SQL-Abfragen mit der Translation API übersetzen

In diesem Dokument wird beschrieben, wie Sie mit der Translation API in BigQuery Skripts, die in anderen SQL-Dialekten geschrieben sind, in GoogleSQL-Abfragen übersetzen. Mit der Übersetzungs-API lässt sich die Migration von Arbeitslasten zu BigQuery vereinfachen.

Hinweise

Führen Sie die folgenden Schritte aus, bevor Sie einen Übersetzungsjob senden:

1. Prüfen, ob Sie die erforderlichen Berechtigungen haben
2. Aktivieren Sie die BigQuery Migration API.
3. Erfassen Sie die Quelldateien mit den SQL-Skripts und Abfragen, die übersetzt werden sollen.
4. Quelldateien in Cloud Storage hochladen

Erforderliche Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle MigrationWorkflow-Bearbeiter (roles/bigquerymigration.editor) für die Ressource parent zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Übersetzungsjobs mit der konsolidierten Übersetzungs-API benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen von Übersetzungsjobs mithilfe der konsolidierten Übersetzungs-API erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Übersetzungsjobs mit der konsolidierten Übersetzungs-API zu erstellen:

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

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

BigQuery Migration API aktivieren

Wenn Ihr Google Cloud-Befehlszeilenprojekt vor dem 15. Februar 2022 erstellt wurde, aktivieren Sie die BigQuery Migration API so:

1. Rufen Sie in der Google Cloud Console die Seite BigQuery Migration API auf.

   Zu „BigQuery Migration API“

2. Klicken Sie auf Aktivieren.

Hinweis: Bei Projekten, die nach dem 15. Februar 2022 erstellt wurden, ist diese API automatisch aktiviert.

Eingabedateien nach Cloud Storage hochladen

Wenn Sie die Cloud Console oder die BigQuery Migration API verwenden möchten, um einen Übersetzungsjob auszuführen, müssen Sie die Quelldateien mit den Abfragen und Skripts hochladen, die in Cloud Storage übersetzt werden sollen. Sie können auch beliebige Metadatendateien oder YAML-Konfigurationsdateien in denselben Cloud Storage-Bucket hochladen, der die Quelldateien enthält. Weitere Informationen zum Erstellen von Buckets und zum Hochladen von Dateien in Cloud Storage erhalten Sie unter Buckets erstellen und Objekte aus einem Dateisystem hochladen.

Unterstützte Aufgabentypen

Die Translation API kann die folgenden SQL-Dialekte in GoogleSQL übersetzen:

• Amazon Redshift SQL - Redshift2BigQuery_Translation
• Apache HiveQL und Beeline-Befehlszeile - 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 und NZPLSQL - Netezza2BigQuery_Translation
• MySQL SQL - MySQL2BigQuery_Translation
• Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
• PostgreSQL SQL - Postgresql2BigQuery_Translation
• Presto oder Trino SQL – Presto2BigQuery_Translation
• Snowflake SQL - Snowflake2BigQuery_Translation
• SQLite - SQLite2BigQuery_Translation
• SQL Server T-SQL - SQLServer2BigQuery_Translation
• Teradata und Teradata Vantage - Teradata2BigQuery_Translation
• Vertica SQL - Vertica2BigQuery_Translation

Standorte

Die Translation API ist an den folgenden Verarbeitungsorten verfügbar:

	Beschreibung der Region	Name der Region	Details
Asiatisch-pazifischer Raum
	Tokio	asia-northeast1
	Mumbai	asia-south1
	Singapur	asia-southeast1
	Sydney	australia-southeast1
Europa
	EU (mehrere Regionen)	eu
	Warschau	europe-central2
	Finnland	europe-north1	Niedriger CO2-Wert
	Madrid	europe-southwest1	Niedriger CO2-Wert
	Belgien	europe-west1	Niedriger CO2-Wert
	London	europe-west2	Niedriger CO2-Wert
	Frankfurt	europe-west3	Niedriger CO2-Wert
	Niederlande	europe-west4	Niedriger CO2-Wert
	Zürich	europe-west6	Niedriger CO2-Wert
	Paris	europe-west9	Niedriger CO2-Wert
	Turin	europe-west12
