Traduci le query con il traduttore SQL interattivo

Questo documento descrive come tradurre una query da un dialetto SQL diverso in una query GoogleSQL utilizzando il traduttore SQL interattivo di BigQuery. Il traduttore SQL interattivo può aiutarti a ridurre il tempo e l'impegno per la migrazione dei workload a BigQuery. Questo documento è rivolto agli utenti che hanno familiarità con la consoleGoogle Cloud o con Google Cloud CLI.

Puoi utilizzare la funzionalità delle regole di traduzione per personalizzare il modo in cui il traduttore SQL interattivo traduce SQL.

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 job di traduzione, segui questi passaggi.

Abilita le traduzioni SQL

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

Autorizzazioni obbligatorie

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

  • Visualizzazione e monitoraggio dei job di migrazione: MigrationWorkflow Viewer (roles/bigquerymigration.viewer)
  • Invio di job di migrazione: MigrationWorkflow Editor (roles/bigquerymigration.editor)
  • Accedi ai bucket Cloud Storage per input e file: Amministratore oggetti Storage (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 di traduzione o il traduttore SQL batch. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare job di traduzione con il traduttore interattivo, l'API di traduzione o il traduttore SQL batch, sono necessarie le seguenti autorizzazioni:

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

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

Gestione delle funzioni SQL non supportate con funzioni definite dall'utente helper

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 di BigQuery in generale) fornisce funzioni definite dall'utente (UDF) helper che replicano il comportamento di queste funzioni del dialetto di origine non supportate.

Queste funzioni definite dall'utente 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 importanti per gli ambienti di produzione:

Sebbene bqutil offra un comodo accesso a queste funzioni definite dall'utente di supporto per la traduzione e i test iniziali, l'affidamento diretto a bqutil per i workload di produzione non è consigliato per diversi motivi:

  1. Controllo della versione: il progetto bqutil ospita l'ultima versione di queste funzioni definite dall'utente, il che significa che le relative definizioni possono cambiare nel tempo. Se ti affidi direttamente a bqutil, potresti riscontrare comportamenti imprevisti o modifiche che provocano un errore nelle query di produzione se la logica di una funzione definita dall'utente 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 funzioni definite dall'utente per adattarle meglio alla tua logica di business o ai tuoi requisiti di prestazioni specifici. Questo è possibile solo se si trovano all'interno del tuo progetto.
  4. Sicurezza e governance: le policy di sicurezza della tua organizzazione potrebbero limitare l'accesso diretto ai set di dati pubblici come bqutil per l'elaborazione dei dati di produzione. La copia delle UDF nel tuo ambiente controllato è in linea con queste policy.

Deployment delle funzioni definite dall'utente helper nel progetto:

Per un utilizzo in produzione affidabile e stabile, devi eseguire il deployment di queste funzioni definite dall'utente helper nel tuo progetto e nel tuo set di dati. In questo modo hai il pieno controllo della versione, della personalizzazione e dell'accesso. Per istruzioni dettagliate su come eseguire il deployment di queste UDF, consulta la guida al deployment delle UDF su GitHub. Questa guida fornisce gli script e i passaggi necessari per copiare le funzioni definite dall'utente nel tuo ambiente.

Località

Il traduttore SQL interattivo è disponibile solo in alcune località di elaborazione. Per saperne di più, consulta Località.

Le configurazioni di traduzione basate su Gemini sono disponibili solo in località di elaborazione specifiche. Per saperne di più, consulta Posizioni degli endpoint dei modelli Google

Traduci una query in GoogleSQL

Puoi tradurre una query con la console Google Cloud o con Google Cloud CLI.

Console

Per tradurre una query in GoogleSQL:

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

    Vai a BigQuery

  2. Nel riquadro Editor, fai clic su Strumenti > Impostazioni di traduzione.

  3. In Dialetto di origine, seleziona il dialetto SQL che vuoi tradurre.

  4. Facoltativo. 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 dati superino i confini di località, seleziona la regione eu.

  5. Fai clic su Salva.

  6. Nel riquadro Editor, fai clic su Strumenti > Abilita traduzione SQL.

    Il riquadro Editor si divide in due riquadri.

  7. Nel riquadro a sinistra, inserisci la query che vuoi tradurre.

  8. Fai clic su Traduci.

    BigQuery traduce la query in GoogleSQL e la visualizza nel riquadro a destra. Ad esempio, lo screenshot seguente mostra il codice SQL Teradata tradotto:

    Visualizza una query SQL Teradata tradotta in GoogleSQL

  9. (Facoltativo) Per eseguire la query GoogleSQL tradotta, fai clic su Esegui.

  10. (Facoltativo) Per tornare all'editor SQL, fai clic su Altro > Disabilita traduzione SQL.

    Il riquadro Editor torna ad avere un singolo riquadro.

