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 carichi di lavoro a BigQuery. Questo documento è destinato agli utenti che hanno familiarità con la Google Cloud console.

Puoi utilizzare la funzionalità delle regole di traduzione per personalizzare il modo in cui il traduttore SQL interattivo traduce l'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 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: MigrationWorkflow Viewer (roles/bigquerymigration.viewer)
• Invio di job di migrazione: MigrationWorkflow Editor (roles/bigquerymigration.editor)
• Accesso ai bucket Cloud Storage per input e 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:

Autorizzazioni obbligatorie

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

• 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.

Gestire le funzioni SQL non supportate con le UDF di assistenza

Quando traduci l'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 più ampia community di BigQuery) 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, il che consente 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 accesso comodo a queste UDF di assistenza per la traduzione e il test iniziali, l'utilizzo diretto di bqutil per i carichi di lavoro di produzione non è consigliato per diversi motivi:

1. Controllo delle versioni: 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 interruzioni 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 dalle modifiche esterne.
3. Personalizzazione: potrebbe essere necessario modificare o ottimizzare queste UDF per adattarle meglio alla logica di business o ai requisiti di prestazioni 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 ai set di dati pubblici come bqutil per l'elaborazione dei dati di produzione. La copia delle UDF nel tuo ambiente controllato è conforme a queste norme.

Eseguire il deployment delle UDF di assistenza nel tuo progetto:

Per un utilizzo di produzione affidabile e stabile, devi eseguire il deployment di queste UDF di assistenza nel tuo progetto e set di dati. In questo modo avrai il controllo completo 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 UDF 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 Località degli endpoint dei modelli Google.

Traduci una query in GoogleSQL

Segui questi passaggi per tradurre una query in GoogleSQL:

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

   Vai a BigQuery

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

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

4. (Facoltativo) Per 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 viene suddiviso 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, la schermata seguente mostra l'SQL di Teradata tradotto:

   

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.

Utilizza Gemini con il traduttore SQL interattivo

Puoi configurare il traduttore SQL interattivo per modificare il modo in cui traduce l'SQL di origine. Per farlo, fornisci le tue regole da utilizzare con Gemini in un file di configurazione YAML oppure fornisci 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

Nota: per ricevere assistenza e fornire feedback sulle funzionalità di anteprima, contatta [e-mail].

Puoi personalizzare il modo in cui il traduttore SQL interattivo traduce l'SQL creando regole di traduzione. Il traduttore SQL interattivo adatta 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 oppure creare un file di configurazione YAML e caricarlo in 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)

Allo stesso modo, 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.

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 da sostituire 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 della 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 tua regola.

   

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

   Le regole vengono salvate nel file di configurazione YAML predefinito o __default.ai_config.yaml. Questo file di configurazione YAML 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 è ancora impostata, viene visualizzato un browser di cartelle che ti consente di selezionarne una. Un file di configurazione YAML è soggetto a limitazioni di dimensione del 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 di configurazione YAML basato su Gemini e caricarlo in Cloud Storage. Per saperne di più, consulta Crea un file di configurazione YAML basato su Gemini.

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

1. Nella Google Cloud console, 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. Se è disponibile un file di configurazione YAML, il traduttore interattivo suggerisce modifiche alle traduzioni in base alle regole contenute nel file.

Se è disponibile un suggerimento di Gemini per l'input in base alla tua regola, viene visualizzata la finestra di dialogo Visualizza l'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, viene visualizzato un banner di notifica nell'editor di codice. Per esaminare e applicare questi suggerimenti:

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

   

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

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

Aggiorna il file di configurazione YAML basato su Gemini

Per aggiornare un file di configurazione YAML esistente:

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 di configurazione YAML 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

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: con le traduzioni SQL ottimizzate con Gemini, puoi generare una spiegazione testuale per gli script utilizzando il modello Gemini. Le traduzioni SQL ottimizzate con Gemini consentono un utilizzo limitato di Gemini senza costi. Questo utilizzo è sufficiente per la maggior parte dei progetti di migrazione. Per richiedere un aumento di questo limite, o per ricevere assistenza e fornire feedback su questa funzionalità di anteprima, contatta [e-mail].

Dopo aver eseguito una traduzione interattiva, puoi richiedere una spiegazione testuale 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 una spiegazione della traduzione SQL generata da Gemini:

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

   

Traduci con un ID configurazione di 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 di traduzione batch per applicare la stessa configurazione di traduzione di un job di migrazione batch di BigQuery completato.

   Per trovare l'ID configurazione di traduzione batch di un job, seleziona un job di traduzione batch dalla pagina Traduzione SQL, quindi fai clic sulla scheda Configurazione traduzione. L'ID configurazione di 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 di configurazione YAML archiviati in una cartella Cloud Storage. Le configurazioni di traduzione possono includere metadati degli oggetti SQL o informazioni di mappatura degli oggetti dal database di origine che possono migliorare la qualità della traduzione. Ad esempio, includi informazioni DDL o schemi dal database di origine per migliorare la qualità della traduzione SQL interattiva.

Per specificare le configurazioni di traduzione fornendo una posizione ai file di origine della configurazione di traduzione:

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 di metadati contenenti metadati di traduzione e mappatura dei nomi degli oggetti. Per informazioni su come caricare i file in Cloud Storage, consulta Carica oggetti da un file system.

3. Fai clic su Salva.

Limitazioni di dimensione dei file di configurazione

Quando utilizzi un file di configurazione di traduzione con il traduttore SQL interattivo di BigQuery, il file di metadati compressi o il file di configurazione YAML deve essere inferiore 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 di metadati consiste nell'utilizzare i flag --database o --schema per estrarre solo i metadati dei database o degli 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

Di seguito sono riportati gli errori più comuni che si verificano durante l'utilizzo del traduttore SQL interattivo.

Problemi di traduzione RelationNotFound o AttributeNotFound

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

Puoi trovare le traduzioni non riuscite andando alla pagina Dettagli traduzione e aprendo la scheda Messaggi di log.

Per garantire la traduzione più accurata possibile, puoi inserire le istruzioni DDL (Data Definition Language) 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;, devi inserire 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

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per richiedere feedback o assistenza per questa funzionalità, contatta [e-mail].

Per correggere i job di traduzione non riusciti con gli errori RelationNotFound o AttributeNotFound, puoi anche utilizzare Gemini per provare a risolvere questi problemi seguendo questi passaggi.

1. 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. Fai clic su Traduci per tradurre di nuovo la query.

Prezzi

L'utilizzo del traduttore SQL interattivo non prevede costi. Tuttavia, lo spazio di archiviazione utilizzato per archiviare i file di input e output comporta le tariffe normali. Per saperne di più, consulta Prezzi di archiviazione.

Passaggi successivi

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

• Panoramica della migrazione
• Valutazione della migrazione
• Panoramica del trasferimento di schemi e dati
• Traduzione SQL batch
• Pipeline di dati
• Sicurezza e governance dei dati
• Strumento di convalida dei dati