Tradurre 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 è rivolto agli utenti che hanno dimestichezza con la Google Cloud console.

Se la tua posizione è supportata, puoi utilizzare la funzionalità di regola di traduzione per personalizzare il modo in cui il traduttore SQL interattivo traduce SQL.

Prima di iniziare

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

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

    Vai all'API BigQuery Migration

  2. Fai clic su Attiva.

Autorizzazioni e ruoli

Questa sezione descrive le autorizzazioni di Identity and Access Management (IAM) di cui hai bisogno per utilizzare il traduttore SQL interattivo, inclusi i ruoli IAM predefiniti che concedono queste autorizzazioni. La sezione descrive anche le autorizzazioni necessarie per configurare configurazioni di traduzione aggiuntive.

Autorizzazioni per utilizzare il traduttore SQL interattivo

Per ottenere le autorizzazioni necessarie per utilizzare il traduttore interattivo, chiedi all'amministratore di concederti il ruolo IAM MigrationWorkflow Editor (roles/bigquerymigration.editor) nella risorsa parent. Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per utilizzare il traduttore interattivo. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per utilizzare il traduttore interattivo sono necessarie le seguenti autorizzazioni:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get

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

Autorizzazioni per configurare configurazioni di traduzione aggiuntive

Puoi configurare configurazioni di traduzione aggiuntive utilizzando i campi ID configurazione traduzione e Posizione di origine della configurazione di traduzione nelle impostazioni di traduzione. Per configurare queste configurazioni di traduzione, devi disporre delle seguenti autorizzazioni:

  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list

Il seguente ruolo IAM predefinito fornisce le autorizzazioni necessarie per configurare ulteriori configurazioni di traduzione:

  • roles/bigquerymigration.viewer

Per ulteriori informazioni su IAM di BigQuery, consulta Controllo dell'accesso con IAM.

Dialetti SQL supportati

Il traduttore SQL interattivo di BigQuery può tradurre i seguenti dialetti SQL in GoogleSQL:

  • Amazon Redshift SQL
  • Apache HiveQL e interfaccia a riga di comando 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
  • Greenplum SQL
  • SQL di IBM DB2
  • MySQL SQL
  • Oracle SQL, PL/SQL, Exadata
  • SQL PostgreSQL
  • Trino o PrestoSQL
  • Snowflake SQL
  • T-SQL di SQL Server
  • SQLite
  • Vertica SQL

Gestione di funzioni SQL non supportate con funzioni UDF di supporto

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

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

Considerazioni importanti per gli ambienti di produzione:

Sebbene bqutil offra un accesso pratico a queste funzioni UDF di supporto per la traduzione e i test iniziali, non è consigliabile fare affidamento diretto su bqutil per i carichi di lavoro di produzione per diversi motivi:

  1. Controllo della versione: il progetto bqutil ospita la versione più recente di queste funzioni definite dall'utente, il che significa che le relative definizioni possono cambiare nel tempo. Se la logica di una UDF viene aggiornata, fare affidamento direttamente su bqutil potrebbe comportare comportamenti imprevisti o modifiche che causano interruzioni nelle query di produzione.
  2. Isolamento delle dipendenze: il deployment delle funzioni definite dall'utente 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 aziendale o ai requisiti di rendimento specifici. Questo è possibile solo se si trovano all'interno del tuo progetto.
  4. Sicurezza e governance: i criteri 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.

Esegui il deployment delle UDF di supporto nel progetto:

Per un utilizzo in produzione affidabile e stabile, devi implementare queste UDF di supporto nel tuo progetto e nel tuo set di dati. In questo modo avrai il pieno controllo sulla versione, sulla personalizzazione e sull'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 nelle seguenti località di elaborazione:

Descrizione della regione Nome regione Dettagli
Asia Pacifico
Delhi asia-south2
Hong Kong asia-east2
Giacarta asia-southeast2
Melbourne australia-southeast2
Mumbai asia-south1
Osaka asia-northeast2
Seul asia-northeast3
Singapore asia-southeast1
Sydney australia-southeast1
Taiwan asia-east1
Tokyo asia-northeast1
Europa
Belgio europe-west1 icona foglia Bassi livelli di CO2
Berlino europe-west10 icona foglia Bassi livelli di CO2
Multiregione UE eu
Finlandia europe-north1 icona foglia Bassi livelli di CO2
Francoforte europe-west3 icona foglia Bassi livelli di CO2
Londra europe-west2 icona foglia Bassi livelli di CO2
Madrid europe-southwest1 icona foglia Bassi livelli di CO2
Milano europe-west8
Paesi Bassi europe-west4 icona foglia Bassi livelli di CO2
Parigi europe-west9 icona foglia Bassi livelli di CO2
Stoccolma europe-north2 icona foglia Bassi livelli di CO2
Torino europe-west12
Varsavia europe-central2
Zurigo europe-west6 icona foglia Bassi livelli di CO2
Americhe
Columbus, Ohio us-east5
Dallas us-south1 icona foglia Bassi livelli di CO2
Iowa us-central1 icona foglia Bassi livelli di CO2
Las Vegas us-west4
Los Angeles us-west2
Messico northamerica-south1
Virginia del Nord us-east4
Oregon us-west1 icona foglia Bassi livelli di CO2
Québec northamerica-northeast1 icona foglia Bassi livelli di CO2
San Paolo southamerica-east1 icona foglia Bassi livelli di CO2
Salt Lake City us-west3
Santiago southamerica-west1 icona foglia Bassi livelli di CO2
Carolina del Sud us-east1
Toronto northamerica-northeast2 icona foglia Bassi livelli di CO2
Multiregione Stati Uniti us
Africa
Johannesburg africa-south1
MiddleEast
Dammam me-central2
Doha me-central1
Israele me-west1

