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 è destinato agli utenti che hanno familiarità con la consoleGoogle Cloud .

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

Prima di iniziare

Se il tuo progetto Google Cloud CLI è stato creato prima del 15 febbraio 2022, attiva l'API BigQuery Migration nel seguente modo:

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

   Vai all'API BigQuery Migration

2. Fai clic su Attiva.

Nota: questa API è abilitata automaticamente per i progetti creati dopo il 15 febbraio 2022.

Autorizzazioni e ruoli

Questa sezione descrive le autorizzazioni Identity and Access Management (IAM) necessarie per utilizzare lo strumento di traduzione SQL interattivo, inclusi i ruoli IAM predefiniti che concedono queste autorizzazioni. La sezione descrive anche le autorizzazioni necessarie per configurare altre configurazioni di traduzione.

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 Editor MigrationWorkflow (roles/bigquerymigration.editor) nella risorsa parent. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per utilizzare il traduttore interattivo. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

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 altre configurazioni di traduzione 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 configurazioni di traduzione aggiuntive:

• roles/bigquerymigration.viewer

Per saperne di più su BigQuery IAM, 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
• Azure Synapse T-SQL
• Greenplum SQL
• IBM DB2 SQL
• MySQL SQL
• Oracle SQL, PL/SQL, Exadata
• SQL PostgreSQL
• Trino o PrestoSQL
• Snowflake SQL
• SQL Server T-SQL
• SQLite
• SQL Vertica

Gestione delle funzioni SQL non supportate con le UDF helper

Quando si traduce 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) helper 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 importanti 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 carichi di lavoro di produzione non è consigliato per diversi 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 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: potresti dover modificare o ottimizzare queste UDF per adattarle meglio alla logica aziendale o ai requisiti di rendimento specifici. Ciò è 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 nel tuo ambiente controllato è in linea con queste norme.

Deployment delle UDF helper nel tuo progetto:

Per un utilizzo affidabile e stabile in produzione, devi eseguire il deployment di queste UDF helper nel tuo progetto e set di dati. In questo modo avrai 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 UDF nel tuo ambiente.

Località

Il traduttore SQL interattivo è disponibile nelle seguenti posizioni 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	Bassi livelli di CO2
	Berlino	europe-west10	Bassi livelli di CO2
	Multiregione UE	eu
	Finlandia	europe-north1	Bassi livelli di CO2
	Francoforte	europe-west3	Bassi livelli di CO2
	Londra	europe-west2	Bassi livelli di CO2
	Madrid	europe-southwest1	Bassi livelli di CO2
	Milano	europe-west8
	Paesi Bassi	europe-west4	Bassi livelli di CO2
	Parigi	europe-west9	Bassi livelli di CO2
	Stoccolma	europe-north2	Bassi livelli di CO2
	Torino	europe-west12
	Varsavia	europe-central2
	Zurigo	europe-west6	Bassi livelli di CO2
Americhe
	Columbus, Ohio	us-east5
	Dallas	us-south1	Bassi livelli di CO2
	Iowa	us-central1	Bassi livelli di CO2
	Las Vegas	us-west4
	Los Angeles	us-west2
	Messico	northamerica-south1
	Virginia del Nord	us-east4
	Oregon	us-west1	Bassi livelli di CO2
	Québec	northamerica-northeast1	Bassi livelli di CO2
	San Paolo	southamerica-east1	Bassi livelli di CO2
	Salt Lake City	us-west3
	Santiago	southamerica-west1	Bassi livelli di CO2
	Carolina del Sud	us-east1
	Toronto	northamerica-northeast2	Bassi livelli di CO2
	Stati Uniti (multiregionale)	us
Africa
	Johannesburg	africa-south1
MiddleEast
	Dammam	me-central2
	Doha	me-central1
	Israele	me-west1

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

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

