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

Prima di iniziare

Prima di inviare un progetto di traduzione, completa i seguenti passaggi:

1. Assicurati di disporre di tutte le autorizzazioni richieste.
2. Abilita l'API BigQuery Migration.
3. Raccogli i file di origine contenenti gli script e le query SQL da tradurre.
4. Facoltativo. Crea un file di metadati per migliorare l'accuratezza della traduzione.
5. Facoltativo. Decidi se devi mappare i nomi degli oggetti SQL nei file di origine con nuovi nomi in BigQuery. Determina quali regole di mappatura dei nomi utilizzare, se necessario.
6. Decidi quale metodo utilizzare per inviare il lavoro di traduzione.
7. Carica i file di origine su Cloud Storage.

Autorizzazioni obbligatorie

Per attivare BigQuery Migration Service, devi disporre delle seguenti autorizzazioni per il progetto:

• resourcemanager.projects.get
• serviceusage.services.enable
• serviceusage.services.get

Per accedere e utilizzare BigQuery Migration Service, devi disporre delle seguenti autorizzazioni per il progetto:

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

• bigquerymigration.subtasks.list

  In alternativa, puoi utilizzare i seguenti ruoli per ottenere le stesse autorizzazioni:

  • bigquerymigration.viewer - Accesso di sola lettura.
  • bigquerymigration.editor - Accesso in lettura/scrittura.

Per accedere ai bucket Cloud Storage per i file di input e output:

• storage.objects.get sul bucket Cloud Storage di origine.
• storage.objects.list sul bucket Cloud Storage di origine.
• storage.objects.create sul bucket Cloud Storage di destinazione.

Puoi disporre di tutte le autorizzazioni Cloud Storage necessarie dai seguenti ruoli:

• roles/storage.objectAdmin
• roles/storage.admin

Abilita l'API BigQuery Migration

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

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

   Vai all'API BigQuery Migration

2. Fai clic su Attiva.

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, questa operazione non è obbligatoria.

Puoi utilizzare lo strumento di estrazione da riga di comando dwh-migration-dumper per generare le informazioni sui metadati oppure puoi fornire i tuoi file di metadati. Una volta preparati 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. Non è necessario configurare impostazioni aggiuntive per abilitare questa funzionalità.

Per generare informazioni sui metadati utilizzando lo strumento dwh-migration-dumper, vedi Generare metadati per la traduzione.

Per fornire i tuoi metadati, raccogli le istruzioni del linguaggio di definizione dei dati (DDL) per gli oggetti SQL nel sistema di origine in file di testo separati.

Decidere come inviare il job di traduzione

Hai tre opzioni per inviare un job di traduzione batch:

• Client di traduzione batch: configura un job modificando le impostazioni in un file di configurazione e invia il job utilizzando la riga di comando. Questo approccio non richiede il caricamento manuale dei file di origine su Cloud Storage. Il client utilizza ancora Cloud Storage per archiviare i file durante l'elaborazione dei job di traduzione.

  Il client di traduzione batch legacy è un client Python open source che ti consente di tradurre i file di origine che si trovano sulla tua macchina locale e di inviare i file tradotti a una directory locale. Configura il client per l'utilizzo di base modificando alcune impostazioni nel relativo file di configurazione. Se vuoi, puoi anche configurare il client per gestire attività più complesse come la sostituzione delle macro e l'elaborazione pre e post degli input e degli output di traduzione. Per saperne di più, consulta il file Readme del client di traduzione batch.

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

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.

Se vuoi utilizzare la console Trusted Cloud o l'API BigQuery Migration per un job di traduzione batch, puoi caricare il file YAML di configurazione nel bucket Cloud Storage contenente i file di origine.

Se vuoi utilizzare il client di traduzione batch, puoi inserire il file YAML di configurazione nella cartella di input della traduzione locale.

Carica i file di input su Cloud Storage

Se vuoi utilizzare la console Trusted Cloud o l'API BigQuery Migration per eseguire un job di traduzione, devi caricare i file di origine contenenti <x0A>le query e gli script che vuoi tradurre in Cloud Storage. Puoi anche caricare qualsiasi file di metadati o file YAML di configurazione nello stesso bucket Cloud Storage contenente i file di origine. Per saperne di più sulla creazione di bucket e sul caricamento di file in Cloud Storage, consulta Crea bucket e Carica oggetti da un file system.

Dialetti SQL supportati

Il traduttore SQL batch fa parte di BigQuery Migration Service. Il traduttore SQL batch 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 funzioni definite dall'utente 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 batch è 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
	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

Inviare un job di traduzione

Segui questi passaggi per avviare un job di traduzione, visualizzarne l'avanzamento e vedere i risultati.

Esplora l'output della traduzione

Dopo aver eseguito il job di traduzione, puoi visualizzare le informazioni sul job nella Trusted Cloud console. Se hai utilizzato la console Trusted Cloud per eseguire il job, puoi visualizzare i risultati del job nel bucket Cloud Storage di destinazione che hai specificato. Se hai utilizzato il client di traduzione batch per eseguire il job, puoi visualizzare i risultati del job nella directory di output che hai specificato. Il traduttore SQL batch genera i seguenti file nella destinazione specificata:

• I file tradotti.
• Il report di riepilogo della traduzione in formato CSV.
• Il mapping dei nomi degli output utilizzati in formato JSON.
• I file di suggerimenti dell'AI.

Trusted Cloud console output

Per visualizzare i dettagli del job di traduzione:

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

   Vai a BigQuery

2. Nel menu di navigazione, fai clic su Traduzione SQL.

3. Nell'elenco dei job di traduzione, individua quello per cui vuoi visualizzare i dettagli della traduzione. Poi, fai clic sul nome del progetto 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 problemi aggiuntivi nelle fasi successive.