Amerika
	Québec	northamerica-northeast1	Niedriger CO2-Wert
	São Paulo	southamerica-east1	Niedriger CO2-Wert
	USA (mehrere Regionen)	us
	Iowa	us-central1	Niedriger CO2-Wert
	South Carolina	us-east1
	Northern Virginia	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	Niedriger CO2-Wert
	Oregon	us-west1	Niedriger CO2-Wert
	Los Angeles	us-west2
	Salt Lake City	us-west3

Übersetzungsjob senden

Verwenden Sie zum Senden eines Übersetzungsjobs mit der Translation API die Methode projects.locations.workflows.create und geben Sie eine Instanz der Ressource MigrationWorkflow mit einer unterstützten Aufgabentyp.

Sobald der Job gesendet wurde, können Sie eine Abfrage stellen, um Ergebnisse zu erhalten.

Batchübersetzung erstellen

Mit dem folgenden curl-Befehl wird ein Batchübersetzungsjob erstellt, in dem die Ein- und Ausgabedateien in Cloud Storage gespeichert werden. Das Feld source_target_mapping enthält eine Liste, die die literal-Quelleinträge einem optionalen relativen Pfad für die Zielausgabe zuordnet.

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

Ersetzen Sie Folgendes:

• TYPE: Der Aufgabentyp der Übersetzung, der den Quell- und Zieldialekt bestimmt.
• TARGET_BASE: Der Basis-URI für alle Übersetzungsausgaben.
• BASE ist der Basis-URI für alle Dateien, die als Quellen für die Übersetzung gelesen werden.

• TARGET_TYPES (optional): die generierten Ausgabetypen. Wenn Sie keine Angabe machen, wird SQL generiert.

  • sql (Standardeinstellung): Die übersetzten SQL-Abfragedateien.
  • suggestion: KI-generierte Vorschläge.

  Die Ausgabe wird in einem Unterordner im Ausgabeverzeichnis gespeichert. Der Unterordner wird anhand des Werts in TARGET_TYPES benannt.

• TOKEN: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehl gcloud auth print-access-token oder den OAuth 2.0 Playground (verwenden Sie den Bereich https://www.googleapis.com/auth/cloud-platform).

• PROJECT_ID: das Projekt, in dem die Übersetzung verarbeitet werden soll.

• LOCATION: den Speicherort, an dem der Job verarbeitet wird.

Der vorherige Befehl gibt eine Antwort zurück, die eine Workflow-ID im Format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID enthält.

Beispiel für eine Batchübersetzung

Wenn Sie die Teradata-SQL-Scripts im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/input/ übersetzen und die Ergebnisse im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/output/ speichern möchten, können Sie die folgende Abfrage verwenden:

{
  "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/"
             }
          },
       }
    }
  }
}

Hinweis: Der String "task_name" in diesem Beispiel ist eine Kennung für die Übersetzungsaufgabe und kann auf einen beliebigen Wert festgelegt werden.

Dieser Aufruf gibt eine Nachricht mit der erstellten Workflow-ID im Feld "name" zurück:

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

Wenn Sie den aktualisierten Status des Workflows abrufen möchten, führen Sie eine GET-Abfrage aus. Im Laufe des Jobs werden die Ausgaben an Cloud Storage gesendet. Der Job state ändert sich in COMPLETED, sobald alle angeforderten target_types generiert wurden. Wenn die Aufgabe erfolgreich war, finden Sie die übersetzte SQL-Abfrage unter gs://my_data_bucket/teradata/output.

Beispiel für eine Batchübersetzung mit KI-Vorschlägen

Vorschau

Dieses Produkt oder diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und -Funktionen sind unverändert verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

Hinweis: Die Übersetzungs-API kann Gemini über die BigQuery-Vertex AI-Integration aufrufen, um Vorschläge für Ihre übersetzte SQL-Abfrage basierend auf Ihrer YAML-Datei für die KI-Konfiguration zu generieren.

Im folgenden Beispiel werden die Teradata-SQL-Scripts im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/input/ übersetzt und die Ergebnisse mit zusätzlichen KI-Vorschlägen im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/output/ gespeichert:

{
  "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",
       }
    }
  }
}

Hinweis :Damit KI-Vorschläge generiert werden können, muss das Cloud Storage-Quellverzeichnis mindestens eine Konfigurations-YAML-Datei mit dem Suffix .ai_config.yaml enthalten. Informationen zum Erstellen der YAML-Konfigurationsdatei für KI-Vorschläge finden Sie unter Gemini-basierte YAML-Konfigurationsdatei erstellen.

