Esegui la migrazione del codice con il traduttore SQL batch

Per le nuove traduzioni, ti consigliamo di utilizzare l'API di traduzione per tradurre i tuoi script SQL. L'API di traduzione funziona in modo molto simile al traduttore SQL batch, ma senza dover installare o utilizzare il codice client.

Questo documento descrive come utilizzare il traduttore SQL batch BigQuery per tradurre script scritti in altri dialetti SQL in GoogleSQL query. 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:

  1. Assicurati di disporre di tutte le autorizzazioni richieste.
  2. Abilitare l'API BigQuery Migration.
  3. Raccogli i file sorgente contenenti gli script e le query SQL da tradotto in inglese.
  4. Facoltativo. Crea un file di metadati per migliorare la precisione della traduzione.
  5. Facoltativo. Decidi se devi mappare i nomi degli oggetti SQL nei file di origine con nuovi nomi in BigQuery. Stabilisci quali regole di mappatura dei nomi utilizzare da utilizzare se necessario.
  6. Decidi quale metodo utilizzare per inviare il job di traduzione.
  7. 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, abilita l'API BigQuery Migration nel modo seguente:

  1. Nella console Google Cloud, vai alla pagina dell'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 codice 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 aiutare il servizio a generare risultati di traduzione più accurati, ti consigliamo che fornisci file di metadati. Tuttavia, questo 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 nella traduzione insieme ai file di origine cartella di origine. Il traduttore li rileva automaticamente e li utilizza per tradurre i file sorgente, non è necessario configurare ulteriori impostazioni.

Per generare informazioni sui metadati utilizzando Strumento dwh-migration-dumper, consulta Generare metadati per la traduzione.

Per fornire i tuoi metadati, raccogli il Data Definition Language (DDL) per gli oggetti SQL del sistema di origine in file di testo separati.

Mappa i nomi degli oggetti SQL

Se vuoi, puoi eseguire Mappatura del nome output durante la modalità batch una traduzione automatica. 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 vuoi che oggetto da nominare 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 inviare il job utilizzando la riga di comando. Questo non richiede di caricare manualmente i file di origine di archiviazione ideale in Cloud Storage. Il client utilizza ancora Cloud Storage per archiviare i file durante l'elaborazione del job di traduzione.

    Il client di traduzione batch è un file Python open source che ti consente di tradurre i file sorgente che si trovano nel tuo client machine e fare in modo che i file tradotti vengano restituiti 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 di file di origine di archiviazione ideale 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 utilizzati per trasformare dell'output di 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 di traduzione batch, puoi caricare il file YAML 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. La 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 preview:

  • Apache Spark SQL
  • T-SQL di Azure Synapse
  • SQL Greenplum
  • SQL IBM DB2
  • SQL MySQL
  • Oracle SQL, PL/SQL, Exadata
  • SQL PostgreSQL
  • Trino o PrestoSQL
  • SQL Snowflake
  • T-SQL per SQL Server
  • SQLite
  • SQL vertica

Località

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

Descrizione 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 icona foglia A basse emissioni di CO2
Madrid europe-southwest1 icona foglia A basse emissioni di CO2
Belgio europe-west1 icona foglia A basse emissioni di CO2
Londra europe-west2 icona foglia A basse emissioni di CO2
Francoforte europe-west3 icona foglia A basse emissioni di CO2
Paesi Bassi europe-west4 icona foglia A basse emissioni di CO2
Zurigo europe-west6 icona foglia A basse emissioni di CO2
Parigi europe-west9 icona foglia A basse emissioni di CO2
Torino europe-west12
Americhe
San Paolo southamerica-east1 icona foglia A basse emissioni di CO2
Stati Uniti (più regioni) us
Iowa us-central1 icona foglia A basse emissioni di CO2
Carolina del Sud us-east1
Virginia del Nord us-east4
Columbus, Ohio us-east5
Dallas us-south1 icona foglia A basse emissioni di CO2
Oregon us-west1 icona foglia A basse emissioni di CO2
Los Angeles us-west2
Salt Lake City us-west3

Inviare un job di traduzione

Segui questi passaggi per avviare un job di traduzione, visualizzarne l'avanzamento e controllare che consentono di analizzare i dati e visualizzare i risultati.

Client di traduzione batch

  1. Installa il client di traduzione batch e Google Cloud CLI.

  2. Genera un file di credenziali della gcloud CLI gcloud.

  3. Nella directory di installazione del client di traduzione batch, utilizza il testo un editor di tua scelta per aprire config.yaml e modifica 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.
  4. Salva le modifiche e chiudi il file config.yaml.

  5. Inserisci i file di origine e di metadati nella directory di input.

  6. Esegui il client di traduzione batch utilizzando questo comando:

    bin/dwh-migration-client
    

    Una volta creato il job di traduzione, puoi visualizzarne lo stato nella dei job di traduzione nella console Google Cloud.

  7. Facoltativo. Una volta completato il job di traduzione, elimina i file il job creato nel bucket Cloud Storage specificato, nell'ordine per evitare costi di archiviazione.

Console

Questi passaggi presuppongono che i file di origine siano caricati in un nel bucket Cloud Storage.

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

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su SQL. traduzione automatica.

  3. Fai clic su Avvia traduzione.

  4. 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 tuoi dati superino i confini di una località, seleziona Regione eu. Il job di traduzione ha le prestazioni migliori quando scegli posizione come bucket dei file di origine.
    3. Per Dialetto di origine, seleziona il dialetto SQL che vuoi traduci.
    4. Per Dialetto di destinazione, seleziona BigQuery.
  5. Fai clic su Avanti.

  6. In Posizione di origine, specifica il percorso della cartella di Cloud Storage. contenente i file da tradurre. Puoi digitare il percorso nel formato bucket_name/folder_name/ o usa Sfoglia.

  7. Fai clic su Avanti.

  8. In Località di destinazione, specifica il percorso del Cloud Storage di destinazione cartella per i file tradotti. Puoi digitare il percorso nel formato bucket_name/folder_name/ o utilizza l'opzione Sfoglia.

  9. Se stai eseguendo traduzioni che non hanno bisogno di nomi degli oggetti predefiniti o la mappatura del nome da origine a destinazione specificata, vai al passaggio 11. Altrimenti, fai clic su Avanti.

  10. 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 Add Schema Name (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 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 mapping dei nomi.
      2. Aggiungi le parti appropriate del nome dell'oggetto di origine nella sezione 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.
  11. Fai clic su Crea per avviare il job di traduzione.

Una volta creato il job di traduzione, puoi visualizzarne lo stato nella dei job di traduzione.

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 genera i seguenti file nella destinazione specificata:

  • I file tradotti.
  • Il report di riepilogo della traduzione in formato CSV.
  • Il mapping del nome di output utilizzato in formato JSON.

Output della console Google Cloud

Per visualizzare i dettagli del job di traduzione, segui questi passaggi:

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

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su SQL. traduzione automatica.

  3. Nell'elenco dei job di traduzione, individua il job per cui vuoi visualizzare il dettagli della traduzione. Quindi, fai clic sul nome del job di traduzione.

  4. Nella sezione Risultati puoi vedere il successo complessivo delle traduzioni la velocità effettiva, il numero di istruzioni elaborate e la durata del job.

  5. 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 associate alla categoria di problema (Anteprima).

  6. 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 nella sezione Messaggio per aprire la scheda Codice che visualizza il file di input e di output, se applicabile (anteprima).

  7. Seleziona la scheda Configurazione di traduzione per visualizzare il job di traduzione della configurazione.

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:

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

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su SQL. traduzione automatica.

  3. Nell'elenco dei job di traduzione, individua il job che ti interessa. Fai clic su Mostra dettagli nella colonna Stato.

  4. Nella sezione Report sulla traduzione, fai clic su batch_translation_report.csv.

  5. 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 viene visualizzato l'avviso o l'errore si è verificato un 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 di problemi della traduzione.
SourceType L'origine 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 eseguire per risolvere il problema.

Scheda Codice

La scheda Codice ti consente di rivedere ulteriori informazioni sull'input e i file di output per un particolare 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 Codice, segui questi passaggi:

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

    Vai a BigQuery

  2. Nella sezione Migrazione del pannello di navigazione, fai clic su Traduzione SQL.

  3. Nell'elenco dei job di traduzione, individua il job che ti interessa, quindi fai clic su Mostra dettagli nella colonna Stato.

  4. Seleziona Scheda Codice.

File di mapping dei nomi di output utilizzato

Questo file JSON contiene le regole di mappatura dei nomi di output utilizzate dalla di un job di traduzione. Le regole in questo file possono essere diverse Regole per la mappatura dei nomi di output specificato per il job di traduzione, a causa di conflitti regole di mappatura dei nomi o assenza di regole di mappatura dei nomi per gli oggetti SQL identificati durante la traduzione. Esamina questo file in determinare se le regole di mappatura dei nomi necessitano di correzioni. Se sì, crea nuove regole di mappatura dei nomi di output che indirizzino gli 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 formato 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 usare 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. Utilizzerai 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:

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

    Vai a BigQuery

  2. Nella sezione Migrazione del menu di navigazione, fai clic su SQL. traduzione automatica.

  3. 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 BigQuery ora si apre con l'ID di configurazione della traduzione batch corrispondente. Per visualizzare dell'ID configurazione della traduzione interattiva 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 dalle lingue diversi da SQL, perché non può analizzarli per determinare i tipi di dati di input e output. Questo causa la traduzione delle istruzioni SQL che indicano che queste funzioni definite dall'utente non sono precise. 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 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 siano correttamente tradotto, crea una funzione SQL segnaposto con la stessa firma C, come illustrato 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. Questo permette al traduttore di apprendere la definizione delle funzioni definite 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 fonti e metadati, , ti consigliamo di mantenere il numero di file al di sotto di 1000 per migliorare delle prestazioni.

Risolvere gli errori di traduzione

Problemi di traduzione in RelationNotFound o AttributeNotFound

La traduzione funziona meglio con i DDL di metadati. Quando non è possibile definire gli oggetti SQL trovato, il motore di traduzione genera RelationNotFound o AttributeNotFound che le applicazioni presentino problemi di prestazioni. Consigliamo di utilizzare l'estrattore di metadati per generare pacchetti di metadati. per assicurarsi che siano presenti tutte le definizioni degli oggetti. L'aggiunta di metadati primo passaggio consigliato per risolvere la maggior parte degli errori di traduzione, poiché spesso consente di correggere molti altri errori che sono causati indirettamente dalla mancanza di metadati.

Per saperne di più, consulta Generare metadati per la traduzione e la valutazione.

Prezzi

Non è previsto alcun costo per l'utilizzo del traduttore SQL batch. Tuttavia, per archiviare i file di input e output comporta le normali tariffe. Per ulteriori informazioni informazioni, vedi Prezzi dello spazio di archiviazione.

Passaggi successivi

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