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 Cloud de Confiance 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: Storage Object Admin (roles/storage.objectAdmin) sul 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.

Utilizza una delle seguenti opzioni per includere un file YAML di configurazione nel job di traduzione.

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-local-dirs=LOCAL_DIR=SOURCE_URI \
  --source-local-files=LOCAL_CONFIG_YAML=CONFIG_YAML_URI \
  --target-gcs-path=TARGET_URI

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:

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

• Google Cloud CLI: invia un job dalla riga di comando utilizzando gcloud CLI. Il comando translate-batch accetta le posizioni di origine e di destinazione come flag e può caricare directory e file locali su Cloud Storage. Per saperne di più, consulta Inviare un lavoro di traduzione.

Entrambe le opzioni richiedono che i file di origine siano accessibili 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 consoleCloud de Confiance .

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.

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-gcs-uris=SOURCE_URI \
    --target-gcs-path=TARGET_URI

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-local-dirs=LOCAL_DIR=SOURCE_URI \
    --target-gcs-path=TARGET_URI

gcloud alpha bq translation describe TRANSLATION_ID \
    --location=LOCATION

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

Tradurre i metadati

Oltre a tradurre gli script SQL, puoi tradurre i metadati che descrivono il data warehouse di origine. Un job di conversione dei metadati legge i file di metadati estratti dal sistema di origine e scrive istruzioni Data Definition Language (DDL) GoogleSQL che ricreano questi oggetti in BigQuery.

L'input è costituito da uno o più file ZIP di metadati. Per scoprire come produrre questi file con lo strumento dwh-migration-dumper, consulta Generare metadati per la traduzione.

Puoi tradurre i metadati utilizzando la console Cloud de Confiance o gcloud CLI. Seleziona una delle seguenti opzioni:

gcloud alpha bq translation translate-metadata \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI \
  --target-types=sql,metadata

Genera DDL dell'origine

Quando l'SQL di origine fa riferimento a tabelle di cui non disponi delle definizioni, il traduttore non sempre riesce a risolvere gli oggetti, il che comporta problemi di RelationNotFound o AttributeNotFound.

Il modo migliore per risolvere questi problemi è fornire le definizioni reali degli oggetti di origine. Esegui lo strumento dwh-migration-dumper sul sistema di origine e includi il file ZIP dei metadati risultante negli input di traduzione. Per istruzioni, vedi Generare metadati per la traduzione. I metadati estratti descrivono esattamente gli oggetti, quindi il traduttore li risolve senza congetture.

Se non riesci a estrarre i metadati, ad esempio quando non hai più accesso al sistema di origine, puoi chiedere a Gemini di dedurre le istruzioni DDL mancanti dall'SQL di origine. Gemini deduce queste istruzioni DDL dal modo in cui gli oggetti vengono utilizzati nelle query, quindi rivedi e verifica sempre queste istruzioni prima di utilizzarle.

Puoi generare il DDL di origine per le traduzioni utilizzando la consoleCloud de Confiance o gcloud CLI. Seleziona una delle seguenti opzioni:

gcloud alpha bq translation generate-source-ddl \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Puoi quindi fornire le istruzioni DDL generate come input a un successivo job di traduzione per migliorare la qualità della traduzione. Per saperne di più, consulta Problemi di traduzione di RelationNotFound o AttributeNotFound.

Esplora l'output della traduzione

Puoi esaminare i risultati di un job di traduzione nella console Cloud de Confiance , indipendentemente dal fatto che il job sia stato inviato dalla riga di comando o dalla console Cloud de Confiance . 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.

Output della consoleCloud de Confiance

Per visualizzare i dettagli del lavoro di traduzione:

1. Nella console Cloud de Confiance , 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 ulteriori problemi 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 Cloud de Confiance , segui questi passaggi:

1. Nella console Cloud de Confiance , 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 di 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 Cloud de Confiance , 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 Cloud de Confiance , 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.<dataset>.<function>(). 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 è in linea con 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.

Puoi eseguire il debug delle query SQL tradotte in batch utilizzando la consoleCloud de Confiance o gcloud CLI. Seleziona una delle seguenti opzioni:

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE \
  --output-file=OUTPUT_FILE \
  --translation-log-file=LOG_FILE \
  --explanation-output-file=EXPLANATION_FILE

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 Cloud de Confiance 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 Generare metadati per la traduzione e la valutazione.

Risolvere i problemi di traduzione con Gemini

Per correggere i lavori 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.

Strumenti a riga di comando per workflow di migrazione alternativi

Puoi anche inviare un job di traduzione batch utilizzando un file di configurazione della traduzione con Google Cloud CLI (gcloud bq migration-workflows) o con lo strumento a riga di comando bq.

Questi passaggi presuppongono che tu abbia caricato i file delle fonti in un bucket Cloud Storage.

Crea un file di configurazione della traduzione

Un file di configurazione della traduzione definisce il percorso dei file di origine, la destinazione di output e i dialetti di origine e di destinazione della traduzione. Puoi scrivere questo file in formato YAML o JSON.

Il seguente esempio mostra un file YAML di configurazione della traduzione per una traduzione da Teradata a BigQuery:

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

L'esempio seguente mostra un file JSON di configurazione della traduzione per una traduzione da Teradata a BigQuery:

{
  "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"
        ]
      }
    }
  }
}

Inviare e gestire i job di traduzione

Utilizza uno dei seguenti strumenti a riga di comando per inviare e gestire i tuoi job di traduzione.

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

Recuperare i file di output

Per scaricare i file di output al termine del job, utilizza gcloud storage cp come descritto in Recuperare i file di output. Per esaminare il job nella console Cloud de Confiance , consulta Esplorare l'output della traduzione.

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