SQL-Abfragen mit der Translation API übersetzen

In diesem Dokument wird beschrieben, wie Sie mit der BigQuery Migration API in BigQuery Skripts, die in anderen SQL-Dialekten geschrieben sind, in GoogleSQL-Abfragen übersetzen.

Eine Liste der von diesem SQL-Übersetzer unterstützten SQL-Dialekte und eine Liste der unterstützten Verarbeitungsstandorte finden Sie unter Unterstützte SQL-Dialekte und Standorte.

Hinweis

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

Übersetzungsmodus auswählen

Die BigQuery Migration API unterstützt zwei Übersetzungsmodi. In beiden Modi wird dieselbe API-Methode verwendet und die Jobs werden asynchron ausgeführt. Die Modi unterscheiden sich darin, wie Sie die SQL-Quelle bereitstellen und wie Sie die übersetzte SQL-Anweisung erhalten:

  • Batchübersetzung: Die API liest Quelldateien aus Cloud Storage und schreibt die übersetzten Dateien und Berichte in Cloud Storage. Verwenden Sie die Batchübersetzung, um viele Dateien gleichzeitig zu übersetzen, z. B. wenn Sie eine gesamte Codebasis migrieren.
  • Interaktive Übersetzung: Sie übergeben Ihre SQL-Anweisungen als Stringliterale im Anfragetext und lesen die übersetzten SQL-Anweisungen aus der Workflowantwort. Sie müssen Ihre SQL- oder Übersetzungsausgabe nicht in Cloud Storage speichern. Mit der interaktiven Übersetzung können Sie einzelne Abfragen bei Bedarf übersetzen, z. B. Abfragen aus einer Anwendung oder einem Entwicklertool.

Übersetzungen aktivieren

Aktivieren Sie die erforderliche BigQuery Migration API. Weitere Informationen finden Sie unter SQL-Übersetzungen aktivieren.

Erforderliche Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für die Ressource parent zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen von Übersetzungsjobs mit dem interaktiven Übersetzer, der Translation API oder dem Batch-SQL-Übersetzer benötigen:

  • Migrationsjobs ansehen und überwachen: MigrationWorkflow-Betrachter (roles/bigquerymigration.viewer)
  • Migrationsjobs senden: MigrationWorkflow-Bearbeiter (roles/bigquerymigration.editor)
  • Auf die Cloud Storage-Buckets für Eingabe und Dateien zugreifen: Storage-Objekt-Administrator (roles/storage.objectAdmin) für den Cloud Storage-Quell- und -Ziel-Bucket.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Erstellen von Übersetzungsjobs mit dem interaktiven Übersetzer, der Translation API oder dem Batch-SQL-Übersetzer erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Übersetzungsjobs mit dem interaktiven Übersetzer, der Translation API oder dem Batch-SQL-Übersetzer zu erstellen:

  • 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

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

Eingabedateien nach Cloud Storage hochladen

Für Batchübersetzungsjobs müssen Sie die Quelldateien mit den Abfragen und Skripts, die Sie übersetzen möchten, in Cloud Storage hochladen. 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.

Nicht unterstützte SQL-Funktionen

Wenn Ihre Quellabfragen auf SQL-Funktionen verweisen, die keine direkten Entsprechungen in GoogleSQL haben, können Sie benutzerdefinierte Hilfsfunktionen (UDFs) verwenden. Weitere Informationen finden Sie unter Nicht unterstützte SQL-Funktionen mit Hilfs-UDFs verarbeiten.

Übersetzungsjob senden

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

Nachdem Sie den Job gesendet haben, können Sie den Jobstatus abfragen.

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 Quellverzeichnisse 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/v2/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 nicht angegeben, wird SQL generiert.

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

    Die Ausgabe wird in einem Unterordner im Ausgabeverzeichnis gespeichert. Der Name des Unterordners basiert auf dem Wert in TARGET_TYPES.

  • 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: der Standort, 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. Der Job sendet während der Ausführung Ausgaben an Cloud Storage. Der Job state ändert sich in COMPLETED, nachdem 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 im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/output/ mit einem zusätzlichen KI-Vorschlag 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",
       }
    }
  }
}