gcloud

Per tradurre una query da Google Cloud CLI, utilizza il comando gcloud alpha bq translation translate:

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE

Sostituisci quanto segue:

  • SOURCE_DIALECT: il dialetto SQL che vuoi tradurre, ad esempio teradata. Per i valori supportati, consulta Dialetti SQL supportati.
  • TARGET_DIALECT: il dialetto in cui tradurre la query. Ad esempio, bigquery.
  • LOCATION: la località in cui vuoi eseguire il job di traduzione. Ad esempio, se ti trovi in Europa e non vuoi che i dati superino i confini di località, specifica la regione eu.
  • INPUT_FILE: il file locale che contiene la query che vuoi tradurre.

Il comando stampa la query tradotta in gcloud CLI. Per scrivere la query tradotta in un file, aggiungi il flag --output-file.

Per tradurre una query senza creare un file, inviala tramite pipe all'input standard e ometti il flag --input-file:

echo 'SELECT 1;' | gcloud alpha bq translation translate \
  --source-dialect=teradata \
  --target-dialect=bigquery \
  --location=us

Per applicare le personalizzazioni che altrimenti imposteresti in Impostazioni di traduzione, utilizza i seguenti flag:

  • --translation-config-files: un elenco separato da virgole di file YAML di configurazione. I nomi file devono terminare con .config.yaml.
  • --metadata-gcs-uri: l'URI Cloud Storage di un file ZIP di metadati.
  • --explanation-output-file: un file locale che riceve una spiegazione della traduzione generata da Gemini.

Utilizza Gemini con il traduttore SQL interattivo

Puoi configurare il traduttore SQL interattivo per regolare il modo in cui traduce l'SQL di origine. Puoi farlo fornendo le tue regole da utilizzare con Gemini in un file di configurazione YAML o fornendo un file di configurazione YAML contenente metadati degli oggetti SQL o informazioni di mappatura degli oggetti.

Crea e applica regole di traduzione ottimizzate con Gemini

Puoi personalizzare il modo in cui il traduttore SQL interattivo traduce l'SQL creando regole di traduzione. Il traduttore SQL interattivo modifica le traduzioni in base alle regole di traduzione SQL ottimizzate con Gemini che gli assegni, consentendoti di personalizzare i risultati della traduzione in base alle tue esigenze di migrazione.

Per creare una regola di traduzione SQL ottimizzata con Gemini, puoi crearla nella console o creare un file YAML di configurazione e caricarlo su Cloud Storage.

Console

Per creare una regola di traduzione SQL ottimizzata con Gemini per l'SQL di input, scrivi una query SQL di input nell'editor di query, quindi fai clic su ASSIST > Personalizza. (Anteprima)

Personalizza l'input di traduzione

Analogamente, per creare una regola di traduzione SQL ottimizzata con Gemini per l'SQL di output, esegui una traduzione interattiva, quindi fai clic su ASSIST > Personalizza questa traduzione.

Personalizza l'output della traduzione

