Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui la migrazione del codice con il traduttore SQL batch

Questo documento descrive come utilizzare il traduttore SQL batch in BigQuery per tradurre gli script scritti in altri dialetti SQL in query GoogleSQL. Questo documento è rivolto agli utenti che conoscono il 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.
Abilita l'API BigQuery Migration.
Raccogliere i file di origine contenenti gli script e le query SQL 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 a nuovi nomi in BigQuery. Determina quali regole di mappatura dei nomi utilizzare, se necessario.
Decidi quale metodo utilizzare per inviare il job di traduzione.
Caricare i file di origine in Cloud Storage.

Autorizzazioni obbligatorie

Devi disporre delle seguenti autorizzazioni sul progetto per abilitare BigQuery Migration Service:

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

Devi disporre delle seguenti autorizzazioni sul progetto per accedere e utilizzare il BigQuery Migration Service:

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 nel bucket Cloud Storage di origine.
storage.objects.list nel bucket Cloud Storage di origine.
storage.objects.create nel bucket Cloud Storage di destinazione.

Puoi disporre di tutte le autorizzazioni Cloud Storage necessarie sopra i 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, attiva l'API BigQuery Migration come segue:

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

Vai all'API BigQuery Migration
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 i metodi a tua disposizione.

Creare file di metadati

Per consentire al servizio di generare risultati di traduzione più accurati, ti consigliamo che fornisci file di metadati. Tuttavia, non è obbligatorio.

Puoi utilizzare lo strumento di estrazione a riga di comando dwh-migration-dumper per generare i metadati informazioni oppure puoi fornire i tuoi file di metadati. Una volta preparati i file di metadati, puoi includerli insieme ai file di origine nella cartella della sorgente della traduzione. Il traduttore li rileva automaticamente e li utilizza per tradurre i file sorgente, non è necessario configurare ulteriori impostazioni.

Per generare informazioni sui metadati utilizzando lo strumentodwh-migration-dumper, consulta Genera 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

Se vuoi, puoi eseguire la mappatura dei nomi di output durante la traduzione collettiva. Quando utilizzi la mappatura dei nomi di output, specifichi le regole di mappatura dei nomi che modificano i nomi degli oggetti SQL nel sistema di origine con nuovi nomi in BigQuery. Ad esempio, potresti avere l'oggetto schema1.table1 nel tuo sistema di origine e volere che questo oggetto abbia il nome project1.dataset1.table1 in BigQuery. Se utilizzi la mappatura dei nomi di output, definisci le regole di mappatura dei nomi prima di avviare un job di traduzione batch. Tu puoi inserire queste regole manualmente durante la configurazione del job oppure puoi creare un File JSON contenente le regole di mappatura dei nomi e caricala.

Decidi come inviare il job di traduzione

Hai a disposizione 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 invialo utilizzando la riga di comando. Questo approccio non richiede il caricamento manuale dei file di origine su Cloud Storage. Il cliente utilizza ancora Cloud Storage per archiviare i file durante l'elaborazione dei job di traduzione.

Il client di traduzione batch è un client Python open source che consente di tradurre i file di origine situati sulla macchina locale e di esportare i file tradotti in una directory locale. Puoi configurare il client per l'utilizzo di base modificando alcune impostazioni in di configurazione del proprio file di configurazione. Se vuoi, puoi anche configurare il client eseguire attività più complesse, come la sostituzione di macro, e la post-elaborazione degli input e degli output di traduzione. Per ulteriori informazioni, vedere il client di traduzione batch leggimi.
Console Google Cloud: configura e invia un job utilizzando un utente a riga di comando. Questo approccio richiede il caricamento dei file di origine su Cloud Storage.

Creare file YAML di configurazione

Facoltativamente, puoi creare e utilizzare file YAML di configurazione per personalizzare le traduzioni collettive. Questi file possono essere utilizzati per trasformare l'output della traduzione in vari modi. Ad esempio: puoi creare un file YAML di configurazione per cambiare le maiuscole/minuscole 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 di configurazione YAML nel bucket Cloud Storage contenente i file di origine.