4. Tieni il puntatore sopra le barre di errore o avviso e rivedi i suggerimenti per determinare i passaggi successivi per eseguire il debug del job di traduzione.

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

6. Seleziona la scheda Messaggi di log per visualizzare ulteriori dettagli su ogni problema di traduzione, inclusi la categoria del problema, il messaggio specifico del problema 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 output, se applicabile.

7. 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 lavoro di traduzione.

Per visualizzare il file di riepilogo nella console Trusted Cloud :

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

   Vai a BigQuery

2. Nel menu di navigazione, fai clic su Traduzione SQL.

3. Nell'elenco dei progetti di traduzione, individua quello che ti interessa, poi fai clic sul nome del progetto o su Altre opzioni > Mostra dettagli.

4. Nella scheda Dettagli job, nella sezione Report di traduzione, fai clic su translation_report.csv.

5. 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 consente di esaminare ulteriori informazioni sui file di input e output per un determinato job di traduzione. Nella scheda del codice puoi esaminare i file utilizzati in un lavoro di traduzione, rivedere un confronto affiancato 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 lavoro.

Per accedere alla scheda del codice:

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

   Vai a BigQuery

2. Nel menu di navigazione, fai clic su Traduzione SQL.

3. Nell'elenco dei progetti di traduzione, individua quello che ti interessa, poi fai clic sul nome del progetto o su Altre opzioni > Mostra dettagli.

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

5. (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 Trusted Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel menu di navigazione, fai clic su Traduzione SQL.

3. Nell'elenco dei progetti di traduzione, individua quello che ti interessa, poi fai clic sul nome del progetto o su Altre opzioni > Mostra dettagli.

4. 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 di mapping dei nomi di output utilizzato

Questo file JSON contiene le regole di mappatura dei nomi di output utilizzate dal job di traduzione. Le regole in questo file potrebbero differire da quelle di mapping dei nomi di output specificate per il job di traduzione, a causa di conflitti nelle regole di mapping dei nomi o della mancanza di regole di mapping dei nomi per gli oggetti SQL identificati durante la traduzione. Esamina questo file per determinare se le regole di mappatura dei nomi devono essere corrette. In questo caso, crea nuove regole di mappatura dei nomi di output che risolvano eventuali problemi identificati ed esegui un nuovo job di traduzione.

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.

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

Per avviare una traduzione SQL interattiva utilizzando un ID configurazione di traduzione batch:

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

   Vai a BigQuery

2. Nel menu di navigazione, fai clic su Traduzione SQL.

3. Nell'elenco dei lavori di traduzione, individua quello che ti interessa, quindi fai clic su more_vert Altre opzioni > Apri traduzione interattiva.

   Il traduttore SQL interattivo di BigQuery ora si apre con l'ID configurazione di traduzione batch corrispondente. Per visualizzare l'ID configurazione della traduzione per la traduzione interattiva, fai clic su Altro > Impostazioni di traduzione nel traduttore SQL interattivo.

Per eseguire il debug di un file di traduzione batch nel traduttore SQL interattivo, segui questi passaggi:

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

   Vai a BigQuery

2. Nel menu di navigazione, fai clic su Traduzione SQL.

3. Nell'elenco dei job di traduzione, individua quello che ti interessa, quindi fai clic sul nome del job o su Altre opzioni > Mostra dettagli.

4. Nella finestra Dettagli traduzione, fai clic sulla scheda Codice.

5. In Esplora file, fai clic sul nome del file per aprirlo.

6. Accanto al nome del file di output, fai clic su Modifica per aprire i file nel traduttore SQL interattivo (anteprima).

   Vedi i file di input e output compilati nel traduttore SQL interattivo che ora utilizza l'ID configurazione di traduzione batch corrispondente.

7. Per salvare il file di output modificato in Cloud Storage, nel traduttore SQL interattivo fai clic su Salva > Salva in GCS.

Limitazioni

Il traduttore non può tradurre le funzioni definite dall'utente (UDF) da lingue diverse da SQL perché non può analizzarle per determinare i tipi di dati di input e output. Ciò causa una traduzione imprecisa delle istruzioni SQL che fanno riferimento a queste UDF. Per assicurarti che le UDF non SQL vengano correttamente referenziate durante la traduzione, utilizza SQL valido per creare UDF segnaposto con le stesse firme.

Ad esempio, supponiamo di avere una UDF scritta in C che calcola la somma di due numeri interi. Per assicurarti che le istruzioni SQL che fanno riferimento a questa UDF vengano tradotte correttamente, crea una UDF SQL segnaposto che condivida la stessa firma della UDF C, come mostrato nell'esempio seguente:

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

Salva questa UDF segnaposto in un file di testo e includi il file tra i file di origine del job di traduzione. In questo modo, il traduttore può apprendere la definizione della funzione definita dall'utente e identificare i tipi di dati di input e output previsti.

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.

Risolvere i problemi relativi agli errori di traduzione

Problemi di traduzione di RelationNotFound o AttributeNotFound

La traduzione funziona meglio con i DDL dei 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, in quanto spesso può correggere molti altri errori causati indirettamente dalla mancanza di metadati.

Per ulteriori informazioni, vedi Generare metadati per la traduzione e la valutazione.

Prezzi

Non è previsto alcun costo per l'utilizzo del traduttore SQL batch. Tuttavia, lo spazio di archiviazione utilizzato per archiviare i file di input e output comporta le normali tariffe. Per ulteriori informazioni, consulta la pagina 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
• Pipeline di dati
• Traduzione SQL interattiva
• Sicurezza e governance dei dati
• Strumento di convalida dei dati