Esegui la migrazione del codice con il traduttore SQL batch

Questo documento descrive come utilizzare il traduttore SQL batch in BigQuery per tradurre script scritti in altri dialetti SQL in query GoogleSQL. Puoi inviare e rivedere i risultati di un job di traduzione dalla console Google Cloud o dalla riga di comando.

Per un elenco dei dialetti SQL supportati da questo traduttore SQL, consulta Dialetti SQL supportati.

Per un elenco delle località di elaborazione supportate, consulta Località.

Prima di iniziare

Prima di inviare un lavoro di traduzione, segui questi passaggi.

Abilitare le traduzioni SQL

Abilita l'API richiesta e ottieni le autorizzazioni necessarie per utilizzare un traduttore SQL BigQuery. Per saperne di più, consulta Attivare le traduzioni SQL.

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per creare job di traduzione con il traduttore interattivo, l'API Translation o il traduttore SQL batch, chiedi all'amministratore di concederti i seguenti ruoli IAM sulla risorsa parent:

• Visualizzazione e monitoraggio dei job di migrazione: Visualizzatore MigrationWorkflow (roles/bigquerymigration.viewer)
• Invio di job di migrazione: Editor MigrationWorkflow (roles/bigquerymigration.editor)
• Accedi ai bucket Cloud Storage per l'input e i file: Amministratore oggetti Storage (roles/storage.objectAdmin) nel bucket Cloud Storage di origine e di destinazione.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare job di traduzione con il traduttore interattivo, l'API Translation o il traduttore SQL batch. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Raccogliere i file di origine

I file di origine devono essere file di testo contenenti SQL valido per il dialetto di origine. I file di origine possono includere anche commenti. Fai del tuo meglio per assicurarti che l'SQL sia valido, utilizzando tutti i metodi a tua disposizione.

Creare file di metadati

Per aiutare il servizio a generare risultati di traduzione più accurati, ti consigliamo di fornire file di metadati. Tuttavia, non è obbligatorio.

Puoi utilizzare lo strumento di estrazione da riga di comando dwh-migration-dumper per generare le informazioni sui metadati. Dopo aver preparato 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 di origine, quindi non devi configurare impostazioni aggiuntive per attivare questa funzionalità.

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

Crea file YAML di configurazione

Se vuoi, puoi creare e utilizzare file YAML di configurazione per personalizzare le traduzioni batch. Questi file possono essere utilizzati per trasformare l'output della traduzione in vari modi. Ad esempio, puoi creare un file YAML di configurazione per modificare le maiuscole e minuscole di un oggetto SQL durante la traduzione.

Per utilizzare un file YAML di configurazione, caricalo nel bucket Cloud Storage contenente i file di origine.

Carica i file di input su Cloud Storage

Carica su Cloud Storage i file di origine contenenti le query e gli script che vuoi tradurre. Puoi anche caricare qualsiasi file di metadati o file YAML di configurazione nello stesso bucket Cloud Storage e nella stessa directory contenenti i file di origine. Per saperne di più sulla creazione di bucket e sul caricamento di file in Cloud Storage, consulta Creare bucket e Caricare oggetti da un file system.

Scegli come inviare il progetto di traduzione

Hai due opzioni per inviare un job di traduzione batch:

• Google Cloud Console: configura e invia un job utilizzando un'interfaccia utente.

• Strumenti a riga di comando: descrivi il job in un file di configurazione della traduzione e invialo con Google Cloud CLI o con lo strumento a riga di comando bq.

Entrambe le opzioni richiedono il caricamento dei file di origine in Cloud Storage ed entrambe creano lo stesso tipo di job di traduzione. Un job che invii dalla riga di comando viene comunque visualizzato nell'elenco dei job di traduzione nella consoleGoogle Cloud .

Inviare un job di traduzione

Utilizza una delle seguenti opzioni per avviare un job di traduzione e visualizzarne l'avanzamento. Per esaminare i risultati in un secondo momento, consulta la sezione Esplorare l'output della traduzione.

tasks:
  translation_task:
    type: Teradata2BigQuery_Translation
    translationDetails:
      sourceTargetMapping:
      - sourceSpec:
          baseUri: gs://bq-translations/input
        targetSpec:
          relativePath: output
      targetBaseUri: gs://bq-translations
      targetTypes:
      - sql
      sourceEnvironment:
        defaultDatabase: default_db
        schemaSearchPath:
        - foo