Nach erfolgreicher Ausführung der Aufgabe finden Sie die KI-Vorschläge im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/output/suggestion.

Interaktiven Übersetzungsjob mit Stringliteraleingaben und -ausgaben erstellen

Mit dem folgenden curl-Befehl wird ein Übersetzungsjob mit Ein- und Ausgaben von Stringliteralen erstellt. Das Feld source_target_mapping enthält eine Liste, die die Quellverzeichnisse einem optionalen relativen Pfad für die Zielausgabe zuordnet.

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

Ersetzen Sie Folgendes:

• TYPE: Der Aufgabentyp der Übersetzung, der den Quell- und Zieldialekt bestimmt.
• PATH: die Kennung des Literaleintrags, ähnlich einem Dateinamen oder Pfad.
• STRING: String der Literaleingabedaten (z. B. SQL), die übersetzt werden sollen.
• TARGETS: die erwarteten Ziele, die der Nutzer direkt in der Antwort im Format literal zurückgeben möchte. Diese sollten im Ziel-URI-Format vorliegen (z. B. GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Alles, was nicht in dieser Liste enthalten ist, wird in der Antwort nicht zurückgegeben. Das generierte Verzeichnis GENERATED_DIR für allgemeine SQL-Übersetzungen ist sql/.
• TOKEN: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehl gcloud auth print-access-token oder den OAuth 2.0 Playground (verwenden Sie den Bereich https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: das Projekt, in dem die Übersetzung verarbeitet werden soll.
• LOCATION: den Speicherort, an dem der Job verarbeitet wird.

Der vorherige Befehl gibt eine Antwort zurück, die eine Workflow-ID im Format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID enthält.

Wenn der Job abgeschlossen ist, können Sie die Ergebnisse abrufen, indem Sie den Job abfragen und das Inline-Feld translation_literals in der Antwort prüfen, nachdem der Workflow abgeschlossen ist.

Beispiel für eine interaktive Übersetzung

Um den Hive-SQL-String select 1 interaktiv zu übersetzen, können Sie die folgende Abfrage verwenden:

"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",
    }
  }
}

Hinweis: Der String "task_name" in diesem Beispiel ist eine Kennung für die Übersetzungsaufgabe und kann auf einen beliebigen Wert festgelegt werden.

Sie können für das Literal ein beliebiges relative_path verwenden. Das übersetzte Literal wird jedoch nur in den Ergebnissen angezeigt, wenn Sie sql/$relative_path in target_return_literals einschließen. Sie können auch mehrere Literale in einer einzigen Abfrage angeben. In diesem Fall müssen alle relativen Pfade in target_return_literals enthalten sein.

Dieser Aufruf gibt eine Nachricht mit der erstellten Workflow-ID im Feld "name" zurück:

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

Wenn Sie den aktualisierten Status des Workflows abrufen möchten, führen Sie eine GET-Abfrage aus. Der Job ist abgeschlossen, wenn "state" in COMPLETED wechselt. Wenn die Aufgabe erfolgreich war, finden Sie die übersetzte SQL-Anweisung in der Antwortnachricht:

{
  "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"
}

Übersetzungsausgabe ansehen

Rufen Sie nach dem Ausführen des Übersetzungsjobs die Ergebnisse ab. Geben Sie dazu die Workflow-ID des Übersetzungsjobs mit dem folgenden Befehl an:

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

Ersetzen Sie Folgendes:

• TOKEN: das Token zur Authentifizierung. Verwenden Sie zum Generieren eines Tokens den Befehl gcloud auth print-access-token oder den OAuth 2.0 Playground (verwenden Sie den Bereich https://www.googleapis.com/auth/cloud-platform).
• PROJECT_ID: das Projekt, in dem die Übersetzung verarbeitet werden soll.
• LOCATION: den Speicherort, an dem der Job verarbeitet wird.
• WORKFLOW_ID: die ID, die beim Erstellen eines Übersetzungsworkflows generiert wird.

Die Antwort enthält den Status des Migrationsworkflows und alle abgeschlossenen Dateien in target_return_literals.

Die Antwort enthält den Status des Migrationsworkflows und alle abgeschlossenen Dateien in target_return_literals. Sie können diesen Endpunkt abfragen, um den Status Ihres Workflows zu prüfen.