Quando viene visualizzato il menu Personalizza, continua con i seguenti passaggi.

  1. Utilizza uno o entrambi i seguenti prompt per creare una regola di traduzione:

    • Nel prompt Trova e sostituisci un pattern, specifica un pattern SQL che vuoi sostituire nel campo Sostituisci e un pattern SQL per sostituirlo nel campo Con.

      Un pattern SQL può contenere un numero qualsiasi di istruzioni, clausole o funzioni in uno script SQL. Quando crei una regola utilizzando questo prompt, la traduzione SQL ottimizzata con Gemini identifica tutte le istanze di quel pattern SQL nella query SQL e lo sostituisce dinamicamente con un altro pattern SQL. Ad esempio, puoi utilizzare questo prompt per creare una regola che sostituisce tutte le occorrenze di months_between (X,Y) con date_diff(X,Y,MONTH).

    • Nel campo Descrivi una modifica all'output, digita una modifica all'output di traduzione SQL in linguaggio naturale.

      Quando crei una regola utilizzando questo prompt, la traduzione SQL ottimizzata con Gemini identifica la richiesta e apporta la modifica specificata alla query SQL.

  2. Fai clic su Anteprima.

  3. Nella finestra di dialogo Suggerimenti generati da Gemini, esamina le modifiche apportate dalla traduzione SQL ottimizzata con Gemini alla query SQL in base alla regola.

    Applica modifiche dal file YAML di configurazione basato su Gemini

  4. (Facoltativo) Per aggiungere questa regola da utilizzare con le traduzioni future, seleziona la casella di controllo Salva questo prompt….

    Le regole vengono salvate nel file YAML di configurazione predefinito o in __default.ai_config.yaml. Questo file YAML di configurazione viene salvato nella cartella Cloud Storage come specificato nel campo Posizione di origine della configurazione della traduzione nelle impostazioni di traduzione. Se la posizione di origine della configurazione della traduzione non è già impostata, viene visualizzato un browser delle cartelle che ti consente di selezionarne una. Un file YAML di configurazione è soggetto alle limitazioni relative alle dimensioni dei file di configurazione.

  5. Per applicare le modifiche suggerite alla query SQL, fai clic su Applica.

YAML

Per creare una regola di traduzione SQL ottimizzata con Gemini, puoi creare un file YAML di configurazione basato su Gemini e caricarlo su Cloud Storage. Per saperne di più, consulta Crea un file YAML di configurazione basato su Gemini.

Dopo aver creato una regola di traduzione SQL ottimizzata con Gemini e averla caricata su Cloud Storage, puoi applicarla nel seguente modo:

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

    Vai a BigQuery

  2. Nell'editor di query, fai clic su Strumenti > Impostazioni di traduzione.

  3. Nel campo Posizione di origine della configurazione della traduzione, specifica il percorso del file YAML basato su Gemini archiviato in una cartella Cloud Storage.

  4. Fai clic su Salva.

    Una volta salvata, esegui una traduzione interattiva. Il traduttore interattivo suggerisce modifiche alle traduzioni in base alle regole nel file YAML di configurazione, se disponibile.

Se è disponibile un suggerimento di Gemini per l'input in base alla regola, viene visualizzata la finestra di dialogo Anteprima delle modifiche suggerite, che mostra le possibili modifiche all'input della traduzione. (Anteprima)

Se è disponibile un suggerimento di Gemini per l'output in base alla tua regola, nell'editor di codice viene visualizzato un banner di notifica. Per esaminare e applicare questi suggerimenti:

  1. Fai clic su Assistenza > Visualizza suggerimenti su entrambi i lati dell'editor di codice per rivedere le modifiche suggerite alla query corrispondente.

    Applica modifiche dal file YAML di configurazione basato su Gemini

  2. Nella finestra di dialogo Suggerimenti generati da Gemini, esamina le modifiche apportate da Gemini alla query SQL in base alla regola di traduzione.

  3. Per applicare le modifiche suggerite all'output della traduzione, fai clic su Applica.

Aggiorna il file YAML di configurazione basato su Gemini

Per aggiornare un file YAML di configurazione esistente, segui questi passaggi:

  1. Nella finestra di dialogo Suggerimenti generati in Gemini, fai clic su Visualizza il file di configurazione delle regole Gemini.

  2. Quando viene visualizzato l'editor di configurazione, seleziona il file YAML di configurazione che vuoi modificare.

  3. Apporta la modifica e fai clic su Salva.

  4. Chiudi l'editor YAML facendo clic su Fine.

  5. Esegui una traduzione interattiva per applicare la regola aggiornata.

Spiega una traduzione

Dopo aver eseguito una traduzione interattiva, puoi richiedere una spiegazione del testo generata da Gemini. Il testo generato include un riepilogo della query SQL tradotta. Gemini identifica anche le differenze e le incoerenze di traduzione tra la query SQL di origine e la query GoogleSQL tradotta.

Per ottenere la spiegazione della traduzione SQL generata da Gemini, segui questi passaggi:

  1. Per creare una spiegazione della traduzione SQL generata da Gemini, fai clic su Assistenza e poi su Spiega questa traduzione.

    Pulsante Spiega traduzione.

Traduci con un ID configurazione della traduzione batch

Puoi eseguire una query interattiva con le stesse configurazioni di traduzione di un job di traduzione batch fornendo un ID configurazione di traduzione batch.

  1. Nell'editor di query, fai clic su Strumenti > Impostazioni di traduzione.

  2. Nel campo ID configurazione traduzione, fornisci un ID configurazione traduzione batch per applicare la stessa configurazione di traduzione di un job di migrazione batch BigQuery completato.

    Per trovare l'ID configurazione della traduzione batch di un job, seleziona un job di traduzione batch dalla pagina Traduzione SQL, quindi fai clic sulla scheda Configurazione della traduzione. L'ID configurazione della traduzione batch è elencato come Nome risorsa.

  3. Fai clic su Salva.

Traduci con configurazioni aggiuntive

Puoi eseguire una query interattiva con configurazioni di traduzione aggiuntive specificando i file YAML di configurazione archiviati in una cartella Cloud Storage. Le configurazioni di traduzione potrebbero includere metadati degli oggetti SQL o informazioni di mappatura degli oggetti del database di origine che possono migliorare la qualità della traduzione. Ad esempio, includi informazioni o schemi DDL del database di origine per migliorare la qualità della traduzione SQL interattiva.

Per specificare le configurazioni di traduzione fornendo una posizione per i file di origine della configurazione di traduzione, segui questi passaggi:

  1. Nell'editor di query, fai clic su Strumenti > Impostazioni di traduzione.

  2. Nel campo Posizione di origine della configurazione della traduzione, specifica il percorso dei file di configurazione della traduzione archiviati in una cartella Cloud Storage.

    Il traduttore SQL interattivo di BigQuery supporta i file ZIP dei metadati contenenti metadati di traduzione e mappatura dei nomi degli oggetti. Per informazioni su come caricare file su Cloud Storage, consulta Carica oggetti da un file system.

  3. Fai clic su Salva.

Limiti di dimensione dei file di configurazione

Quando utilizzi un file di configurazione della traduzione con il traduttore SQL interattivo di BigQuery, il file di metadati compresso o il file di configurazione YAML deve avere dimensioni inferiori a 50 MB. Se le dimensioni del file superano i 50 MB, il traduttore interattivo salta il file di configurazione durante la traduzione e genera un messaggio di errore simile al seguente:

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

Un metodo per ridurre le dimensioni del file dei metadati consiste nell'utilizzare i flag --database o --schema per estrarre solo i metadati per i database o gli schemi pertinenti per le query di input della traduzione. Per saperne di più sull'utilizzo di questi flag quando generi file di metadati, consulta Flag globali.

Risolvi gli errori di traduzione

Le sezioni seguenti descrivono gli errori più comuni che si verificano durante l'utilizzo del traduttore SQL interattivo.

Problemi di traduzione di RelationNotFound o AttributeNotFound

Dopo aver tradotto una query utilizzando il traduttore SQL interattivo, 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.

Per garantire la traduzione più accurata, puoi inserire le istruzioni del linguaggio di definizione dei dati (DDL) per tutte le tabelle utilizzate in una query prima della query stessa. Ad esempio, se vuoi tradurre la query Amazon Redshift select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;, inserisci le seguenti istruzioni SQL nel traduttore SQL interattivo:

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Risolvi 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. In BigQuery nella console Google Cloud , vai alla pagina Dettagli traduzione e apri la scheda Messaggi di log.
  2. Fai clic sulla query che contiene il messaggio RelationNotFound o AttributeNotFound nella colonna Categoria.
  3. Fai clic su Correzione suggerita.
  4. Fai clic su Applica.
  5. Per ritradurre la query, fai clic su Traduci.

Prezzi

L'utilizzo del traduttore SQL interattivo non comporta alcun costo. Tuttavia, lo spazio di archiviazione utilizzato per archiviare i file di input e di output è soggetto alle 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: