Esegui la migrazione del codice con il traduttore SQL batch

Per le nuove traduzioni, ti consigliamo di utilizzare l'API di traduzione per tradurre i tuoi script SQL. L'API di traduzione funziona in modo molto simile al traduttore SQL batch, ma senza la necessità di installare o utilizzare un codice client.

Questo documento descrive come utilizzare il traduttore SQL batch in BigQuery per tradurre script scritti in altri dialetti SQL in query GoogleSQL. Questo documento è rivolto agli utenti che conoscono la console Google Cloud.

Prima di iniziare

Prima di inviare un job di traduzione, completa i seguenti passaggi:

  1. Assicurati di disporre di tutte le autorizzazioni richieste.
  2. Abilitare l'API BigQuery Migration.
  3. Raccogli i file sorgente contenenti le query e gli script SQL da tradurre.
  4. Facoltativo. Crea un file di metadati per migliorare la precisione della traduzione.
  5. Facoltativo. Decidi se devi mappare i nomi degli oggetti SQL nei file di origine a nuovi nomi in BigQuery. Determina quali regole di mappatura dei nomi utilizzare se necessario.
  6. Decidi quale metodo utilizzare per inviare il job di traduzione.
  7. Caricare i file di origine in Cloud Storage.

Autorizzazioni obbligatorie

Per abilitare BigQuery Migration Service, devi disporre delle seguenti autorizzazioni sul progetto:

  • resourcemanager.projects.get
  • serviceusage.services.enable
  • serviceusage.services.get

Per accedere al servizio di migrazione BigQuery e utilizzarlo, devi disporre delle seguenti autorizzazioni sul progetto:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get
  • bigquerymigration.subtasks.list

    In alternativa, puoi utilizzare i seguenti ruoli per ottenere le stesse autorizzazioni:

    • bigquerymigration.viewer - Accesso di sola lettura.
    • bigquerymigration.editor - Accesso in lettura/scrittura.

Per accedere ai bucket Cloud Storage per i file di input e di output:

  • storage.objects.get nel bucket Cloud Storage di origine.
  • storage.objects.list nel bucket Cloud Storage di origine.
  • storage.objects.create nel bucket Cloud Storage di destinazione.

Puoi disporre di tutte le autorizzazioni Cloud Storage necessarie sopra dai ruoli seguenti:

  • roles/storage.objectAdmin
  • roles/storage.admin

Abilita l'API BigQuery Migration

Se il tuo progetto Google Cloud CLI è stato creato prima del 15 febbraio 2022, abilita l'API BigQuery Migration come segue:

  1. Nella console Google Cloud, vai alla pagina dell'API BigQuery Migration.

    Vai all'API BigQuery Migration

  2. Fai clic su Abilita.

Raccogliere i file di origine

I file di origine devono essere file di testo contenenti codice SQL valido per il dialetto di origine. I file di origine possono includere anche commenti. Assicurati che l'SQL sia valido, usando i metodi a tua disposizione.

Creare file di metadati

Per consentire al servizio di generare risultati di traduzione più accurati, ti consigliamo di fornire file di metadati. Tuttavia, questo non è obbligatorio.

Puoi utilizzare lo strumento di estrazione a riga di comando dwh-migration-dumper per generare le informazioni sui metadati oppure puoi fornire i tuoi file di metadati. Una volta preparati i file di metadati, puoi includerli insieme ai file di origine nella cartella di origine della traduzione. Il traduttore li rileva automaticamente e li utilizza per tradurre i file sorgente.

Per generare informazioni sui metadati utilizzando lo strumento dwh-migration-dumper, consulta Generare metadati per la traduzione.

Per fornire i tuoi metadati, raccogli le istruzioni DDL (Data Definition Language) per gli oggetti SQL nel sistema di origine in file di testo separati.

Mappa i nomi degli oggetti SQL

