Questa pagina è stata tradotta dall'API Cloud Translation.

Tradurre query SQL con l'API Translation

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

Prima di iniziare

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

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

Autorizzazioni obbligatorie

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

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare job di traduzione utilizzando l'API Translation. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

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 tuo progetto Google Cloud CLI è stato creato prima del 15 febbraio 2022, attiva l'API BigQuery Migration nel seguente modo:

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

Vai all'API BigQuery Migration
Fai clic su Attiva.

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

Tipi di attività supportati

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

SQL di Amazon Redshift - Redshift2BigQuery_Translation
Apache HiveQL e CLI Beeline - 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
SQL Presto o Trino - 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 delle funzioni SQL non supportate con le UDF 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:

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.
Isolamento delle dipendenze: il deployment delle UDF nel tuo progetto isola l'ambiente di produzione dalle modifiche esterne.
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.
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à

L'API Translation è 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 CO₂
	Berlino	`europe-west10`	Bassi livelli di CO₂
	Multiregione UE	`eu`
	Finlandia	`europe-north1`	Bassi livelli di CO₂
	Francoforte	`europe-west3`	Bassi livelli di CO₂
	Londra	`europe-west2`	Bassi livelli di CO₂
	Madrid	`europe-southwest1`	Bassi livelli di CO₂
	Milano	`europe-west8`
	Paesi Bassi	`europe-west4`	Bassi livelli di CO₂
	Parigi	`europe-west9`	Bassi livelli di CO₂
	Stoccolma	`europe-north2`	Bassi livelli di CO₂
	Torino	`europe-west12`
	Varsavia	`europe-central2`
	Zurigo	`europe-west6`	Bassi livelli di CO₂
Americhe
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	Bassi livelli di CO₂
	Iowa	`us-central1`	Bassi livelli di CO₂
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	Messico	`northamerica-south1`
	Virginia del Nord	`us-east4`
	Oregon	`us-west1`	Bassi livelli di CO₂
	Québec	`northamerica-northeast1`	Bassi livelli di CO₂
	San Paolo	`southamerica-east1`	Bassi livelli di CO₂
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	Bassi livelli di CO₂
	Carolina del Sud	`us-east1`
	Toronto	`northamerica-northeast2`	Bassi livelli di CO₂
	Stati Uniti (multiregionale)	`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 inviare una query per ottenere i risultati.

Crea una traduzione batch

Il seguente comando curl crea un job di traduzione batch in cui i file di input e di output sono 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 di 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 (impostazione predefinita): i file di query SQL tradotti.
- suggestion: suggerimenti creati con l'AI.
L'output viene archiviato in una sottocartella della directory di output. Il nome della sottocartella si basa sul 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 in cui 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 Storage gs://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 workflow creato nel campo "name":

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

Per ottenere lo stato aggiornato del workflow, esegui una query GET. Il job invia gli output a Cloud Storage man mano che procede. Lo stato del job state diventa COMPLETED dopo la generazione di tutti i target_types richiesti. Se l'attività viene completata correttamente, puoi trovare la query SQL tradotta in gs://my_data_bucket/teradata/output.

Esempio di traduzione batch con suggerimenti dell'AI

L'esempio seguente traduce gli script SQL di Teradata che si trovano nella directory Cloud Storage gs://my_data_bucket/teradata/input/ e archivia i risultati nella directory Cloud Storage gs://my_data_bucket/teradata/output/ con un suggerimento aggiuntivo 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 si trovano nella directory gs://my_data_bucket/teradata/output/suggestion di Cloud Storage.

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

Il seguente comando curl crea un job di traduzione con input e output letterali stringa. 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. Questi devono essere nel formato URI di destinazione (ad esempio, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Tutto ciò che non è presente in questo elenco non viene restituito 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 in cui elaborare la traduzione.
LOCATION: la posizione in cui viene elaborato il lavoro.

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 interrogando il job ed esaminando il campo translation_literals incorporato nella risposta al termine del flusso di lavoro.

Esempio di traduzione interattiva

Per tradurre in modo interattivo la stringa SQL di Hive select 1, 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 valore letterale, ma il valore letterale tradotto verrà visualizzato nei risultati solo se includi sql/$relative_path nel tuo target_return_literals. Puoi anche includere più valori letterali in una singola query, nel qual caso ciascuno dei relativi percorsi deve essere incluso in target_return_literals.

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

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

Per ottenere lo stato aggiornato del workflow, esegui una query GET. Il job viene completato quando "state" diventa COMPLETED. Se l'attività ha esito positivo, troverai l'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"
}

Esplora 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 in cui elaborare la traduzione.
LOCATION: la posizione in cui viene elaborato il lavoro.
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 tutti i file completati in target_return_literals. Puoi eseguire il polling di questo endpoint per controllare lo stato del flusso di lavoro.