Traduci le query SQL con l'API Translation

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

Per un elenco dei dialetti SQL supportati da questo traduttore SQL e un elenco delle località di elaborazione supportate, consulta Dialetti SQL supportati e località.

Prima di iniziare

Prima di inviare un job di traduzione, segui questi passaggi.

Attiva traduzioni

Abilita l'API BigQuery Migration richiesta. Per ulteriori informazioni, consulta Abilitare le traduzioni SQL.

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per creare job di traduzione con il traduttore interattivo, l'API Translation o il traduttore SQL batch, chiedi all'amministratore di concederti i seguenti ruoli IAM sulla risorsa parent:

  • Visualizzazione e monitoraggio dei job di migrazione: MigrationWorkflow Viewer (roles/bigquerymigration.viewer)
  • Invio di job di migrazione: MigrationWorkflow Editor (roles/bigquerymigration.editor)
  • Accesso ai bucket Cloud Storage per input e file: Storage Object Admin (roles/storage.objectAdmin) sul bucket Cloud Storage di origine e di destinazione.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare job di traduzione con il traduttore interattivo, l'API Translation o il traduttore SQL batch. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare job di traduzione con il traduttore interattivo, l'API Translation o il traduttore SQL batch sono necessarie le seguenti autorizzazioni:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get
  • bigquerymigration.subtasks.list
  • storage.objects.get
  • storage.objects.list
  • storage.objects.create

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

Carica i file di input in 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 che vuoi tradurre in Cloud Storage. Puoi anche caricare eventuali 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 in Cloud Storage, consulta Creare bucket e Caricare oggetti da un file system.

Gestisci le funzioni SQL non supportate con le UDF di assistenza

Quando traduci 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) di assistenza che replicano il comportamento di queste funzioni del dialetto di origine non supportate.

Queste UDF si trovano spesso nel set di dati pubblico bqutil, il che consente 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 pratico a queste UDF di assistenza per la traduzione e il test iniziali, l'utilizzo diretto di bqutil per i workload di produzione non è consigliato per diversi motivi:

  1. Controllo delle versioni: 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.
  2. Isolamento delle dipendenze: il deployment delle UDF 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 di business o ai requisiti di prestazioni specifici. Questo è possibile solo se si trovano all'interno del tuo progetto.
  4. Sicurezza e governance: le norme di sicurezza della tua organizzazione potrebbero limitare l'accesso diretto ai set di dati pubblici come bqutil per l'elaborazione dei dati di produzione. La copia delle UDF nel tuo ambiente controllato è conforme a queste norme.

Esegui il deployment delle UDF di assistenza nel tuo progetto

Per un utilizzo di produzione affidabile e stabile, devi eseguire il deployment di queste UDF di assistenza nel tuo progetto e set di dati. In questo modo avrai il controllo completo 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.

Invia un job di traduzione

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

Una volta inviato il job, puoi eseguire 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 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 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 generati dall'AI.

    L'output viene archiviato in una sottocartella nella 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 località in cui viene elaborato il job.

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

Esempio di traduzione batch

Per tradurre gli script SQL 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 workflow 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 workflow, esegui una query GET. Il job invia gli output a Cloud Storage man mano che procede. Lo state del job cambia in COMPLETED dopo che tutti i target_types richiesti sono stati generati. Se l'attività ha esito positivo, puoi trovare la query SQL tradotta in gs://my_data_bucket/teradata/output.

Esempio di traduzione batch con suggerimenti dell'AI

Il seguente esempio traduce gli script SQL 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 sono disponibili nella directory Cloud Storage gs://my_data_bucket/teradata/output/suggestion.

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 letterali. 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: le destinazioni previste che l'utente vuole che vengano restituite 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 per elaborare la traduzione.
  • LOCATION: la località in cui viene elaborato il job.

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

Al termine del job, puoi visualizzare i risultati eseguendo una query sul job ed esaminando il campo translation_literals incorporato nella risposta al termine del workflow.

Esempio di traduzione interattiva

Per tradurre in modo interattivo la stringa SQL 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 che preferisci per il tuo valore letterale, ma il valore letterale tradotto verrà visualizzato nei risultati solo se includi sql/$relative_path in target_return_literals. Puoi anche includere più valori letterali in una singola query, nel qual caso i relativi percorsi relativi devono essere inclusi in target_return_literals.

Questa chiamata restituirà un messaggio contenente l'ID workflow 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 workflow, esegui una query GET. Il job è completato quando "state" cambia in 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 workflow 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 lo OAuth 2.0 Playground (utilizza l'ambito https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: il progetto per elaborare la traduzione.
  • LOCATION: la località in cui viene elaborato il job.
  • WORKFLOW_ID: l'ID generato quando crei un workflow di traduzione.

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

La risposta conterrà lo stato del workflow di migrazione e tutti i file completati in target_return_literals. Puoi eseguire il polling di questo endpoint per controllare lo stato del workflow.