Facoltativamente, puoi eseguire la mappatura dei nomi dell'output durante la traduzione batch. Quando utilizzi la mappatura dei nomi di output, specifica regole di mappatura dei nomi che modificano i nomi degli oggetti SQL nel sistema di origine con nuovi nomi in BigQuery. Ad esempio, potresti avere l'oggetto schema1.table1 nel sistema di origine e vuoi che quell'oggetto abbia il nome project1.dataset1.table1 in BigQuery. Se usi la mappatura dei nomi di output, devi definire le regole di mappatura dei nomi prima di avviare un job di traduzione batch. Puoi inserire queste regole manualmente durante la configurazione del job oppure creare un file JSON contenente le regole di mappatura dei nomi e caricarlo.

Decidi come inviare il job di traduzione

Hai a disposizione tre opzioni per inviare un job di traduzione batch:

  • Client di traduzione batch: configura un job modificando le impostazioni in un file di configurazione e invia il job utilizzando la riga di comando. Questo approccio non richiede il caricamento manuale dei file di origine su Cloud Storage. Il client utilizza comunque Cloud Storage per archiviare i file durante l'elaborazione del job di traduzione.

    Il client di traduzione batch è un client Python open source che ti consente di tradurre i file di origine che si trovano sulla tua macchina locale e di fare in modo che i file tradotti vengano restituiti in una directory locale. Per configurare il client per l'utilizzo di base, modifica alcune impostazioni nel suo file di configurazione. Se vuoi, puoi anche configurare il client per gestire attività più complesse come la sostituzione di macro e la pre- e post-elaborazione degli input e degli output di traduzione. Per ulteriori informazioni, consulta readme del client di traduzione batch.

  • Console Google Cloud: configura e invia un job utilizzando un'interfaccia utente. Questo approccio richiede il caricamento dei file di origine in Cloud Storage.

Creare file YAML di configurazione

Facoltativamente, puoi creare e utilizzare file YAML di configurazione di configurazione per personalizzare le traduzioni batch. Puoi usare questi file per trasformare l'output della traduzione in vari modi. Ad esempio, puoi creare un file YAML di configurazione per cambiare le maiuscole/minuscole di un oggetto SQL durante la traduzione.

Se vuoi utilizzare la console Google Cloud o l'API BigQuery Migration per un job di traduzione batch, puoi caricare il file YAML di configurazione nel bucket Cloud Storage contenente i file di origine.

Se vuoi utilizzare il client di traduzione batch, puoi inserire il file YAML di configurazione nella cartella di input della traduzione locale.

Carica i file di input su Cloud Storage

Se vuoi utilizzare la console Google Cloud o l'API BigQuery Migration per eseguire un job di traduzione, devi caricare i file di origine contenenti le query e gli script da tradurre in Cloud Storage. Puoi anche caricare qualsiasi file di metadati o file YAML di configurazione nello stesso bucket Cloud Storage contenente i file di origine. Per ulteriori informazioni sulla creazione di bucket e sul caricamento di file in Cloud Storage, consulta Creare bucket e Caricare oggetti da un file system.

Dialetti SQL supportati

Il traduttore SQL batch fa parte di BigQuery Migration Service. Il traduttore SQL batch può tradurre i seguenti dialetti SQL in GoogleSQL:

  • SQL di Amazon Redshift
  • Interfaccia a riga di comando Apache HiveQL e Beeline
  • IBM Netezza SQL e NZPLSQL
  • Teradata e Teradata Vantage
    • SQL
    • Query Teradata di base (BTEQ)
    • Teradata Parallel Transport (TPT)

Inoltre, la traduzione dei seguenti dialetti SQL è supportata in anteprima:

  • Apache Spark SQL
  • T-SQL di Azure Synapse
  • SQL Greenplum
  • SQL IBM DB2
  • SQL MySQL
  • Oracle SQL, PL/SQL, Exadata
  • SQL PostgreSQL
  • Trino o PrestoSQL
  • SQL Snowflake
  • T-SQL per SQL Server
  • SQLite
  • SQL vertica

Località

Il traduttore SQL batch è disponibile nelle seguenti località di elaborazione:

