Diese Seite wurde von der Cloud Translation API übersetzt.

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:

Prüfen, ob Sie die erforderlichen Berechtigungen haben
Aktivieren Sie die BigQuery Migration API.
Erfassen Sie die Quelldateien mit den SQL-Skripts und Abfragen, die übersetzt werden sollen.
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 Ü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:

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

Zu „BigQuery Migration API“
Klicken Sie auf Aktivieren.

Eingabedateien nach Cloud Storage hochladen

Wenn Sie die Google 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 finden 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

Nicht unterstützte SQL-Funktionen mit Hilfs-UDFs verarbeiten

Bei der Übersetzung von SQL aus einem Quelldialekt in BigQuery haben einige Funktionen möglicherweise keine direkte Entsprechung. Um dieses Problem zu beheben, stellen der BigQuery Migration Service und die BigQuery-Community benutzerdefinierte Hilfsfunktionen bereit, die das Verhalten dieser nicht unterstützten Funktionen des Quelldialekts nachahmen.

Diese UDFs finden Sie häufig im öffentlichen bqutil-Dataset. So können sie in übersetzen Abfragen anfangs im Format bqutil.<dataset>.<function>() referenziert werden. Beispiel: bqutil.fn.cw_count()

Wichtige Hinweise für Produktionsumgebungen:

bqutil bietet zwar einen praktischen Zugriff auf diese Hilfs-UDFs für die anfängliche Übersetzung und Tests, die direkte Nutzung von bqutil für Produktionsarbeitslasten wird jedoch aus mehreren Gründen nicht empfohlen:

Versionskontrolle: Das Projekt bqutil beherbergt die neueste Version dieser UDFs. Das bedeutet, dass sich ihre Definitionen im Laufe der Zeit ändern können. Wenn Sie sich direkt auf bqutil verlassen, kann es zu unerwartetem Verhalten oder fehlerhaften Änderungen in Ihren Produktionsabfragen kommen, wenn die Logik einer UDF aktualisiert wird.
Abhängigkeitsisolation: Wenn Sie UDFs in Ihrem eigenen Projekt bereitstellen, wird Ihre Produktionsumgebung von externen Änderungen isoliert.
Anpassung: Möglicherweise müssen Sie diese UDFs ändern oder optimieren, damit sie besser zu Ihrer spezifischen Geschäftslogik oder Ihren Leistungsanforderungen passen. Das ist nur möglich, wenn sie sich in Ihrem eigenen Projekt befinden.
Sicherheit und Governance: Die Sicherheitsrichtlinien Ihrer Organisation können den direkten Zugriff auf öffentliche Datasets wie bqutil für die Verarbeitung von Produktionsdaten einschränken. Das Kopieren von UDFs in Ihre kontrollierte Umgebung entspricht diesen Richtlinien.

Hilfs-UDFs in Ihrem Projekt bereitstellen:

Für eine zuverlässige und stabile Produktionsnutzung sollten Sie diese Hilfs-UDFs in Ihrem eigenen Projekt und Dataset bereitstellen. So haben Sie die vollständige Kontrolle über Version, Anpassung und Zugriff. Eine ausführliche Anleitung zum Bereitstellen dieser UDFs finden Sie im GitHub-Leitfaden zur Bereitstellung von UDFs. Dieser Leitfaden enthält die erforderlichen Scripts und Schritte zum Kopieren der UDFs in Ihre Umgebung.

Standorte

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

	Beschreibung der Region	Name der Region	Details
Asiatisch-pazifischer Raum
	Delhi	`asia-south2`
	Hongkong	`asia-east2`
	Jakarta	`asia-southeast2`
	Melbourne	`australia-southeast2`
	Mumbai	`asia-south1`
	Osaka	`asia-northeast2`
	Seoul	`asia-northeast3`
	Singapur	`asia-southeast1`
	Sydney	`australia-southeast1`
	Taiwan	`asia-east1`
	Tokio	`asia-northeast1`
Europa
	Belgien	`europe-west1`	Niedriger CO₂-Wert
	Berlin	`europe-west10`	Niedriger CO₂-Wert
	EU (mehrere Regionen)	`eu`
	Finnland	`europe-north1`	Niedriger CO₂-Wert
	Frankfurt	`europe-west3`	Niedriger CO₂-Wert
	London	`europe-west2`	Niedriger CO₂-Wert
	Madrid	`europe-southwest1`	Niedriger CO₂-Wert
	Mailand	`europe-west8`
	Niederlande	`europe-west4`	Niedriger CO₂-Wert
	Paris	`europe-west9`	Niedriger CO₂-Wert
	Stockholm	`europe-north2`	Niedriger CO₂-Wert
	Turin	`europe-west12`
	Warschau	`europe-central2`
	Zürich	`europe-west6`	Niedriger CO₂-Wert
Amerika
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	Niedriger CO₂-Wert
	Iowa	`us-central1`	Niedriger CO₂-Wert
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	Mexiko	`northamerica-south1`
	Northern Virginia	`us-east4`
	Oregon	`us-west1`	Niedriger CO₂-Wert
	Québec	`northamerica-northeast1`	Niedriger CO₂-Wert
	São Paulo	`southamerica-east1`	Niedriger CO₂-Wert
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	Niedriger CO₂-Wert
	South Carolina	`us-east1`
	Toronto	`northamerica-northeast2`	Niedriger CO₂-Wert
	USA (mehrere Regionen)	`us`
Afrika
	Johannesburg	`africa-south1`
MiddleEast
	Dammam	`me-central2`
	Doha	`me-central1`
	Israel	`me-west1`

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

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

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

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

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.