Nachdem die Aufgabe erfolgreich ausgeführt wurde, finden Sie die KI-Vorschläge im Cloud Storage-Verzeichnis gs://my_data_bucket/teradata/output/suggestion.

Interaktive Übersetzung erstellen

Mit dem folgenden curl-Befehl wird ein interaktiver Übersetzungsjob mit Ein- und Ausgaben von Stringliteralen erstellt. 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\": {
        \"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/v2/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: der Standort, 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.

Nachdem der Workflow erstellt wurde, können Sie die Ergebnisse aufrufen, indem Sie den Jobstatus prüfen.

Beispiel für eine interaktive Übersetzung

Um den Apache 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, prüfen Sie den Jobstatus. 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"
}

Jobstatus prüfen

Übersetzungsjobs werden asynchron ausgeführt. Nachdem Sie einen Workflow gesendet haben, rufen Sie seinen Status ab, indem Sie eine GET-Anfrage mit der Workflow-ID senden:

curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" \
  -X GET https://bigquerymigration.googleapis.com/v2/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 der Übersetzungsjob ausgeführt wird.
  • LOCATION: der Standort, an dem der Job verarbeitet wird.
  • WORKFLOW_ID: die Workflow-ID, die beim Erstellen des Übersetzungsworkflows zurückgegeben wurde.

Workflowstatus

Die Antwort enthält ein Feld state, das den aktuellen Status des Workflows angibt:

  • STATE_UNSPECIFIED: Der Workflowstatus ist nicht angegeben.
  • RUNNING: Der Workflow wird aktiv ausgeführt. Fragen Sie den Endpunkt regelmäßig ab, bis sich der Status ändert.
  • PAUSED: Der Workflow ist pausiert.
  • COMPLETED: Der Workflow wurde erfolgreich abgeschlossen. Sie können die Ergebnisse jetzt abrufen.
  • FAILED: Im Workflow sind Fehler aufgetreten. Prüfen Sie die Felder taskResult und reportLogMessages in der Antwort auf Fehlerdetails.

Wenn der Workflow state den Status COMPLETED oder FAILED erreicht, können Sie das Abfragen beenden.

Ergebnisse abrufen

Wie Sie Ergebnisse abrufen, hängt davon ab, ob Sie eine Batchübersetzung oder eine interaktive Übersetzung gesendet haben:

  • Batchübersetzungen: Die übersetzten Dateien, Zusammenfassungsberichte und alle KI-Vorschläge werden in das Cloud Storage-Zielverzeichnis geschrieben, das Sie in target_base_uri angegeben haben. Sie können diese Dateien direkt aus Cloud Storage mit gcloud CLI-Speicherbefehlen, den Cloud Storage-Clientbibliotheken oder der REST API lesen:

    gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

    Ersetzen Sie Folgendes:

    • TARGET_URI: Ihr Ziel-Basis-URI, z. B. gs://my_data_bucket/teradata/output/.
    • LOCAL_DIRECTORY: das lokale Verzeichnis, in dem die Dateien gespeichert werden.

    Weitere Informationen zu den im Ziel-Bucket generierten Dateien finden Sie unter Übersetzungsausgabe ansehen.

  • Interaktive Übersetzungen: Bei Jobs, die mit Stringliteraleingaben und target_return_literals konfiguriert sind, wird die übersetzte Abfrage direkt in der Workflowantwort im Feld translatedLiterals zurückgegeben:

    "taskResult": {
  "translationTaskResult": {
    "translatedLiterals": [
      {
        "relativePath": "sql/input_file",
        "literalString": "SELECT 1;\n"
      }
    ]
  }
}

    Extrahieren Sie das Feld literalString für jeden Eintrag in translatedLiterals, um die übersetzte Abfrage zu erhalten.