Descrizione regione Nome regione Dettagli
Asia Pacifico
Tokyo asia-northeast1
Mumbai asia-south1
Singapore asia-southeast1
Sydney australia-southeast1
Europa
Multiregionale UE eu
Varsavia europe-central2
Finlandia europe-north1 icona foglia A basse emissioni di CO2
Madrid europe-southwest1
Belgio europe-west1 icona foglia A basse emissioni di CO2
Londra europe-west2 icona foglia A basse emissioni di CO2
Francoforte europe-west3 icona foglia A basse emissioni di CO2
Paesi Bassi europe-west4
Zurigo europe-west6 icona foglia A basse emissioni di CO2
Parigi europe-west9 icona foglia A basse emissioni di CO2
Torino europe-west12
Americhe
San Paolo southamerica-east1 icona foglia A basse emissioni di CO2
Stati Uniti (più regioni) us
Iowa us-central1 icona foglia A basse emissioni di CO2
Carolina del Sud us-east1
Virginia del Nord us-east4
Columbus, Ohio us-east5
Dallas us-south1
Oregon us-west1 icona foglia A basse emissioni di CO2
Los Angeles us-west2
Salt Lake City us-west3

Inviare un job di traduzione

Segui questi passaggi per avviare un job di traduzione, visualizzarne l'avanzamento e vedere i risultati.

Client di traduzione batch

  1. Installa il client di traduzione batch e Google Cloud CLI.

  2. Genera un file di credenziali gcloud CLI gcloud.

  3. Nella directory di installazione del client di traduzione batch, utilizza l'editor di testo di tua scelta per aprire il file config.yaml e modificare le seguenti impostazioni:

    • project_number: digita il numero del progetto da utilizzare per il job di traduzione batch. Puoi trovare queste informazioni nel riquadro Informazioni sul progetto nella pagina di benvenuto della console Google Cloud relativa al progetto.
    • gcs_bucket: digita il nome del bucket Cloud Storage che il client di traduzione batch deve utilizzare per archiviare i file durante l'elaborazione del job di traduzione.
    • input_directory: digita il percorso assoluto o relativo della directory contenente i file di origine ed eventuali file di metadati.
    • output_directory: digita il percorso assoluto o relativo della directory di destinazione per i file tradotti.
  4. Salva le modifiche e chiudi il file config.yaml.

  5. Inserisci i file di origine e di metadati nella directory di input.

  6. Esegui il client di traduzione batch utilizzando questo comando:

    bin/dwh-migration-client
    

    Una volta creato il job di traduzione, puoi visualizzarne lo stato nell'elenco dei job di traduzione della console Google Cloud.

  7. Facoltativo. Una volta completato il job di traduzione, elimina i file che il job ha creato nel bucket Cloud Storage specificato, per evitare costi di archiviazione.

Console