{
  "tasks": {
    "translation_task": {
      "type": "Teradata2BigQuery_Translation",
      "translationDetails": {
        "sourceTargetMapping": [
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 1",
                "relativePath": "my_input_1"
              },
              "encoding": "UTF-8"
            }
          },
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 2",
                "relativePath": "my_input_2"
              },
              "encoding": "UTF-8"
            }
          }
        ],
        "targetReturnLiterals": [
          "sql/my_input_1",
          "sql/my_input_2"
        ]
      }
    }
  }
}

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async

gcloud bq migration-workflows list --location=LOCATION

gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE

bq ls --migration_workflow --location=LOCATION

bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

Esplora l'output della traduzione

Puoi esaminare i risultati di un job di traduzione nella console Google Cloud , indipendentemente dal fatto che il job sia stato inviato dalla riga di comando o dalla console Google Cloud . Il traduttore SQL batch genera i seguenti file nella destinazione specificata:

• I file tradotti.
• Il report di riepilogo della traduzione in formato CSV.
• I file di suggerimenti dell'AI.

Google Cloud console output

Per visualizzare i dettagli del lavoro di traduzione:

1. Nella console Google Cloud , vai alla pagina SQL Translation.

   Vai a Traduzione SQL

2. Nell'elenco dei job di traduzione, individua quello di cui vuoi visualizzare i dettagli. Poi, fai clic sul nome del job di traduzione. Puoi visualizzare una visualizzazione Sankey che illustra la qualità complessiva del job, il numero di righe di codice di input (escluse le righe vuote e i commenti) e un elenco dei problemi che si sono verificati durante il processo di traduzione. Devi dare la priorità alle correzioni da sinistra a destra. I problemi in una fase iniziale possono causare problemi aggiuntivi nelle fasi successive.

3. Tieni il puntatore sopra le barre di errore o avviso ed esamina i suggerimenti per determinare i passaggi successivi per il debug del job di traduzione.

4. Seleziona la scheda Riepilogo log per visualizzare un riepilogo dei problemi di traduzione, incluse le categorie di problemi, le azioni suggerite e la frequenza con cui si è verificato ciascun problema. Puoi fare clic sulle barre della visualizzazione Sankey per filtrare i problemi. Puoi anche selezionare una categoria di problemi per visualizzare i messaggi di log associati a quella categoria.

5. Seleziona la scheda Messaggi di log per visualizzare ulteriori dettagli su ogni problema di traduzione, tra cui la categoria del problema, il messaggio di errore specifico e un link al file in cui si è verificato il problema. Puoi fare clic sulle barre della visualizzazione Sankey per filtrare i problemi. Puoi selezionare un problema nella scheda Messaggio di log per aprire la scheda Codice che mostra il file di input e di output, se applicabile.

6. Fai clic sulla scheda Dettagli job per visualizzare i dettagli di configurazione del job di traduzione.

Rapporto riepilogativo

Il report di riepilogo è un file CSV che contiene 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 , segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina SQL Translation.

   Vai a Traduzione SQL

2. Nell'elenco dei job di traduzione, individua quello che ti interessa, quindi fai clic sul nome del job o su Altre opzioni > Mostra dettagli.

3. Nella scheda Dettagli job, nella sezione Report di traduzione, fai clic su translation_report.csv.

4. Nella pagina Dettagli oggetto, fai clic sul valore nella riga URL di autenticazione per visualizzare il file nel browser.

La tabella seguente descrive le colonne del file di riepilogo:

Scheda Codice

La scheda Codice ti consente di esaminare ulteriori informazioni sui file di input e output per un determinato job di traduzione. Nella scheda del codice puoi esaminare i file utilizzati in un job di traduzione, rivedere un confronto fianco a fianco di un file di input e della relativa traduzione per eventuali imprecisioni e visualizzare i riepiloghi e i messaggi dei log per un file specifico in un job.

Per accedere alla scheda del codice:

1. Nella console Google Cloud , vai alla pagina SQL Translation.

   Vai a Traduzione SQL

2. Nell'elenco dei job di traduzione, individua quello che ti interessa, quindi fai clic sul nome del job o su Altre opzioni > Mostra dettagli.

3. Seleziona la scheda Codice. La scheda Codice è costituita dai seguenti riquadri:

   

   • Esplora file: contiene tutti i file SQL utilizzati per la traduzione. Fai clic su un file per visualizzare l'input e l'output della traduzione, nonché eventuali problemi di traduzione.
   • Input ottimizzato con Gemini: l'SQL di input tradotto dal motore di traduzione. Se hai specificato regole di personalizzazione di Gemini per l'SQL di origine nella configurazione di Gemini, il traduttore trasforma prima l'input originale e poi traduce l'input ottimizzato con Gemini. Per visualizzare l'input originale, fai clic su Visualizza input originale.
   • Output della traduzione: il risultato della traduzione. Se hai specificato regole di personalizzazione di Gemini per l'SQL di destinazione nella configurazione di Gemini, la trasformazione viene applicata al risultato tradotto come output ottimizzato con Gemini. Se è disponibile un output migliorato con Gemini, puoi fare clic sul pulsante Suggerimento di Gemini per esaminarlo.

4. (Facoltativo) Per visualizzare un file di input e il relativo file di output nel traduttore SQL interattivo di BigQuery, fai clic su Modifica. Puoi modificare i file e salvare il file di output di nuovo in Cloud Storage.

Scheda Configurazione

Puoi aggiungere, rinominare, visualizzare o modificare i file YAML di configurazione nella scheda Configurazione. Esplora schema mostra la documentazione per i tipi di configurazione supportati per aiutarti a scrivere i file YAML di configurazione. Dopo aver modificato i file YAML di configurazione, puoi eseguire di nuovo il job per utilizzare la nuova configurazione.

Per accedere alla scheda di configurazione:

1. Nella console Google Cloud , vai alla pagina SQL Translation.

   Vai a Traduzione SQL

2. Nell'elenco dei job di traduzione, individua quello che ti interessa, quindi fai clic sul nome del job o su Altre opzioni > Mostra dettagli.

3. Nella finestra Dettagli traduzione, fai clic sulla scheda Configurazione.

Per aggiungere un nuovo file di configurazione:

1. Fai clic su more_vert Altre opzioni > Crea file YAML di configurazione.
2. Viene visualizzato un riquadro in cui puoi scegliere il tipo, la posizione e il nome del nuovo file YAML di configurazione.
3. Fai clic su Crea.

Per modificare un file di configurazione esistente:

1. Fai clic sul file YAML di configurazione.
2. Modifica il file, quindi fai clic su Salva.
3. Fai clic su Esegui di nuovo per eseguire un nuovo job di traduzione che utilizza i file YAML di configurazione modificati.

Puoi rinominare un file di configurazione esistente facendo clic su more_vert Altre opzioni > Rinomina.

File tradotti

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

Gestione delle funzioni SQL non supportate con le funzioni definite dall'utente di assistenza

Quando traduci SQL da un dialetto di origine a BigQuery, alcune funzioni potrebbero non avere un equivalente diretto. Per risolvere questo problema, BigQuery Migration Service (e la community BigQuery più ampia) forniscono funzioni definite dall'utente (UDF) di assistenza che replicano il comportamento di queste funzioni del dialetto di origine non supportate.

Queste UDF si trovano spesso nel set di dati pubblico bqutil, consentendo alle query tradotte di farvi riferimento inizialmente utilizzando il formato bqutil..(). Ad esempio: bqutil.fn.cw_count().

Considerazioni per gli ambienti di produzione

Sebbene bqutil offra un accesso comodo a queste UDF helper per la traduzione e il test iniziali, l'utilizzo diretto di bqutil per i workload di produzione non è consigliato per i seguenti motivi:

1. Controllo della versione: il progetto bqutil ospita l'ultima versione di queste UDF, il che significa che le loro definizioni possono cambiare nel tempo. L'utilizzo diretto di bqutil potrebbe comportare un comportamento imprevisto o modifiche che causano errori nelle query di produzione se la logica di una UDF viene aggiornata.
2. Isolamento delle dipendenze: il deployment delle UDF nel tuo progetto isola l'ambiente di produzione da modifiche esterne.
3. Personalizzazione: potresti dover modificare o ottimizzare queste UDF per adattarle meglio alla tua logica di business o ai tuoi requisiti di rendimento specifici. Questo è possibile solo se si trovano all'interno del tuo progetto.
4. Sicurezza e governance: le norme di sicurezza della tua organizzazione potrebbero limitare l'accesso diretto a set di dati pubblici come bqutil per l'elaborazione dei dati di produzione. La copia delle UDF nell'ambiente controllato è conforme a queste norme.

Deployment delle UDF helper nel progetto

Per darti il controllo completo su versione, personalizzazione e accesso alle funzioni definite dall'utente, ti consigliamo di eseguire il deployment delle funzioni helper definite dall'utente nel tuo progetto e nel tuo set di dati per un utilizzo di produzione affidabile e stabile. Per saperne di più sugli script e sui passaggi necessari per il deployment delle UDF helper nel tuo ambiente, consulta Deployment delle UDF.

Risoluzione dei problemi

Questa sezione descrive come eseguire il debug delle singole query e come risolvere gli errori di traduzione più comuni.

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

Puoi utilizzare il traduttore SQL interattivo di BigQuery per esaminare o eseguire il debug di una query SQL utilizzando le stesse informazioni di mapping di metadati o oggetti del database di origine. Dopo aver completato un job di traduzione batch, BigQuery genera un ID configurazione di traduzione che contiene informazioni sui metadati del job, sul mapping degli oggetti o sul percorso di ricerca dello schema, a seconda dei casi per la query. Utilizzi 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 di traduzione batch, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina SQL Translation.

   Vai a Traduzione SQL

2. Nell'elenco dei lavori di traduzione, individua quello che ti interessa, quindi fai clic su more_vert Altre opzioni > Apri traduzione interattiva.

   Il traduttore SQL interattivo di BigQuery ora si apre con l'ID configurazione di traduzione batch corrispondente. Per visualizzare l'ID configurazione della traduzione per la traduzione interattiva, fai clic su Strumenti > Traduzione query > Impostazioni di traduzione nel traduttore SQL interattivo.

Per eseguire il debug di un file di traduzione batch nel traduttore SQL interattivo:

1. Nella console Google Cloud , vai alla pagina SQL Translation.

   Vai a Traduzione SQL

2. Nell'elenco dei job di traduzione, individua quello che ti interessa, quindi fai clic sul nome del job o su Altre opzioni > Mostra dettagli.

3. Nella finestra Dettagli traduzione, fai clic sulla scheda Codice.

4. In Esplora file, fai clic sul nome del file per aprirlo.

5. Accanto al nome del file di output, fai clic su Modifica per aprire i file nel traduttore SQL interattivo (anteprima).

   Vedi i file di input e output compilati nel traduttore SQL interattivo, che ora utilizza l'ID configurazione della traduzione batch corrispondente.

6. Per salvare il file di output modificato in Cloud Storage, nel traduttore SQL interattivo fai clic su Salva > Salva in GCS.

Risolvere gli errori di traduzione

Le sezioni seguenti descrivono gli errori più comuni riscontrati durante l'utilizzo del traduttore SQL batch.

Problemi di traduzione di RelationNotFound o AttributeNotFound

Dopo aver tradotto una query utilizzando il traduttore SQL batch, potresti riscontrare una traduzione non riuscita con l'errore RelationNotFound o AttributeNotFound.

Puoi trovare le traduzioni non riuscite andando alla pagina Dettagli traduzione in BigQuery nella console Google Cloud e aprendo la scheda Messaggi di log.

La traduzione funziona meglio con DDL di metadati. Quando non è possibile trovare le definizioni degli oggetti SQL, il motore di traduzione genera problemi RelationNotFound o AttributeNotFound. Ti consigliamo di utilizzare lo strumento di estrazione dei metadati per generare pacchetti di metadati per 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, perché questo passaggio spesso corregge molti altri errori causati indirettamente dalla mancanza di metadati.

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

Risolvere i problemi di traduzione con Gemini

Per correggere i job di traduzione non riusciti con gli errori RelationNotFound o AttributeNotFound, puoi anche utilizzare Gemini per risolvere questi problemi:

1. Vai alla pagina Dettagli traduzione e apri la scheda Messaggi di log.
2. Fai clic sulla query con il messaggio RelationNotFound o AttributeNotFound nella colonna Categoria.

3. Per andare al file e alla riga contenenti l'errore nella scheda Codice, fai clic su

   messaggio di errore.

4. Nella colonna Azione, fai clic su Correzione suggerita.

5. Seleziona una delle seguenti opzioni, Applica o Applica ed esegui di nuovo:

   • Per copiare il file dello schema generato dalla directory di output alla directory di input, fai clic su Applica.
   • Per copiare il file dello schema generato dalla directory di output alla directory di input e aprire una finestra di ripetizione, fai clic su Applica ed esegui di nuovo.

Quota e limiti

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

Prezzi

L'utilizzo del traduttore SQL batch non prevede costi. Tuttavia, lo spazio di archiviazione utilizzato per archiviare i file di input e di output comporta le normali tariffe. Per ulteriori informazioni, consulta la sezione Prezzi dello spazio di archiviazione.

Passaggi successivi

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

• Panoramica della migrazione
• Valutazione della migrazione
• Panoramica dello schema e del trasferimento dei dati
• Pipeline di dati
• Traduzione SQL interattiva
• Sicurezza e governance dei dati
• Strumento di convalida dei dati