Se vuoi utilizzare il client di traduzione batch, puoi inserire il file YAML nella cartella di input della 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 che vuoi tradurre in Cloud Storage. Tu 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 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
Interfaccia a riga di comando Apache HiveQL e 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 IBM DB2
MySQL SQL
Oracle SQL, PL/SQL, Exadata
SQL di PostgreSQL
Trino o PrestoSQL
SQL Snowflake
T-SQL di SQL Server
SQLite
SQL vertica

Località

Il traduttore SQL batch è disponibile nelle seguenti località di elaborazione:

	Descrizione della regione	Nome regione	Dettagli
Asia Pacifico
	Tokyo	`asia-northeast1`
	Mumbai	`asia-south1`
	Singapore	`asia-southeast1`
	Sydney	`australia-southeast1`
Europa
	Multiregionale UE	`eu`
	Varsavia	`europe-central2`
	Finlandia	`europe-north1`	A basse emissioni di CO₂
	Madrid	`europe-southwest1`	Bassi livelli di CO₂
	Belgio	`europe-west1`	Bassi livelli di CO₂
	Londra	`europe-west2`	Bassi livelli di CO₂
	Francoforte	`europe-west3`	A basse emissioni di CO₂
	Paesi Bassi	`europe-west4`	A basse emissioni di CO₂
	Zurigo	`europe-west6`	Bassi livelli di CO₂
	Parigi	`europe-west9`	A basse emissioni di CO₂
	Torino	`europe-west12`
Americhe
	San Paolo	`southamerica-east1`	A basse emissioni di CO₂
	Stati Uniti (più regioni)	`us`
	Iowa	`us-central1`	A basse emissioni di CO₂
	Carolina del Sud	`us-east1`
	Virginia del Nord	`us-east4`
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	Bassi livelli di CO₂
	Oregon	`us-west1`	Bassi livelli di CO₂
	Los Angeles	`us-west2`
	Salt Lake City	`us-west3`

Invia un job di traduzione

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

Console

Questi passaggi presuppongono che tu abbia già caricato i file di origine in un bucket Cloud Storage.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nella sezione Migrazione del riquadro di navigazione, fai clic su Traduzione SQL.
Fai clic su Avvia traduzione.
Compila la finestra di dialogo di configurazione della traduzione.
1. In Nome visualizzato, digita un nome per il job di traduzione. Il nome può contenere lettere, numeri o trattini bassi.
2. In Località di elaborazione, seleziona la località in cui vuoi di traduzione automatica da eseguire. Ad esempio, se ti trovi in Europa e non vuoi che i dati superino i confini di località, seleziona la regione eu. Il job di traduzione ha il rendimento migliore se scegli la stessa posizione del bucket del file di origine.
3. Per Dialetto di origine, seleziona il dialetto SQL da tradurre.
4. Per Dialetto di destinazione, seleziona BigQuery.
Fai clic su Avanti.
In Posizione di origine, specifica il percorso della cartella di Cloud Storage. contenente i file da tradurre. Puoi digitare il percorso nel formatobucket_name/folder_name/ o utilizzare l'opzione Sfoglia.
Fai clic su Avanti.
In Località di destinazione, specifica il percorso del Cloud Storage di destinazione per i file tradotti. Puoi digitare il percorso nel formato bucket_name/folder_name/ o utilizzare l'opzione Sfoglia.
Se stai effettuando traduzioni per le quali non è necessario specificare nomi di oggetti predefiniti o la mappatura dei nomi da origine a destinazione, vai al passaggio 11. Altrimenti, fai clic su Avanti.
Compila le impostazioni facoltative di cui hai bisogno.
1. Facoltativo. In Database predefinito, digita una nome database predefinito da utilizzare con i file di origine. Il traduttore usa questo nome del database predefinito per risolvere gli oggetti SQL nomi completi in cui manca il nome del database.
2. Facoltativo. Per Percorso di ricerca schema, specifica uno schema da cercare quando il traduttore deve risolvere gli oggetti SQL nomi completi 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 ogni nome di schema a cui potrebbe essere fatto riferimento.
  
  Il traduttore cerca nei file di metadati che hai fornito per convalidare le tabelle con i nomi degli schemi. Se non è possibile determinare un'opzione definita dai metadati, viene utilizzato per impostazione predefinita il primo nome dello schema inserito. Per maggiori informazioni su come viene utilizzato il nome dello schema predefinito, consulta la sezione Schema predefinito.
3. Facoltativo. Se vuoi specificare regole di mappatura dei nomi per rinominare SQL oggetti tra il sistema di origine e BigQuery durante la traduzione, puoi fornire un'immagine file JSON con la coppia di mapping dei nomi oppure puoi utilizzare nella console Google Cloud per specificare i valori da mappare.
  
  Per utilizzare un file JSON:
  1. Fai clic su Carica un file JSON per la mappatura dei nomi.
  2. Individua la posizione di un file di mapping dei nomi nella 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:
  1. Fai clic su Aggiungi coppia di mappatura dei nomi.
  2. Aggiungi le parti appropriate del nome dell'oggetto di origine nei campi Database, Schema, Relazione e Attributo nella colonna Origine.
  3. Aggiungi le parti del nome dell'oggetto di destinazione in BigQuery nei campi della colonna Target.
  4. In Tipo, seleziona il tipo di oggetto che descrive l'oggetto che stai mappando.
  5. Ripeti i passaggi da 1 a 4 finché non hai specificato tutta la mappatura dei nomi. le coppie necessarie. Tieni presente che puoi specificare solo fino a 25 nomi quando si utilizza 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.

Client di traduzione batch

Installa il client di traduzione batch e Google Cloud CLI.
Genera un file delle credenziali dell'interfaccia a riga di comando gcloud.
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 che vuoi per il job di traduzione batch. Puoi trovarlo nel Riquadro Informazioni sul progetto nella Pagina di benvenuto della console Google Cloud per del progetto.
- gcs_bucket: digita il nome del bucket Cloud Storage che è stato creato per il batch, che il client di traduzione deve utilizzare per archiviare i file durante il job di traduzione e l'elaborazione dei dati.
- input_directory: digita il percorso assoluto o relativo della directory contenente i file di origine ed eventuali file di metadati.
- output_directory: digita il percorso assoluto o relativo del target. 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. Al termine del job di traduzione, elimina i file creati dal job nel bucket Cloud Storage specificato per evitare costi di archiviazione.

Esplora l'output di traduzione

Dopo aver eseguito il job di traduzione, puoi visualizzare le relative informazioni nella console Google Cloud. Se hai utilizzato la console Google Cloud per eseguire il job, puoi visualizzarne i risultati nella destinazione del bucket Cloud Storage specificato. Se hai utilizzato il batch di un client di traduzione per eseguire il job, puoi vedere i risultati della directory specificata. Il traduttore SQL batch esporta i seguenti file nella destinazione specificata:

I file tradotti.
Il report di riepilogo della traduzione in formato CSV.
La mappatura dei nomi dell'output consumato in formato JSON.

Output della console Google Cloud

Per visualizzare i dettagli del job di traduzione:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nella sezione Migrazione del pannello di navigazione, fai clic su SQL. traduzione automatica.
Nell'elenco dei job di traduzione, individua il job di cui vuoi visualizzare i dettagli. Quindi, fai clic sul nome del job di traduzione.
Nella sezione Risultati, puoi vedere il tasso di successo complessivo della traduzione, il numero di istruzioni elaborate e la durata del job.
Seleziona la scheda Log Riepilogo per vedere un riepilogo dei problemi di traduzione. tra cui categorie di problemi, azioni suggerite e frequenza di ciascun problema si è verificato un errore. Puoi anche selezionare una categoria di problemi per visualizzare i messaggi di log associati (Anteprima).
Seleziona la scheda Messaggi di log per visualizzare ulteriori dettagli su ogni traduzione problema, tra cui la categoria del problema, il messaggio relativo al problema specifico e un link al file in cui si è verificato il problema. Puoi selezionare un problema nel Log Messaggio per aprire la scheda Codice che visualizza il file di input e di output, se applicabile (anteprima).
Seleziona la scheda Configurazione traduzione per visualizzare i dettagli di configurazione del job di traduzione.