Questi passaggi presuppongono che i file di origine siano già caricati in un bucket Cloud Storage.

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.

  3. Fai clic su Avvia traduzione.

  4. Compila la finestra di dialogo di configurazione della traduzione.

    1. In Nome visualizzato, digita un nome per il job di traduzione. Il nome può contenere lettere, numeri o trattini bassi.
    2. In Località di elaborazione, seleziona la località in cui vuoi eseguire il job di traduzione. Ad esempio, se ti trovi in Europa e non vuoi che i tuoi dati superino i confini delle località, seleziona la regione eu. Il job di traduzione ha le prestazioni migliori quando scegli la stessa località del bucket di file di origine.
    3. Per Dialetto di origine, seleziona il dialetto SQL che vuoi tradurre.
    4. Per Dialetto di destinazione, seleziona BigQuery.
  5. Fai clic su Avanti.

  6. In Posizione di origine, specifica il percorso della cartella di Cloud Storage contenente i file da tradurre. Puoi digitare il percorso nel formato bucket_name/folder_name/ o utilizzare l'opzione Sfoglia.

  7. Fai clic su Avanti.

  8. In Località di destinazione, specifica il percorso della cartella Cloud Storage di destinazione per i file tradotti. Puoi digitare il percorso nel formato bucket_name/folder_name/ o utilizzare l'opzione Sfoglia.

  9. Se esegui traduzioni per cui non è necessario specificare nomi degli oggetti predefiniti o la mappatura dei nomi da origine a destinazione, vai al passaggio 11. In caso contrario, fai clic su Avanti.

  10. Compila le impostazioni facoltative di cui hai bisogno.

    1. Facoltativo. In Database predefinito, digita un nome di database predefinito da utilizzare con i file di origine. Il traduttore utilizza questo nome predefinito del database per risolvere i nomi completi degli oggetti SQL in cui manca il nome del database.

    2. Facoltativo. Per Percorso di ricerca schema, specifica uno schema in cui cercare quando il traduttore deve risolvere i nomi completi degli oggetti SQL nei file di origine in cui manca il nome dello schema. Se i file di origine utilizzano nomi di schema diversi, fai clic su Add Schema Name (Aggiungi nome schema) e aggiungi un valore per ogni nome di schema a cui potrebbe essere fatto riferimento.

      Il traduttore cerca nei file di metadati che hai fornito per convalidare le tabelle con i nomi degli schemi. Se non è possibile determinare un'opzione definita dai metadati, viene utilizzato per impostazione predefinita il primo nome dello schema inserito. Per maggiori informazioni su come viene utilizzato il nome dello schema predefinito, consulta la sezione Schema predefinito.

    3. Facoltativo. Se vuoi specificare regole di mappatura dei nomi per rinominare gli oggetti SQL tra il sistema di origine e BigQuery durante la traduzione, puoi fornire un file JSON con la coppia di mappatura dei nomi oppure puoi utilizzare la console Google Cloud per specificare i valori da mappare.

      Per utilizzare un file JSON:

      1. Fai clic su Carica un file JSON per la mappatura dei nomi.
      2. Individua la posizione di un file di mapping dei nomi nel formato appropriato, selezionalo e fai clic su Apri.

        Tieni presente che le dimensioni del file devono essere inferiori a 5 MB.

      Per utilizzare la console Google Cloud:

      1. Fai clic su Aggiungi coppia di mapping dei nomi.
      2. Aggiungi le parti appropriate del nome dell'oggetto di origine nei campi Database, Schema, Relazione e Attributo nella colonna Origine.
      3. Aggiungi le parti del nome dell'oggetto di destinazione in BigQuery nei campi della colonna Target.
      4. In Tipo, seleziona il tipo di oggetto che descrive l'oggetto che stai mappando.
      5. Ripeti i passaggi da 1 a 4 finché non avrai specificato tutte le coppie di mappatura dei nomi necessarie. Tieni presente che puoi specificare solo fino a 25 coppie di mappatura dei nomi quando utilizzi la console Google Cloud.
  11. Fai clic su Crea per avviare il job di traduzione.

Una volta creato il job di traduzione, puoi visualizzarne lo stato nell'elenco dei job di traduzione.

Esplora l'output di traduzione

Dopo aver eseguito il job di traduzione, puoi visualizzare le relative informazioni nella console Google Cloud. Se hai utilizzato la console Google Cloud per eseguire il job, puoi visualizzare i risultati del job nel bucket Cloud Storage di destinazione specificato. Se hai utilizzato il client di traduzione batch per eseguire il job, puoi vedere i risultati del job nella directory di output specificata. Il traduttore SQL batch restituisce i seguenti file nella destinazione specificata:

  • I file tradotti.
  • Il report di riepilogo della traduzione in formato CSV.
  • Il mapping del nome di output utilizzato in formato JSON.

Output della console Google Cloud