Per impostazione predefinita, la funzionalità della regola di traduzione è disponibile nelle seguenti località di elaborazione:

  • us (multiregione Stati Uniti)
  • eu (più regioni dell'UE)
  • us-central1 (Iowa)
  • europe-west4 (Paesi Bassi)

Le configurazioni di traduzione basate su Gemini sono disponibili solo in località di elaborazione specifiche. Per ulteriori informazioni, consulta Località degli endpoint dei modelli Google.

Tradurre una query in GoogleSQL

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 Altro e poi seleziona Impostazioni di traduzione.

  3. Per 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 Altro e poi seleziona Abilita traduzione SQL.

    Il riquadro Editor si suddivide 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 corretto. Ad esempio, lo screenshot seguente mostra il codice SQL di Teradata tradotto:

    Mostra una query SQL di 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 e poi seleziona Disabilita la traduzione SQL.

    Il riquadro Editor torna a un singolo riquadro.

Utilizzare Gemini con il traduttore SQL interattivo

Puoi configurare il traduttore SQL interattivo per modificare il modo in cui traduce il codice 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 sulla mappatura degli oggetti.

Creare e applicare regole di traduzione ottimizzate con Gemini

Puoi personalizzare il modo in cui il traduttore SQL interattivo traduce SQL creando regole di traduzione. Il traduttore SQL interattivo aggiusta 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. Questa funzionalità è supportata solo in determinate località.

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 ASSISTENTE > Personalizza. (Anteprima)

Personalizzare l&#39;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 ASSISTENTE > Personalizza questa traduzione.

Personalizzare l&#39;output della traduzione

Quando viene visualizzato il menu Personalizza, procedi con i passaggi che seguono.

  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 da 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 migliorata di Gemini identifica eventuali istanze del 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.

    Applica le modifiche dal file YAML di configurazione basato su Gemini

  4. (Facoltativo) Per aggiungere questa regola da utilizzare nelle traduzioni future, seleziona la casella di controllo Salva questa richiesta.

    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 configurazione della traduzione nelle impostazioni di traduzione. Se la Posizione della fonte della configurazione della traduzione non è già impostata, viene visualizzato un browser di cartelle che ti consente di selezionarne una. Un file YAML di configurazione è soggetto a 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 ulteriori informazioni, consulta Creare un file YAML di configurazione basato su Gemini.

Dopo aver caricato una regola di traduzione SQL ottimizzata con Gemini in Cloud Storage, puoi applicarla nel seguente modo:

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

    Vai a BigQuery

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

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

  4. Fai clic su Salva.

    Una volta salvato, 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 di 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 rivedere e applicare questi suggerimenti:

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

    Applica le 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:

  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 inoltre 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:

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

    Spiega il pulsante di traduzione.

Tradurre 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 delle query, fai clic su Altro > 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 di configurazione della traduzione batch di un job, seleziona un job di traduzione batch dalla pagina Traduzione SQL e poi fai clic sulla scheda Configurazione traduzione. L'ID configurazione traduzione batch è indicato come Nome risorsa.

  3. Fai clic su Salva.

Tradurre con configurazioni aggiuntive

Puoi eseguire una query interattiva con configurazioni di traduzione aggiuntive specificando i file YAML di configurazione memorizzati in una cartella Cloud Storage. Le configurazioni di traduzione potrebbero 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 o schemi DDL dal database di origine per migliorare la qualità della traduzione SQL interattiva.

Per specificare le configurazioni di traduzione specificando una posizione per i file di origine della configurazione di traduzione, procedi nel seguente modo:

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

  2. Nel campo Posizione di origine della configurazione della traduzione, specifica il percorso ai 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 Caricare oggetti da un file system.

  3. Fai clic su Salva.

Per archiviare le informazioni dei file di metadati generati dallo strumento dwh-migration-dumper nel backend di BigQuery:

  1. Nell'editor delle query, fai clic su Altro > Impostazioni di traduzione.
  2. Fai clic sulla casella di controllo Attiva memorizzazione nella cache dei metadati. Per i job con file di metadati di grandi dimensioni, questo processo riduce notevolmente la latenza della traduzione per le richieste successive. I metadati memorizzati nella cache sono attivi per un massimo di 7 giorni. Questa funzionalità è in anteprima. Per richiedere assistenza o fornire un feedback su questa funzionalità, contatta bq-edw-migration-support@google.com.
  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 dei metadati compressi 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 ulteriori informazioni sull'utilizzo di questi flag quando generi file di metadati, consulta Flag globali.

Risolvere i problemi di traduzione

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

RelationNotFound o AttributeNotFound

Per garantire la traduzione più accurata, 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;, 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;

Prezzi

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

Passaggi successivi

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