Le configurazioni di traduzione basate su Gemini sono disponibili solo in posizioni di elaborazione specifiche. Per ulteriori informazioni, consulta Posizioni degli endpoint del modello 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. Per Posizione di elaborazione, seleziona la posizione 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 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 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 e poi seleziona Disabilita la traduzione SQL.

    Il riquadro Editor torna a essere un singolo riquadro.

Utilizzare Gemini con il traduttore SQL interattivo

Puoi configurare il traduttore SQL interattivo per modificare la modalità di traduzione dell'SQL di origine. Puoi farlo fornendo le tue regole da utilizzare con Gemini in un file di configurazione YAML oppure 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

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. Questa funzionalità è supportata solo in determinate località.

Per creare una regola di traduzione SQL ottimizzata con Gemini, puoi crearla nella console oppure creare un file YAML di configurazione 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 ASSISTI > 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 ASSISTI > 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 da sostituire nel campo Sostituisci e un pattern SQL con cui sostituirlo nel campo Con.

     Un pattern SQL può contenere qualsiasi numero di istruzioni, clausole o funzioni in uno script SQL. Quando crei una regola utilizzando questo prompt, la traduzione SQL ottimizzata con Gemini identifica eventuali istanze di questo 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 sostituisca 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 alla query SQL dalla traduzione SQL ottimizzata con Gemini in base alla tua regola.

   

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

   Le regole vengono salvate nel file YAML di configurazione predefinito o __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 di origine della configurazione della traduzione non è ancora impostata, viene visualizzato un browser di cartelle che ti consente di selezionarne una. Un file YAML di configurazione è soggetto a limitazioni delle dimensioni 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 YAML di configurazione basato su Gemini e caricarlo in 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 e averla caricata in Cloud Storage, puoi applicarla procedendo 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 origine 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 tua regola, viene visualizzata la finestra di dialogo Visualizza l'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 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.

   

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.

Spiegare 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 i tuoi script tramite 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 del testo generata da Gemini. Il testo generato include un riepilogo della query SQL tradotta. Gemini identifica anche differenze e incongruenze 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 Assistenza e poi su Spiega questa 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 da 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 della traduzione. L'ID configurazione di traduzione batch è elencato 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 archiviati in una cartella Cloud Storage. Le configurazioni di traduzione potrebbero includere metadati degli oggetti SQL o informazioni sul mapping 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 fornendo una posizione ai file di origine della configurazione di traduzione, esegui le seguenti operazioni:

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

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

   Il traduttore SQL interattivo BigQuery supporta file ZIP di metadati contenenti metadati di traduzione e mapping dei nomi degli oggetti. Per informazioni su come caricare file in Cloud Storage, consulta Carica 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 BigQuery:

1. Nell'editor delle query, fai clic su Altro > Impostazioni di traduzione.
2. Fai clic sulla casella di controllo Abilita memorizzazione nella cache dei metadati. Per i job con file di metadati di grandi dimensioni, questo processo riduce significativamente la latenza di 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 [e-mail].
3. Fai clic su Salva.

Limitazioni delle dimensioni dei file di configurazione

Quando utilizzi un file di configurazione della traduzione con lo strumento di traduzione 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, lo strumento di traduzione interattiva ignora il file di configurazione durante la traduzione e produce 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 per i database o gli schemi pertinenti per le query di input di traduzione. Per saperne di più sull'utilizzo di questi flag quando generi file di metadati, consulta Flag globali.

Risolvere i problemi relativi agli errori di traduzione

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

Problemi di traduzione di RelationNotFound o AttributeNotFound

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

Prezzi

L'utilizzo del traduttore SQL interattivo non comporta alcun costo. Tuttavia, lo spazio di archiviazione utilizzato per archiviare i file di input e output comporta le normali tariffe. Per maggiori informazioni, consulta 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 del trasferimento di schemi e dati
• Traduzione SQL batch
• Pipeline di dati
• Sicurezza e governance dei dati
• Strumento di convalida dei dati