Per visualizzare i dettagli del job di traduzione, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.

  3. Nell'elenco dei job di traduzione, individua il job per cui vuoi visualizzare i dettagli della traduzione. Quindi, fai clic sul nome del job di traduzione.

  4. Nella sezione Risultati puoi vedere la percentuale di successo complessiva della traduzione, il numero di istruzioni elaborate e la durata del job.

  5. Seleziona la scheda Riepilogo log per visualizzare un riepilogo dei problemi di traduzione, incluse le categorie dei problemi, le azioni suggerite e la frequenza con cui si sono verificati i singoli problemi. Puoi anche selezionare una categoria di problema per visualizzare i messaggi di log associati a quella categoria (Anteprima).

  6. Seleziona la scheda Messaggi di log per visualizzare ulteriori dettagli su ogni problema di traduzione, tra cui la categoria di problema, il messaggio relativo al problema specifico e un link al file in cui si è verificato il problema. Puoi selezionare un problema nella scheda Messaggio di log per aprire la scheda Codice che mostra il file di input e output, se applicabile (Anteprima).

  7. Seleziona la scheda Configurazione di traduzione per visualizzare i dettagli di configurazione del job di traduzione.

Rapporto riepilogativo

Il report di riepilogo è un file CSV contenente una tabella di tutti i messaggi di avviso ed errore riscontrati durante il job di traduzione.

Per visualizzare il file di riepilogo nella console Google Cloud:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.

  3. Nell'elenco dei job di traduzione, individua il job che ti interessa e fai clic su Mostra dettagli nella colonna Stato.

  4. Nella sezione Report sulla traduzione, fai clic su batch_translation_report.csv.

  5. Nella pagina Dettagli oggetto, fai clic sul valore nella riga URL autenticato per visualizzare il file nel tuo browser.

Nella tabella seguente vengono descritte le colonne dei file di riepilogo:

Colonna Descrizione
Timestamp Il timestamp in cui si è verificato il problema.
FilePath Il percorso del file di origine a cui è associato il problema.
FileName Il nome del file di origine a cui è associato il problema.
ScriptLine Il numero di riga in cui si è verificato il problema.
ScriptColumn Il numero di colonna in cui si è verificato il problema.
TranspilerComponent Il componente interno del motore di traduzione in cui si è verificato l'avviso o l'errore. Questa colonna potrebbe essere vuota.
Ambiente L'ambiente del dialetto di traduzione associato all'avviso o all'errore. Questa colonna potrebbe essere vuota.
ObjectName L'oggetto SQL nel file di origine associato all'avviso o all'errore. Questa colonna potrebbe essere vuota.
Gravità Gravità del problema (avviso o errore).
Categoria La categoria di problemi della traduzione.
SourceType L'origine del problema. Il valore in questa colonna può essere SQL, che indica un problema nei file SQL di input, oppure METADATA, che indica un problema nel pacchetto di metadati.
Messaggio L'avviso relativo al problema di traduzione o il messaggio di errore.
ScriptContext Lo snippet SQL nel file di origine associato al problema.
Azione L'azione che ti consigliamo di eseguire per risolvere il problema.

Scheda Codice

La scheda Codice consente di rivedere ulteriori informazioni sui file di input e output per un particolare job di traduzione. Nella scheda Codice, puoi esaminare i file utilizzati in un job di traduzione, esaminare un confronto affiancato di un file di input e la sua traduzione per individuare eventuali inesattezze e visualizzare riepiloghi di log e messaggi per un file specifico in un job.

Per accedere alla scheda Codice, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.

  3. Nell'elenco dei job di traduzione, individua il job che ti interessa, quindi fai clic su Mostra dettagli nella colonna Stato.

  4. Seleziona Scheda Codice.

File di mapping dei nomi di output utilizzato

Questo file JSON contiene le regole di mappatura dei nomi di output utilizzate dal job di traduzione. Le regole in questo file potrebbero differire dalle regole di mappatura dei nomi di output specificate per il job di traduzione, a causa di conflitti nelle regole di mappatura dei nomi o della mancanza di regole di mappatura dei nomi per gli oggetti SQL identificati durante la traduzione. Esamina questo file per determinare se le regole di mappatura dei nomi devono essere corrette. In caso affermativo, crea nuove regole di mappatura dei nomi di output che risolvano gli eventuali problemi identificati ed esegui un nuovo job di traduzione.

File tradotti

Per ogni file di origine, nel percorso di destinazione viene generato un file di output corrispondente. Il file di output contiene la query tradotta.

Esegui il debug delle query SQL tradotte in batch con il traduttore SQL interattivo

Puoi utilizzare il traduttore SQL interattivo BigQuery per esaminare o eseguire il debug di una query SQL utilizzando gli stessi metadati o informazioni di mappatura degli oggetti del database di origine. Dopo che hai completato un job di traduzione batch, BigQuery genera un ID configurazione della traduzione contenente informazioni sui metadati del job, sulla mappatura degli oggetti o sul percorso di ricerca dello schema, a seconda dei casi. Puoi usare l'ID configurazione della traduzione batch con il traduttore SQL interattivo per eseguire query SQL con la configurazione specificata.

Per avviare una traduzione SQL interattiva utilizzando un ID configurazione della traduzione batch, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nella sezione Migrazione del menu di navigazione, fai clic su Traduzione SQL.

  3. Nell'elenco dei job di traduzione, individua il job che ti interessa, quindi fai clic su Altre opzioni > Apri traduzione interattiva.

Si apre il traduttore SQL interattivo BigQuery con l'ID configurazione della traduzione batch corrispondente. Per visualizzare l'ID di configurazione della traduzione per la traduzione interattiva, fai clic su Altro > Impostazioni di traduzione nel traduttore interattivo.

Limitazioni

Il traduttore non può tradurre le funzioni definite dall'utente da linguaggi diversi da SQL, perché non può analizzarle per determinare i tipi di dati di input e output. per cui la traduzione delle istruzioni SQL che fanno riferimento a queste funzioni definite dall'utente non è precisa. Per assicurarti che alle funzioni definite dall'utente non SQL venga fatto riferimento correttamente durante la traduzione, utilizza un codice SQL valido per creare funzioni definite dall'utente segnaposto con le stesse firme.

Ad esempio, supponiamo di avere una funzione definita dall'utente scritta in C che calcola la somma di due numeri interi. Per assicurarti che le istruzioni SQL che fanno riferimento a questa funzione definita dall'utente vengano tradotte correttamente, crea una funzione SQL segnaposto che condivida la stessa firma della UDF C, come mostrato nell'esempio seguente:

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

Salva questa funzione definita dall'utente segnaposto in un file di testo e includi il file come uno dei file di origine per il job di traduzione. Ciò consente al traduttore di apprendere la definizione delle funzioni definite dall'utente e identificare i tipi di dati di input e output previsti.

Quota e limiti

  • Si applicano le quote dell'API BigQuery Migration.
  • Ogni progetto può avere al massimo 10 attività di traduzione attive.
  • Anche se non esiste un limite preciso al numero totale di file di origine e di metadati, ti consigliamo di mantenere il numero di file al di sotto di 1000 per ottenere prestazioni migliori.

Risolvere gli errori di traduzione

Problemi di traduzione in RelationNotFound o AttributeNotFound

La traduzione funziona meglio con i DDL di metadati. Quando non è possibile trovare le definizioni degli oggetti SQL, il motore di traduzione genera problemi RelationNotFound o AttributeNotFound. Consigliamo di utilizzare l'estrattore di metadati per generare pacchetti di metadati e assicurarti che siano presenti tutte le definizioni degli oggetti. L'aggiunta di metadati è il primo passaggio consigliato per risolvere la maggior parte degli errori di traduzione, poiché spesso consente di correggere molti altri errori causati indirettamente dalla mancanza di metadati.

Per saperne di più, consulta Generare metadati per la traduzione e la valutazione.

Prezzi

Non è previsto alcun costo per l'utilizzo del traduttore SQL batch. Tuttavia, l'archiviazione utilizzata per archiviare i file di input e output comporta le normali tariffe. Per maggiori informazioni, vedi Prezzi dell'archiviazione.

Passaggi successivi

Scopri di più sui seguenti passaggi della migrazione del data warehouse: