Esegui la migrazione del codice con il traduttore SQL batch
Per le nuove traduzioni, ti consigliamo di usare l'API Translation per tradurre i tuoi script SQL. L'API di traduzione funziona in modo molto simile al traduttore SQL batch, ma senza bisogno di installare o utilizzare codice client.
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 console Google Cloud.
Prima di iniziare
Prima di inviare un job di traduzione, completa i seguenti passaggi:
- Assicurati di disporre di tutte le autorizzazioni richieste.
- Abilitare l'API BigQuery Migration.
- Raccogli i file di origine contenenti gli script SQL e le query da tradurre.
- Facoltativo. Crea un file di metadati per migliorare la precisione della traduzione.
- Facoltativo. Decidi se devi mappare i nomi degli oggetti SQL nei file di origine su nuovi nomi in BigQuery. Stabilisci quali regole di mappatura dei nomi utilizzare, se necessario.
- Decidi quale metodo utilizzare per inviare il job di traduzione.
- Carica i file di origine in Cloud Storage.
Autorizzazioni obbligatorie
Per abilitare BigQuery Migration Service, devi disporre delle seguenti autorizzazioni nel progetto:
resourcemanager.projects.get
serviceusage.services.enable
serviceusage.services.get
Per accedere a BigQuery Migration Service e utilizzarlo, devi disporre delle seguenti autorizzazioni nel 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 di 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 in alto nei ruoli seguenti:
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:
Nella console Google Cloud, vai alla pagina dell'API BigQuery Migration.
Fai clic su Abilita.
Raccogli 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 anche includere commenti. Fai del tuo meglio per assicurarti che l'SQL sia valido, utilizzando qualsiasi metodo disponibile.
Creare file di metadati
Per consentire al servizio di generare risultati di traduzione più accurati, ti consigliamo di fornire file di metadati. Tuttavia, non è obbligatorio.
Puoi utilizzare lo strumento di estrazione a 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 sorgente, per abilitare questa funzionalità non occorre configurare impostazioni aggiuntive.
Per generare informazioni sui metadati utilizzando lo strumento dwh-migration-dumper
, consulta
Generare metadati per la traduzione.
Per fornire i tuoi metadati, raccogli le istruzioni DDL (Data Definition Language) per gli oggetti SQL nel sistema di origine in file di testo separati.
Mappa i nomi degli oggetti SQL
Facoltativamente, puoi eseguire la mappatura dei nomi di output durante la traduzione batch. Quando utilizzi la mappatura dei nomi di output, specifichi regole di mappatura dei nomi che modificano i nomi degli oggetti SQL nel sistema di origine in nuovi nomi in BigQuery. Ad esempio, potresti avere l'oggetto schema1.table1
nel sistema di origine e vuoi che abbia il nome project1.dataset1.table1
in BigQuery. Se utilizzi il mapping dei nomi di output, devi definire le regole di mappatura dei nomi prima di avviare un job di traduzione batch. Puoi inserire queste regole manualmente durante la configurazione del job oppure creare un file JSON contenente le regole di mappatura dei nomi e caricarlo.
Decidi come inviare il job di traduzione
Per inviare un job di traduzione batch sono disponibili tre opzioni:
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 in Cloud Storage. Il client usa ancora Cloud Storage per archiviare i file durante l'elaborazione del job di traduzione.
Il client di traduzione batch è un client Python open source che consente di tradurre i file di origine situati sulla tua macchina locale e di ottenere l'output dei file tradotti in una directory locale. Per configurare il client per l'utilizzo di base, modifica alcune impostazioni nel file di configurazione. Se vuoi, puoi anche configurare il client in modo che esegua attività più complesse come la sostituzione delle macro e la pre- e post-elaborazione degli input e degli output di traduzione. Per ulteriori informazioni, consulta il readme del client di traduzione batch.
Console Google Cloud: configura e invia un job utilizzando un'interfaccia utente. Questo approccio richiede di caricare i file di origine in Cloud Storage.
Creare file YAML di configurazione
Facoltativamente, puoi creare e utilizzare file YAML di configurazione di configurazione per personalizzare le traduzioni batch. Questi file possono essere usati per trasformare l'output di traduzione in vari modi. Ad esempio, puoi creare un file YAML di configurazione per modificare il caso di un oggetto SQL durante la traduzione.
Se vuoi utilizzare la console Google 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 di traduzione locale.
Carica i file di input su Cloud Storage
Se vuoi utilizzare la console Google Cloud o l'API BigQuery Migration per eseguire un job di traduzione, devi caricare i file di origine contenenti le query e gli script da 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 ulteriori informazioni sulla creazione di bucket e sul caricamento dei file in Cloud Storage, consulta Creare bucket e Caricare 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:
- SQL di Amazon Redshift
- Apache HiveQL e interfaccia a riga di comando Beeline
- SQL Netezza e NZPLSQL di IBM Netezza
- Teradata e Teradata Vantage
- SQL
- Query Teradata di base (BTEQ)
- Trasporto parallelo di Teradata (TPT)
Inoltre, la traduzione dei seguenti dialetti SQL è supportata in anteprima:
- Apache Spark SQL
- Azure Synapse T-SQL
- SQL Greenplum
- SQL DB2 IBM
- SQL MySQL
- Oracle SQL, PL/SQL, Exadata
- SQL PostgreSQL
- Trino o PrestoSQL
- SQL Snowflake
- SQL Server T-SQL
- SQLite
- SQL Vertica
Località
Il traduttore SQL batch è disponibile nelle seguenti posizioni di elaborazione:
Descrizione della regione | Nome regione | Dettagli | |
---|---|---|---|
Asia Pacifico | |||
Tokyo | asia-northeast1 |
||
Mumbai | asia-south1 |
||
Singapore | asia-southeast1 |
||
Sydney | australia-southeast1 |
||
Europa | |||
Più regioni UE | eu |
||
Varsavia | europe-central2 |
||
Finlandia | europe-north1 |
A basse emissioni di CO2 | |
Madrid | europe-southwest1 |
||
Belgio | europe-west1 |
A basse emissioni di CO2 | |
Londra | europe-west2 |
A basse emissioni di CO2 | |
Francoforte | europe-west3 |
A basse emissioni di CO2 | |
Paesi Bassi | europe-west4 |
||
Zurigo | europe-west6 |
A basse emissioni di CO2 | |
Parigi | europe-west9 |
A basse emissioni di CO2 | |
Torino | europe-west12 |
||
Americhe | |||
San Paolo | southamerica-east1 |
A basse emissioni di CO2 | |
Stati Uniti (più regioni) | us |
||
Iowa | us-central1 |
A basse emissioni di CO2 | |
Carolina del Sud | us-east1 |
||
Virginia del Nord | us-east4 |
||
Columbus, Ohio | us-east5 |
||
Dallas | us-south1 |
||
Oregon | us-west1 |
A basse emissioni di CO2 | |
Los Angeles | us-west2 |
||
Salt Lake City | us-west3 |
Invia un job di traduzione
Segui questi passaggi per avviare un job di traduzione, visualizzarne l'avanzamento e vedere i risultati.
Client di traduzione batch
Nella directory di installazione del client di traduzione batch, utilizza l'editor di testo di tua scelta per aprire il file
config.yaml
e modificare le seguenti impostazioni:project_number
: digita il numero del progetto da utilizzare per il job di traduzione batch. Puoi trovare queste informazioni nel riquadro Informazioni sul progetto nella pagina di benvenuto della console Google Cloud per il progetto.gcs_bucket
: digita il nome del bucket Cloud Storage che il client di traduzione batch deve utilizzare per archiviare i file durante l'elaborazione del job di traduzione.input_directory
: digita il percorso assoluto o relativo della directory che contiene i file di origine ed eventuali file di metadati.output_directory
: digita il percorso assoluto o relativo alla directory di destinazione per i file tradotti.
Salva le modifiche e chiudi il file
config.yaml
.Inserisci i file di origine e di metadati nella directory di input.
Esegui il client di traduzione batch utilizzando il seguente comando:
bin/dwh-migration-client
Una volta creato il job di traduzione, puoi visualizzarne lo stato nell'elenco dei job di traduzione nella console Google Cloud.
Facoltativo. Una volta completato il job di traduzione, elimina i file creati dal job nel bucket Cloud Storage specificato per evitare costi di archiviazione.
Console
Questi passaggi presuppongono che i file di origine siano già caricati in un bucket Cloud Storage.
Nella console Google Cloud, vai alla pagina BigQuery.
Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.
Fai clic su Avvia traduzione.
Compila la finestra di dialogo di configurazione della traduzione.
- In Nome visualizzato, digita un nome per il job di traduzione. Il nome può contenere lettere, numeri o trattini bassi.
- 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 tuoi dati superino i confini di località, seleziona la regione
eu
. Il job di traduzione funziona meglio se scegli la stessa posizione del bucket del file di origine. - Per Dialetto di origine, seleziona il dialetto SQL che vuoi tradurre.
- Per Dialetto di destinazione, seleziona BigQuery.
Tocca Avanti.
In Posizione di origine, specifica il percorso della cartella Cloud Storage contenente i file da tradurre. Puoi digitare il percorso nel formato
bucket_name/folder_name/
o utilizzare l'opzione Sfoglia.Tocca Avanti.
In Posizione di destinazione, specifica il percorso della cartella Cloud Storage di destinazione per i file tradotti. Puoi digitare il percorso nel formato
bucket_name/folder_name/
o utilizzare l'opzione Sfoglia.Se esegui traduzioni che non è necessario specificare nomi degli oggetti predefiniti o mapping dei nomi da origine a destinazione, vai al passaggio 11. In caso contrario, fai clic su Avanti.
Compila le impostazioni facoltative necessarie.
Facoltativo. In Database predefinito, digita un nome del database predefinito da utilizzare con i file di origine. Il traduttore utilizza questo nome predefinito del database per risolvere i nomi completi degli oggetti SQL in cui manca il nome del database.
Facoltativo. In Percorso di ricerca di schemi, specifica uno schema da cercare quando il traduttore deve risolvere i nomi completi degli oggetti SQL nei file di origine in cui manca il nome dello schema. Se i file di origine utilizzano una serie di nomi di schema diversi, fai clic su Aggiungi nome schema e aggiungi un valore per ciascun nome di schema a cui potrebbe essere fatto riferimento.
Il traduttore cerca i file di metadati che hai fornito per convalidare le tabelle con i nomi degli schemi. Se non è possibile determinare un'opzione definita dai metadati, il primo nome dello schema inserito viene utilizzato come predefinito. Per saperne di più su come viene utilizzato il nome dello schema predefinito, consulta lo schema predefinito.
Facoltativo. Se vuoi specificare regole di mappatura dei nomi per rinominare gli oggetti SQL tra il sistema di origine e BigQuery durante la traduzione, puoi fornire un file JSON con la coppia di mapping dei nomi oppure utilizzare la console Google Cloud per specificare i valori da mappare.
Per utilizzare un file JSON:
- Fai clic su Carica file JSON per la mappatura dei nomi.
Individua la posizione di un file di mapping dei nomi nel formato appropriato, selezionalo e fai clic su Apri.
Tieni presente che le dimensioni del file devono essere inferiori a 5 MB.
Per utilizzare la console Google Cloud:
- Fai clic su Aggiungi coppia di mapping dei nomi.
- Aggiungi le parti appropriate del nome dell'oggetto di origine nei campi Database, Schema, Relazione e Attributo nella colonna Origine.
- Aggiungi le parti del nome dell'oggetto di destinazione in BigQuery nei campi della colonna Target.
- In Tipo, seleziona il tipo di oggetto che descrive l'oggetto che stai mappando.
- Ripeti i passaggi 1-4 finché non hai specificato tutte le coppie di mapping dei nomi necessarie. Tieni presente che puoi specificare solo fino a 25 coppie di mappatura dei nomi quando utilizzi la console Google Cloud.
Fai clic su Crea per avviare il job di traduzione.
Una volta creato il job di traduzione, puoi visualizzarne lo stato nell'elenco dei job di traduzione.
Esplora l'output della traduzione
Dopo aver eseguito il job di traduzione, puoi visualizzare le informazioni sul job nella console Google Cloud. Se hai utilizzato la console Google Cloud per eseguire il job, puoi visualizzare i risultati nel bucket Cloud Storage di destinazione specificato. Se hai utilizzato il client di traduzione batch per eseguire il job, puoi visualizzare i risultati nella directory di output specificata. Il traduttore SQL batch restituisce i seguenti file nella destinazione specificata:
- I file tradotti.
- Il report di riepilogo della traduzione in formato CSV.
- Il mapping dei nomi di output utilizzato in formato JSON.
Output della console Google Cloud
Per visualizzare i dettagli del job di traduzione, segui questi passaggi:
Nella console Google Cloud, vai alla pagina BigQuery.
Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.
Nell'elenco dei job di traduzione, individua il job per cui vuoi visualizzare i dettagli della traduzione. Quindi, fai clic sul nome del job di traduzione.
Nella sezione Risultati, puoi vedere la percentuale di successo complessiva della traduzione, il numero di istruzioni elaborate e la durata del job.
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 ogni problema. Puoi anche selezionare una categoria di problema per visualizzare i messaggi di log associati a quella categoria di problema (Anteprima).
Seleziona la scheda Messaggi di log per visualizzare ulteriori dettagli su ciascun problema di traduzione, tra cui la categoria del problema, il messaggio del problema specifico e un link al file in cui si è verificato. Puoi selezionare un problema nella scheda Messaggio di log per aprire la scheda Codice che mostra il file di input e di output, se applicabile (Anteprima).
Seleziona la scheda Configurazione traduzione per visualizzare i dettagli di configurazione dei 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 job di traduzione.
Per vedere il file di riepilogo nella console Google Cloud, segui questi passaggi:
Nella console Google Cloud, vai alla pagina BigQuery.
Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.
Nell'elenco dei job di traduzione, individua il job che ti interessa e fai clic su Mostra dettagli nella colonna Stato.
Nella sezione Report sulla traduzione, fai clic su batch_translation_report.csv.
Nella pagina Dettagli oggetto, fai clic sul valore nella riga URL autenticato per visualizzare il file nel browser.
Nella tabella seguente vengono descritte le colonne del file di riepilogo:
Colonna | Descrizione |
---|---|
Timestamp | Il timestamp in cui si è verificato il problema. |
FilePath | Il percorso del file di origine a cui è associato il problema. |
FileName | Il nome del file di origine a cui è associato il problema. |
ScriptLine | Il numero di riga in cui si è verificato il problema. |
ScriptColumn | Il numero di colonna in cui si è verificato il problema. |
TranspilerComponent | Il componente interno del motore di traduzione in cui si è verificato l'avviso o l'errore. Questa colonna potrebbe essere vuota. |
Ambiente | L'ambiente del dialetto di traduzione associato all'avviso o all'errore. Questa colonna potrebbe essere vuota. |
ObjectName | L'oggetto SQL nel file di origine associato all'avviso o all'errore. Questa colonna potrebbe essere vuota. |
Gravità | La gravità del problema (avviso o errore). |
Categoria | La categoria del problema di traduzione. |
SourceType | L'origine del problema. Il valore in questa colonna può essere SQL , che indica un problema nei file SQL di input, oppure METADATA , che indica un problema nel pacchetto dei metadati. |
Messaggio | L'avviso o il messaggio di errore relativo al problema di traduzione. |
ScriptContext | Lo snippet SQL nel file di origine associato al problema. |
Azione | L'azione che ti consigliamo di eseguire per risolvere il problema. |
Scheda Codice
La scheda Codice consente di rivedere ulteriori informazioni sui file di input e di output per un determinato job di traduzione. Nella scheda del codice, puoi esaminare i file utilizzati in un job di traduzione, esaminare un confronto affiancato tra un file di input e la sua traduzione per individuare eventuali inesattezze e visualizzare i riepiloghi dei log e i messaggi relativi a un file specifico in un job.
Per accedere alla scheda del codice, segui questi passaggi:
Nella console Google Cloud, vai alla pagina BigQuery.
Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.
Nell'elenco dei job di traduzione, individua il job che ti interessa, quindi fai clic su Mostra dettagli nella colonna Stato.
Seleziona Scheda Codice.
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 essere diverse dalle regole di mappatura dei nomi di output che hai specificato per il job di traduzione, a causa di conflitti nelle regole di mappatura dei nomi o della mancanza di regole di mappatura 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. Se lo sono, crea nuove regole di mappatura dei nomi di output in grado di risolvere 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.
Esegui il debug delle query SQL tradotte in batch con il traduttore SQL interattivo
Puoi utilizzare il traduttore SQL interattivo BigQuery per esaminare una query SQL o eseguirne il debug utilizzando gli stessi metadati o le stesse informazioni di mappatura degli oggetti del database di origine. Dopo aver completato un job di traduzione batch, BigQuery genera un ID configurazione di traduzione contenente informazioni sui metadati del job, sulla mappatura degli oggetti o sul percorso di ricerca dello schema, a seconda delle esigenze della query. Puoi utilizzare 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 di configurazione della traduzione batch, segui questi passaggi:
Nella console Google Cloud, vai alla pagina BigQuery.
Nella sezione Migrazione del menu di navigazione, fai clic su Traduzione SQL.
Nell'elenco dei job di traduzione, individua il job che ti interessa, quindi fai clic su > Apri traduzione interattiva.
Altre opzioni
Si apre il traduttore SQL interattivo BigQuery con l'ID configurazione della traduzione batch corrispondente. Per visualizzare l'ID configurazione della traduzione per la traduzione interattiva, fai clic su Altro > Impostazioni di traduzione nel traduttore interattivo.
Limitazioni
Il traduttore non può tradurre le funzioni definite dall'utente (UDF) da lingue diverse dall'SQL, perché non può analizzarle per determinare i tipi di dati di input e di output. Ciò causa un'imprecisa traduzione delle istruzioni SQL che fanno riferimento a queste funzioni definite dall'utente. Per assicurarti che venga fatto riferimento corretto alle funzioni definite dall'utente non SQL durante la traduzione, utilizza un codice SQL valido per creare funzioni definite dall'utente segnaposto con le stesse firme.
Ad esempio, supponi di avere una funzione definita dall'utente scritta in C che calcola la somma di due numeri interi. Per assicurarti che le istruzioni SQL che fanno riferimento a questa funzione definita dall'utente vengano tradotte correttamente, crea una funzione SQL segnaposto con la stessa firma della funzione definita dall'utente C, come mostrato nell'esempio seguente:
CREATE FUNCTION Test.MySum (a INT, b INT)
RETURNS INT
LANGUAGE SQL
RETURN a + b;
Salva questa funzione definita dall'utente segnaposto in un file di testo e includi quel file come uno dei file di origine per il job di traduzione. Ciò consente al traduttore di apprendere la definizione della funzione definita dall'utente e identificare i tipi di dati di input e di output previsti.
Quota e limiti
- Si applicano le quote dell'API BigQuery Migration.
- Ogni progetto può avere al massimo 10 attività di traduzione attive.
- Anche se non esiste un limite fisso al numero totale di file di origine e di metadati, ti consigliamo di mantenere il numero di file inferiore a 1000 per ottenere prestazioni migliori.
Risolvere gli errori di traduzione
Problemi di traduzione in RelationNotFound
o AttributeNotFound
La traduzione funziona meglio con i DDL di metadati. Quando non è possibile trovare le definizioni degli oggetti SQL, il motore di traduzione segnala problemi RelationNotFound
o AttributeNotFound
. Ti consigliamo di utilizzare l'estrattore di metadati per generare pacchetti di metadati
e 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, poiché spesso consente di correggere molti altri errori causati indirettamente dalla mancanza di metadati.
Per ulteriori informazioni, consulta la sezione 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 di output comporta le normali tariffe. Per ulteriori informazioni, consulta i prezzi dell'archiviazione.
Passaggi successivi
Scopri di più sui seguenti passaggi nella migrazione dei 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