Rapporto riepilogativo

Il report di riepilogo è un file CSV contenente una tabella di tutti i messaggi di avviso ed errore riscontrati durante il job di traduzione.

Per visualizzare il file di riepilogo nella console Google Cloud:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nella sezione Migrazione del riquadro 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 in URL autenticato. riga per vedere il file nel browser.

Nella tabella seguente vengono descritte le colonne dei 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 avviso o errore. Questa colonna potrebbe essere vuota.
ObjectName	L'oggetto SQL nel file di origine associato all'avviso o un errore. Questa colonna potrebbe essere vuota.
Gravità	Gravità del problema (avviso o errore).
Categoria	La categoria del problema di traduzione.
SourceType	La fonte del problema. Il valore di questa colonna può essere `SQL`, a indicare un problema nei file SQL di input; oppure `METADATA`, che indica un problema nel pacchetto di metadati.
Messaggio	L'avviso relativo al problema di traduzione o il messaggio di errore.
ScriptContext	Lo snippet SQL nel file di origine associato al problema.
Azione	L'azione che ti consigliamo di intraprendere per risolvere il problema.

Scheda Codice

La scheda del codice ti consente di esaminare ulteriori informazioni sui file di input e di output per un determinato job di traduzione. Nella scheda Codice, puoi esaminare i file usati in un job di traduzione, esaminare confronto fianco a fianco di un file di input e la sua traslazione per qualsiasi e visualizzare riepiloghi dei log e messaggi relativi a un file specifico di un job.

Per accedere alla scheda del codice:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a 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 compito di traduzione. Le regole in questo file potrebbero essere diverse dalle regole di mappatura dei nomi di output specificate 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. In questo caso, crea nuove regole di mappatura dei nomi in uscita 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.

Esegui il debug delle query SQL tradotte in batch con il traduttore SQL interattivo

Puoi utilizzare il traduttore SQL interattivo BigQuery rivedere o eseguire il debug di una query SQL utilizzando gli stessi metadati o la stessa mappatura degli oggetti come database di origine. Dopo aver completato un job di traduzione batch, BigQuery genera un ID configurazione della traduzione che contiene informazioni sui metadati del job, sulla mappatura degli oggetti o sulla ricerca dello schema un percorso personalizzato, se applicabile alla query. Utilizza l'ID configurazione della traduzione batch con il traduttore SQL interattivo per eseguire query SQL con la configurazione specificata.

Avvia una traduzione SQL interattiva utilizzando una traduzione batch di configurazione, segui questi passaggi:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nella sezione Migrazione del menu di navigazione, fai clic su SQL. traduzione automatica.
Nell'elenco dei job di traduzione, individua il job che ti interessa, e poi fai clic su Altre opzioni > Apri Traduzione interattiva.

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

Limitazioni

Il traduttore non può tradurre le funzioni definite dall'utente dalle lingue diversi da SQL, perché non può analizzarli per determinare i tipi di dati di input e output. Di conseguenza, la traduzione delle istruzioni SQL che fanno riferimento a queste funzioni definite dall'utente non è accurata. Per assicurarti che le funzioni definite dall'utente non SQL a cui viene fatto riferimento correttamente durante la traduzione, usa un'SQL valido per creare un segnaposto funzioni definite dall'utente con le stesse firme.

Ad esempio, supponiamo di avere una UDF scritta in C che calcola la somma di due interi. Per assicurarti che le istruzioni SQL che fanno riferimento a questa UDF vengano tradotte correttamente, crea un'UDF SQL segnaposto che condivida la stessa firma dell'UDF 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 tale file come uno dei di origine per il job di traduzione. In questo modo, il traduttore può apprendere la definizione della UDF e identificare i tipi di dati di input e output previsti.

Quote 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 per il numero totale di file di metadati e di origine, consigliamo di mantenere il numero di file inferiore a 1000 per migliorare le prestazioni.

Risolvere gli errori di traduzione

`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 genera problemi RelationNotFound o AttributeNotFound. Ti consigliamo di utilizzare l'estrattore di 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, consulta 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 Prezzi dello spazio di archiviazione.

Passaggi successivi

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