Tradurre query SQL con l'API Translation

Questo documento descrive come utilizzare l'API di traduzione in BigQuery per tradurre gli script scritti in altri dialetti SQL in query GoogleSQL. L'API di traduzione può semplificare la procedura di migrazione dei carichi di lavoro a BigQuery.

Prima di iniziare

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

  1. Assicurati di disporre di tutte le autorizzazioni richieste.
  2. Abilita l'API BigQuery Migration.
  3. Raccogliere i file di origine contenenti gli script e le query SQL da tradurre.
  4. Carica i file di origine su Cloud Storage.

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per creare job di traduzione utilizzando l'API di traduzione, chiedi all'amministratore di concederti il ruolo IAM MigrationWorkflow Editor (roles/bigquerymigration.editor) nella risorsa parent. Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare job di traduzione utilizzando l'API di traduzione. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per creare job di traduzione utilizzando l'API Translation sono necessarie le seguenti autorizzazioni:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abilita l'API BigQuery Migration

Se il progetto Google Cloud CLI è stato creato prima del 15 febbraio 2022, attiva l'API BigQuery Migration come segue:

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

    Vai all'API BigQuery Migration

  2. Fai clic su Attiva.

Carica i file di input su Cloud Storage

Se vuoi utilizzare la Google Cloud console 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 di file su Cloud Storage, consulta Creare bucket e Caricare oggetti da un file system.

Tipi di attività supportati

L'API di traduzione può tradurre i seguenti dialetti SQL in GoogleSQL:

  • Amazon Redshift SQL - Redshift2BigQuery_Translation
  • Apache HiveQL e Beeline CLI - HiveQL2BigQuery_Translation
  • Apache Spark SQL - SparkSQL2BigQuery_Translation
  • Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
  • Greenplum SQL - Greenplum2BigQuery_Translation
  • IBM Db2 SQL - Db22BigQuery_Translation
  • IBM Netezza SQL e NZPLSQL - Netezza2BigQuery_Translation
  • MySQL SQL - MySQL2BigQuery_Translation
  • Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
  • PostgreSQL SQL - Postgresql2BigQuery_Translation
  • Presto o Trino SQL - Presto2BigQuery_Translation
  • Snowflake SQL - Snowflake2BigQuery_Translation
  • SQLite - SQLite2BigQuery_Translation
  • SQL Server T-SQL - SQLServer2BigQuery_Translation
  • Teradata e Teradata Vantage - Teradata2BigQuery_Translation
  • Vertica SQL - Vertica2BigQuery_Translation

Gestione di funzioni SQL non supportate con funzioni UDF di supporto

Quando traduci SQL da un dialetto di origine a BigQuery, alcune funzioni potrebbero non avere un equivalente diretto. Per risolvere il problema, BigQuery Migration Service (e la community BigQuery più ampia) forniscono funzioni definite dall'utente (UDF) di supporto che replicano il comportamento di queste funzioni del dialetto di origine non supportate.

Queste funzioni UDF si trovano spesso nel set di dati pubblico bqutil, consentendo alle query tradotte di farvi inizialmente riferimento utilizzando il formato bqutil.<dataset>.<function>(). Ad esempio: bqutil.fn.cw_count().

Considerazioni importanti per gli ambienti di produzione:

Sebbene bqutil offra un accesso pratico a queste funzioni UDF di supporto per la traduzione e i test iniziali, non è consigliabile fare affidamento diretto su bqutil per i carichi di lavoro di produzione per diversi motivi:

  1. Controllo della versione: il progetto bqutil ospita la versione più recente di queste funzioni definite dall'utente, il che significa che le relative definizioni possono cambiare nel tempo. Se la logica di una UDF viene aggiornata, fare affidamento direttamente su bqutil potrebbe comportare comportamenti imprevisti o modifiche che causano interruzioni nelle query di produzione.
  2. Isolamento delle dipendenze: il deployment delle funzioni definite dall'utente nel tuo progetto isola l'ambiente di produzione dalle modifiche esterne.
  3. Personalizzazione: potrebbe essere necessario modificare o ottimizzare queste UDF per adattarle meglio alla logica aziendale o ai requisiti di rendimento specifici. Questo è possibile solo se si trovano all'interno del tuo progetto.
  4. Sicurezza e governance: i criteri 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 nell'ambiente controllato è in linea con queste norme.

Esegui il deployment delle UDF di supporto nel progetto:

Per un utilizzo in produzione affidabile e stabile, devi implementare queste UDF di supporto nel tuo progetto e nel tuo set di dati. In questo modo avrai il pieno controllo sulla versione, sulla personalizzazione e sull'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 funzioni definite dall'utente nel tuo ambiente.

Località

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

Inviare un job di traduzione

Per inviare un job di traduzione utilizzando l'API Translation, utilizza il metodo projects.locations.workflows.create e fornisci un'istanza della risorsa MigrationWorkflow con un tipo di attività supportato.

Una volta inviato il job, puoi emettere una query per ottenere i risultati.

Creare una traduzione batch

Il seguente comando curl crea un job di traduzione batch in cui i file di input e di output vengono archiviati in Cloud Storage. Il campo source_target_mapping contiene un elenco che mappa le voci literal di origine a un percorso relativo facoltativo per l'output di destinazione.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Sostituisci quanto segue:

  • TYPE: il tipo di attività della traduzione, che determina il dialetto di origine e di destinazione.
  • TARGET_BASE: l'URI di base per tutti gli output della traduzione.
  • BASE: l'URI di base per tutti i file letti come origini per la traduzione.

  • TARGET_TYPES (facoltativo): i tipi di output generati. Se non specificato, viene generato SQL.

    • sql (predefinito): i file di query SQL tradotti.
    • suggestion: suggerimenti creati con AI.

    L'output viene archiviato in una sottocartella della directory di output. La sottocartella viene denominata in base al valore in TARGET_TYPES.

  • TOKEN: il token per l'autenticazione. Per generare un token, utilizza il comando gcloud auth print-access-token o OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).

  • PROJECT_ID: il progetto per elaborare la traduzione.

  • LOCATION: la posizione in cui viene elaborato il job.

Il comando precedente restituisce una risposta che include un ID flusso di lavoro scritto nel formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Esempio di traduzione batch

Per tradurre gli script SQL di Teradata nella directory Cloud Storagegs://my_data_bucket/teradata/input/ e archiviare i risultati nella directory Cloud Storage gs://my_data_bucket/teradata/output/, puoi utilizzare la seguente query:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

Questa chiamata restituirà un messaggio contenente l'ID del flusso di lavoro creato nel "name" campo:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Per ottenere lo stato aggiornato del flusso di lavoro, esegui una query GET. Il job invia gli output a Cloud Storage man mano che procede. Il job state viene modificato in COMPLETED dopo che sono stati generati tutti i target_types richiesti. Se l'attività va a buon fine, puoi trovare la query SQL tradotta in gs://my_data_bucket/teradata/output.

Esempio di traduzione batch con suggerimenti AI

L'esempio seguente traduce gli script SQL Teradata nella directory gs://my_data_bucket/teradata/input/ Cloud Storage e archivia i risultati nella directory Cloud Storage gs://my_data_bucket/teradata/output/ con suggerimenti aggiuntivi dell'AI:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

Una volta eseguita correttamente l'attività, i suggerimenti dell'AI sono disponibili nella directory gs://my_data_bucket/teradata/output/suggestion Cloud Storage.

Crea un job di traduzione interattiva con input e output di stringhe letterali

Il seguente comando curl crea un job di traduzione con input e output di stringhe litterali. Il campo source_target_mapping contiene un elenco che mappa le directory di origine a un percorso relativo facoltativo per l'output di destinazione.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Sostituisci quanto segue:

  • TYPE: il tipo di attività della traduzione, che determina il dialetto di origine e di destinazione.
  • PATH: l'identificatore della voce letterale, simile a un nome file o a un percorso.
  • STRING: stringa di dati di input letterali (ad esempio SQL) da tradurre.
  • TARGETS: i target previsti che l'utente vuole che vengano restituiti direttamente nella risposta nel formato literal. Devono essere nel formato dell'URI target (ad es. GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Gli elementi non presenti in questo elenco non vengono restituiti nella risposta. La directory generata, GENERATED_DIR per le traduzioni SQL generali, è sql/.
  • TOKEN: il token per l'autenticazione. Per generare un token, utilizza il comando gcloud auth print-access-token o OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: il progetto per elaborare la traduzione.
  • LOCATION: la posizione in cui viene elaborato il job.

Il comando precedente restituisce una risposta che include un ID flusso di lavoro scritto nel formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Al termine del job, puoi visualizzare i risultati eseguendo una query sul job e esaminando il campo translation_literals in linea nella risposta al termine del flussi di lavoro.

Esempio di traduzione interattiva

Per tradurre la stringa SQL di Hive select 1 in modo interattivo, puoi utilizzare la seguente query:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

Puoi utilizzare qualsiasi relative_path per il tuo letterale, ma il letterale tradotto verrà visualizzato nei risultati solo se includi sql/$relative_path in target_return_literals. Puoi anche includere più letterali in una singola query, in questo caso ogni percorso relativo deve essere incluso in target_return_literals.

Questa chiamata restituirà un messaggio contenente l'ID del flusso di lavoro creato nel "name" campo:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Per ottenere lo stato aggiornato del flusso di lavoro, esegui una query GET. Il job è completato quando "state" diventa COMPLETED. Se l'attività va a buon fine, troverai il codice SQL tradotto nel messaggio di risposta:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

Esplorare l'output della traduzione

Dopo aver eseguito il job di traduzione, recupera i risultati specificando l'ID flusso di lavoro del job di traduzione utilizzando il seguente comando:

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Sostituisci quanto segue:

  • TOKEN: il token per l'autenticazione. Per generare un token, utilizza il comando gcloud auth print-access-token o OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: il progetto per elaborare la traduzione.
  • LOCATION: la posizione in cui viene elaborato il job.
  • WORKFLOW_ID: l'ID generato quando crei un flusso di lavoro di traduzione.

La risposta contiene lo stato del flusso di lavoro di migrazione e tutti i file completati in target_return_literals.

La risposta conterrà lo stato del flusso di lavoro di migrazione e eventuali file completati in target_return_literals. Puoi eseguire il polling di questo endpoint per controllare lo stato del flusso di lavoro.