Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Code mit dem Batch-SQL-Übersetzer migrieren

Dieses Dokument beschreibt, wie Sie den Batch-SQL-Übersetzer in BigQuery verwenden, um in anderen SQL-Dialekten geschriebene Skripte in GoogleSQL-Abfragen zu übersetzen. Dieses Dokument richtet sich an Nutzer, die mit der Google Cloud -Konsole vertraut sind.

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

Eine Liste der unterstützten Verarbeitungsstandorte finden Sie unter Locations.

Hinweis

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

SQL-Übersetzungen aktivieren

Aktivieren Sie die erforderliche API und rufen Sie die Berechtigungen ab, die für die Verwendung eines BigQuery-SQL-Übersetzers erforderlich sind. 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, damit Sie die nötigen Berechtigungen zum Erstellen von Übersetzungsjobs mit dem interaktiven Übersetzer, der Übersetzungs-API oder dem Batch-SQL-Übersetzer haben:

Migrationsjobs ansehen und überwachen: MigrationWorkflow-Betrachter (roles/bigquerymigration.viewer)
Migrationsjobs einreichen: MigrationWorkflow-Bearbeiter (roles/bigquerymigration.editor)
Auf die Cloud Storage-Buckets für Eingabe- und Ausgabedateien zugreifen: Storage Object Admin (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 Übersetzungs-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 Übersetzungs-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.

Quelldateien erfassen

Quelldateien müssen Textdateien sein, die gültigen SQL-Code für den Quelldialekt enthalten. Quelldateien können auch Kommentare enthalten. Versuchen Sie mithilfe der verfügbaren Methoden, die SQL-Gültigkeit zu prüfen.

Metadatendateien erstellen

Damit der Dienst genauere Übersetzungsergebnisse generieren kann, empfehlen wir die Bereitstellung von Metadatendateien. Dies ist jedoch nicht obligatorisch.

Zum Generieren der Metadateninformationen können Sie das dwh-migration-dumper-Befehlszeilentool verwenden oder Ihre eigenen Metadatendateien bereitstellen. Sobald Metadatendateien vorbereitet sind, können Sie diese zusammen mit den Quelldateien in den Quellordner für die Übersetzung aufnehmen. Der Übersetzer erkennt sie automatisch und nutzt sie zum Übersetzen von Quelldateien. Sie müssen keine zusätzlichen Einstellungen konfigurieren, um dies zu aktivieren.

Informationen zum Generieren von Metadateninformationen mit dem dwh-migration-dumper-Tool finden Sie unter Metadaten für die Übersetzung generieren.

Erfassen Sie zur Bereitstellung Ihrer eigenen Metadaten die DDL-Anweisungen (Data Definition Language) für die SQL-Objekte in Ihrem Quellsystem in separaten Textdateien.

Entscheiden, wie der Übersetzungsjob gesendet werden soll

Zum Senden eines Batchübersetzungsjobs haben Sie drei Möglichkeiten:

Batch-Übersetzungsclient: Konfigurieren Sie einen Job, indem Sie die Einstellungen in einer Konfigurationsdatei ändern und den Job über die Befehlszeile senden. Bei diesem Ansatz müssen Sie die Quelldateien nicht manuell in Cloud Storage hochladen. Der Client verwendet während der Verarbeitung des Übersetzungsjobs weiterhin Cloud Storage zum Speichern von Dateien.

Der Legacy Batch Translation Client ist ein Open-Source-Python-Client, mit dem Sie Quelldateien auf Ihrem lokalen Rechner übersetzen und die übersetzten Dateien in einem lokalen Verzeichnis ausgeben lassen können. Sie konfigurieren den Client für die grundlegende Verwendung, indem Sie einige Einstellungen in der Konfigurationsdatei ändern. Wenn Sie möchten, können Sie den Client auch so konfigurieren, dass komplexere Aufgaben wie die Makroersetzung und die Vor- und Nachbearbeitung von Übersetzungseingaben und -ausgaben erfüllt werden. Weitere Informationen finden Sie in der Readme-Datei des Batchübersetzungsclients.
Google Cloud console: Konfigurieren und übermitteln Sie einen Auftrag über eine Benutzeroberfläche. Bei diesem Ansatz müssen Sie Quelldateien in Cloud Storage hochladen.

Erstellen Sie Konfigurations-YAML-Dateien

Optional können Sie YAML-Konfigurationsdateien erstellen und verwenden, um Ihre Batchübersetzungen anzupassen. Mithilfe dieser Dateien können Sie Ihre Übersetzungsergebnisse auf verschiedene Weise transformieren. Sie können beispielsweise eine YAML-Konfigurationsdatei erstellen, um die Groß-/Kleinschreibung eines SQL-Objekts während der Übersetzung zu ändern.

Wenn Sie die Google Cloud Konsole oder die BigQuery Migration API für einen Batch-Übersetzungsauftrag verwenden möchten, können Sie die Konfigurations-YAML-Datei in den Cloud Storage-Bucket hochladen, der die Quelldateien enthält.

Wenn Sie den Batchübersetzungsclient verwenden möchten, können Sie die YAML-Konfigurationsdatei im Eingabeordner für die lokale Übersetzung platzieren.

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 Konfigurations-YAML-Dateien in denselben Cloud Storage-Bucket und dasselbe Verzeichnis hochladen, in dem sich die Quelldateien befinden. 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.

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

Beim Übersetzen von SQL aus einem Quelldialekt in BigQuery gibt es für einige Funktionen möglicherweise keine direkte Entsprechung. Um dieses Problem zu beheben, bietet der BigQuery-Migrationsdienst (und die BigQuery-Community im Allgemeinen) benutzerdefinierte Hilfsfunktionen (UDFs), die das Verhalten dieser nicht unterstützten Funktionen des Quelldialekts nachbilden.

Diese UDFs befinden sich häufig im öffentlichen Datensatz bqutil, sodass übersetzte Abfragen zunächst mit dem Format bqutil.<dataset>.<function>() auf sie verweisen können. Beispiel: bqutil.fn.cw_count()

Wichtige Hinweise für Produktionsumgebungen:

Während bqutil einen bequemen Zugriff auf diese Hilfs-UDFs für die erste Übersetzung und das Testen bietet, wird die direkte Verwendung von bqutil für Produktionsworkloads aus mehreren Gründen nicht empfohlen:

Versionsverwaltung: Das bqutil-Projekt hostet die aktuelle Version dieser UDFs, was bedeutet, dass sich ihre Definitionen im Laufe der Zeit ändern können. Sich direkt auf bqutil zu verlassen, könnte zu unerwartetem Verhalten oder zu inkompatiblen Änderungen in Ihren Produktionsabfragen führen, 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 benutzerdefinierten Funktionen ändern oder optimieren, damit sie besser zu Ihrer spezifischen Geschäftslogik oder Ihren Leistungsanforderungen passen. Dies ist nur möglich, wenn sie sich innerhalb Ihres eigenen Projekts befinden.
Sicherheit und Governance: Die Sicherheitsrichtlinien Ihrer Organisation schränken möglicherweise den direkten Zugriff auf öffentliche Datasets wie bqutil für die Verarbeitung von Produktionsdaten ein. Das Kopieren von benutzerdefinierten Funktionen in Ihre kontrollierte Umgebung entspricht solchen Richtlinien.

Hilfs-UDFs in Ihrem Projekt bereitstellen:

Für einen zuverlässigen und stabilen Produktionseinsatz sollten Sie diese Hilfs-UDFs in Ihr eigenes Projekt und Ihren eigenen Datensatz einbinden. So haben Sie die vollständige Kontrolle über die Version, Anpassung und den Zugriff. Eine detaillierte Anleitung zum Bereitstellen dieser UDFs finden Sie im Bereitstellungsleitfaden für UDFs auf GitHub. In dieser Anleitung finden Sie die erforderlichen Skripts und Schritte zum Kopieren der UDFs in Ihre Umgebung.

Übersetzungsjob senden

Führen Sie die folgenden Schritte aus, um einen Übersetzungsjob zu starten, seinen Fortschritt anzuzeigen und die Ergebnisse anzuzeigen.

Console

Bei diesen Schritten wird davon ausgegangen, dass Sie bereits Quelldateien in einen Cloud Storage-Bucket hochgeladen haben.

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Klicken Sie im Bereich SQL-Übersetzung auf Übersetzung starten.
Geben Sie unter Übersetzungskonfiguration Folgendes ein:
1. Geben Sie einen Namen für den Übersetzungsjob unter Anzeigename ein. Der Name kann Buchstaben, Ziffern und Unterstriche enthalten.
2. Wählen Sie unter Verarbeitungsort den Ort aus, an dem der Übersetzungsjob ausgeführt werden soll. Wenn Sie sich beispielsweise in Europa befinden und Ihre Daten keine Standortgrenzen überschreiten möchten, wählen Sie die Region eu aus. Der Übersetzungsjob funktioniert am besten, wenn Sie denselben Speicherort wie der Quelldatei-Bucket auswählen.
3. Wählen Sie unter Quelldialekt den SQL-Dialekt aus, den Sie übersetzen möchten.
4. Für Zieldialekt, wähle GoogleSQL.
Klicken Sie auf Weiter.
Für Dateispeicherortdetails geben Sie die Cloud Storage-Pfade an, die für die Übersetzungseingabe und -ausgabe verwendet werden sollen. Sie können die Pfade im Format bucket_name/folder_name/ eingeben oder die Option Durchsuchen verwenden, um zu einem Ordner zu navigieren.
1. Geben Sie unter Speicherort des Ausgabeverzeichnisses einen Pfad zum Cloud Storage-Zielordner für die übersetzten Dateien an. Dies dient als Stammverzeichnis für alle Übersetzungen.
2. Wählen Sie einen oder mehrere Eingabeverzeichnisse aus, die den Pfad zu den zu übersetzenden SQL-Dateien enthalten.
3. Jedem Eingabeverzeichnis kann optional ein Ausgabe-Unterverzeichnisname unterhalb des Stamm-Ausgabeverzeichnisses zugewiesen werden, falls erforderlich.
Klicken Sie auf Weiter.
Wählen Sie alle optionalen Einstellungen aus, die Sie benötigen, um Metadaten und zusätzliche Übersetzungsausgaben anzupassen.
Sie können das Übersetzungsverhalten weiter anpassen, indem Sie Konfigurations-YAML-Dateien erstellen und diese Dateien im Eingabe-Cloud-Storage-Bucket ablegen. Mit diesen Dateien können Sie Objekte umbenennen, Optimierungen aktivieren, Übersetzungen mit Gemini verbessern und vieles mehr. Weitere Informationen zu YAML-Konfigurationsdateien finden Sie unter YAML-Konfigurationsdatei erstellen.
Klicken Sie auf Erstellen, um den Übersetzungsjob zu starten.

Nachdem der Übersetzungsjob erstellt wurde, können Sie den Status in der Liste der Übersetzungsjobs sehen.

Batch-Übersetzungsclient

Installieren Sie den Batchübersetzungsclient und die Google Cloud CLI.
Datei mit gcloud CLI-Anmeldedaten generieren
Öffnen Sie im Installationsverzeichnis des Batchübersetzungsclients mit einem Texteditor Ihrer Wahl die Datei config.yaml und ändern Sie die folgenden Einstellungen:
- project_number: Geben Sie die Projektnummer des Projekts ein, das Sie für den Batchübersetzungsjob verwenden möchten. Sie finden diese Information im Bereich Projektinfo auf der Google Cloud Konsolen-Willkommensseite für das Projekt.
- gcs_bucket: Geben Sie den Namen des Cloud Storage-Bucket ein, den der Batchübersetzungsclient zum Speichern von Dateien während der Verarbeitung des Übersetzungsjobs verwendet.
- input_directory: Geben Sie den absoluten oder relativen Pfad zum Verzeichnis ein, das die Quelldateien und Metadatendateien enthält.
- output_directory: Geben Sie den absoluten oder relativen Pfad zum Zielverzeichnis für die übersetzten Dateien ein.
Speichern Sie die Änderungen und schließen Sie die config.yaml-Datei.
Platzieren Sie die Quell- und Metadatendateien im Eingabeverzeichnis.
Führen Sie den Batchübersetzungsclient mit dem folgenden Befehl aus:
```
bin/dwh-migration-client
```
Erstellen Sie einen Übersetzungsjob.
- Das folgende Beispiel zeigt einen Befehl zum Erstellen eines Übersetzungsjobs. Der Befehl führt den Workflow aus und zeigt die Ausgabe an, wenn der Workflow erfolgreich ist.
```
gcloud bq migration-workflows create --location=us --config-file=CONFIG_FILE_NAME.json
```
- Das folgende Beispiel zeigt einen Befehl zum Erstellen und Ausführen des Workflows mit dem Flag --async. Mit dem Befehl wird der Workflow erstellt und ausgeführt. Anschließend wird sofort ein Link zum Workflow zurückgegeben.
```
gcloud bq migration-workflows create --location=LOCATION  --config-file=CONFIG_FILE_NAME.json --async
```
- Das folgende Beispiel zeigt einen Befehl zum Auflisten Ihrer Übersetzungsjobs:
```
gcloud bq migration-workflows list --location=LOCATION
```
Ersetzen Sie Folgendes:
- LOCATION: Der Speicherort des Google Cloud -Projekts, in dem dieser Übersetzungsjob ausgeführt wird.
- CONFIG_FILE_NAME: der Name der config.yaml-Datei. Nachdem der Übersetzungsjob erstellt wurde, können Sie den Status in der Liste der Übersetzungsjobs in der Google Cloud -Konsole sehen.
Optional. Sobald der Übersetzungsjob abgeschlossen ist, löschen Sie die Dateien, die der Job im angegebenen Cloud Storage-Bucket erstellt hat, um Speicherkosten zu vermeiden.

BigQuery-Befehlszeile

Sie können den Batch-SQL-Übersetzer mit dem Befehlszeilentool bq wie folgt ausführen:

Erstellen Sie eine Konfigurationsdatei für Übersetzungen in YAML oder JSON. In dieser Datei müssen Sie den Pfad zur Quelldatei, das Ausgabeziel sowie die Quell- und Zieldialekte Ihrer Übersetzung definieren.

Das folgende Beispiel zeigt eine YAML-Konfigurationsdatei für eine Übersetzung von Teradata nach BigQuery:

tasks:
translation_task:
  type: Teradata2BigQuery_Translation
  translationDetails:
    sourceTargetMapping:
    - sourceSpec:
        baseUri: gs://bq-translations/input
      targetSpec:
        relativePath: output
    targetBaseUri: gs://bq-translations
    targetTypes:
    - sql
    sourceEnvironment:
      defaultDatabase: default_db
      schemaSearchPath:
      - foo

Das folgende Beispiel zeigt eine JSON-Datei mit der Übersetzungskonfiguration für die Übersetzung von Teradata zu BigQuery:

{
"tasks": {
  "translation_task": {
    "type": "Teradata2BigQuery_Translation",
    "translationDetails": {
      "sourceTargetMapping": [
        {
          "sourceSpec": {
            "literal": {
              "literalString": "sel 1",
              "relativePath": "my_input_1"
            },
            "encoding": "UTF-8"
          }
        },
        {
          "sourceSpec": {
            "literal": {
              "literalString": "sel 2",
              "relativePath": "my_input_2"
            },
            "encoding": "UTF-8"
          }
        }
      ],
      "targetReturnLiterals": [
        "sql/my_input_1",
        "sql/my_input_2"
      ]
    }
  }
}
}

Nachdem die Übersetzungskonfiguration erstellt wurde, führen Sie den folgenden Befehl aus, um den Übersetzungsjob auszuführen.
```
bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE_NAME.json
```
Ersetzen Sie Folgendes:
- LOCATION: Der Speicherort des Google Cloud -Projekts, in dem dieser Übersetzungsjob ausgeführt wird.
- CONFIG_FILE_NAME: der Name der config.yaml-Datei.

Führen Sie den folgenden Befehl aus, um Details zu einem bestimmten Übersetzungsjob aufzurufen:
```
bq show --migration_workflow projects/PROJECT_ID/ locations/us/workflows/WORKFLOW_ID
```
Ersetzen Sie Folgendes:
- PROJECT_ID: die ID des Google Cloud Projekts, in dem dieser Übersetzungsjob ausgeführt wird.
- WORKFLOW_ID: die ID des Übersetzungsauftrags.

Führen Sie den folgenden Befehl aus, um die Ergebnisse eines bestimmten Übersetzungsjobs aufzurufen:

gcloud bq migration-workflows describe projects/PROJECT_ID    /locations/us/workflows/WORKFLOW_ID

Um einen Übersetzungsauftrag aus der Liste zu entfernen, führen Sie folgenden Befehl aus:
```
bq rm --migration_workflow projects/PROJECT_ID/locations/us/workflows/WORKFLOW_ID
```
Führen Sie den folgenden Befehl aus, um alle Ihre Übersetzungsjobs aufzulisten:
```
bq ls --migration_workflow --location=LOCATION
```

Übersetzungsausgabe ansehen

Nachdem Sie den Übersetzungsjob ausgeführt haben, können Sie Informationen zum Job in der Google Cloud Console ansehen. Wenn Sie die Google Cloud console zum Ausführen des Auftrags verwendet haben, können Sie die Auftragsergebnisse im Ziel-Cloud Storage-Bucket sehen, den Sie angegeben haben. Wenn Sie den Batchübersetzungsclient zum Ausführen des Jobs verwendet haben, können Sie die Jobergebnisse im von Ihnen angegebenen Ausgabeverzeichnis anzeigen. Der Batch-SQL-Übersetzer gibt die folgenden Dateien an das angegebene Ziel aus:

Die übersetzten Dateien.
Der Zusammenfassungsbericht für Übersetzungen im CSV-Format.
Die verbrauchte Ausgabenamenzuordnung im JSON-Format.
Die Dateien mit KI-Vorschlägen.

Google Cloud -Konsolenausgabe

So rufen Sie Details zu Übersetzungsjobs auf:

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Suchen Sie in der Liste der Übersetzungsjobs nach dem Job, für den Sie die Übersetzungsdetails aufrufen möchten. Klicken Sie dann auf den Namen des Übersetzungsjobs. Sie sehen eine Sankey-Visualisierung, die die Gesamtqualität des Jobs, die Anzahl der Eingabezeilen mit Code (ohne Leerzeilen und Kommentare) und eine Liste der Probleme veranschaulicht, die während des Übersetzungsprozesses aufgetreten sind. Sie sollten Korrekturen von links nach rechts priorisieren. Probleme in einer frühen Phase können in späteren Phasen zu zusätzlichen Problemen führen.
Bewegen Sie den Mauszeiger über die Fehler- oder Warnbalken und prüfen Sie die Vorschläge, um die nächsten Schritte zur Fehlerbehebung bei der Übersetzung zu ermitteln.
Wählen Sie den Tab Logzusammenfassung aus, um eine Übersicht über die Übersetzungsprobleme aufzurufen, einschließlich Problemkategorien, vorgeschlagene Aktionen und der Häufigkeit des jeweiligen Problems. Sie können die Sankey-Visualisierungsbalken anklicken, um die Probleme zu filtern. Sie können auch eine Problemkategorie auswählen, um die mit dieser Problemkategorie verknüpften Logeinträge aufzurufen.
Wählen Sie den Tab Logeinträge aus, um weitere Informationen zu jedem Übersetzungsproblem aufzurufen, einschließlich der Problemkategorie, des spezifischen Problemeintrags und eines Links zu der Datei, in der das Problem aufgetreten ist. Sie können auf die Balken der Sankey-Visualisierung klicken, um Probleme zu filtern. Sie können auf dem Tab Logeinträge ein Problem auswählen, um den Tab Code zu öffnen, der die Eingabe- und Ausgabedatei anzeigt, wenn zutreffend.
Klicken Sie auf den Tab Jobdetails, um Details zur Konfiguration des Übersetzungsjobs aufzurufen.

Zusammenfassender Bericht

Der Zusammenfassungsbericht ist eine CSV-Datei, die eine Tabelle aller Warn- und Fehlermeldungen enthält, die während des Übersetzungsjobs aufgetreten sind.

So rufen Sie die Zusammenfassungsdatei in der Google Cloud Console auf:

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Suchen Sie in der Liste der Übersetzungsjobs nach dem gewünschten Job und klicken Sie dann auf den Jobnamen oder auf Weitere Optionen> Details anzeigen.
Klicken Sie auf der Registerkarte Jobdetails im Abschnitt Übersetzungsbericht auf translation_report.csv.
Klicken Sie auf der Seite Objektdetails auf den Wert in der Zeile Authentifizierte URL, um die Datei in Ihrem Browser anzuzeigen.

In der folgenden Tabelle werden die Spalten der Zusammenfassungsdatei beschrieben:

Spalte	Beschreibung
Zeitstempel	Der Zeitstempel, zu dem das Problem aufgetreten ist.
FilePath	Der Pfad zur Quelldatei, mit der das Problem verknüpft ist.
FileName	Der Name der Quelldatei, mit der das Problem verknüpft ist.
Skriptzeile	Die Zeilennummer, in der das Problem aufgetreten ist
Skriptspalte	Die Spaltennummer, in der das Problem aufgetreten ist.
TranspilerComponent	Die interne Komponente des Übersetzungsmoduls, in der die Warnung oder der Fehler aufgetreten ist. Diese Spalte ist möglicherweise leer.
Umgebung	Die Übersetzungsdialektsumgebung, die der Warnung oder dem Fehler zugeordnet ist. Diese Spalte ist möglicherweise leer.
ObjectName	Das SQL-Objekt in der Quelldatei, die der Warnung oder dem Fehler zugeordnet ist. Diese Spalte ist möglicherweise leer.
Schweregrad	Der Schweregrad des Problems, entweder eine Warnung oder ein Fehler.
Kategorie	Die Kategorie des Übersetzungsproblems.
SourceType	Die Ursache des Problems. Der Wert in dieser Spalte kann entweder `SQL` sein, was auf ein Problem mit den SQL-Eingabedateien hinweist, oder `METADATA`, was auf ein Problem im Metadatenpaket hinweist.
Meldung	Warnmeldung oder Fehlermeldung des Übersetzungsproblems
ScriptContext	Das SQL-Snippet in der Quelldatei, die mit dem Problem verknüpft ist.
Aktion	Wir empfehlen, das Problem zu beheben.

Tab „Code“

Auf dem Tab „Code“ haben Sie die Möglichkeit, weitere Informationen zu den Eingabe- und Ausgabedateien für einen bestimmten Übersetzungsjob zu prüfen. Auf dem Tab „Code“ können Sie die in einem Übersetzungsjob verwendeten Dateien untersuchen, einen direkten Vergleich einer Eingabedatei und ihrer Übersetzung ausführen und dabei Ungenauigkeiten ermitteln sowie Logzusammenfassungen und -einträge für eine bestimmte Datei in einem Job aufrufen.

So greifen Sie auf den Tab „Code“ zu:

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Suchen Sie in der Liste der Übersetzungsjobs nach dem gewünschten Job und klicken Sie dann auf den Jobnamen oder auf Weitere Optionen> Details anzeigen.
Wählen Sie den Tab Code aus. Der Tab „Code“ besteht aus den folgenden Bereichen:
- Dateiexplorer: Enthält alle SQL-Dateien, die für die Übersetzung verwendet werden. Klicken Sie auf eine Datei, um die Ein- und Ausgabe der Übersetzung sowie alle Übersetzungsprobleme der Übersetzung anzusehen.
- Gemini-optimierte Eingabe: Der Eingabe-SQL-Code, der von der Übersetzungs-Engine übersetzt wurde. Wenn Sie Gemini-Anpassungsregeln für die Quell-SQL-Datei angegeben habenin der Gemini-Konfiguration Der Übersetzer transformiert dann zuerst die ursprüngliche Eingabe und übersetzt anschließend die mit Gemini optimierte Eingabe. Wenn Sie die ursprüngliche Eingabe ansehen möchten, klicken Sie auf Ursprüngliche Eingabe ansehen.
- Übersetzungsausgabe: Das Übersetzungsergebnis. Wenn Sie in der Gemini-Konfiguration Regeln zur Anpassung von Gemini für das Ziel-SQL angegeben haben, wird die Transformation als Gemini-optimierte Ausgabe auf das übersetzte Ergebnis angewendet. Wenn eine mit Gemini optimierte Ausgabe verfügbar ist, können Sie auf die Schaltfläche Gemini-Vorschlag klicken, um sie anzusehen.
Optional: Um eine Eingabedatei und ihre Ausgabedatei im interaktiven SQL-Übersetzer von BigQuery anzuzeigen, klicken Sie auf Bearbeiten. Sie können die Dateien bearbeiten und die Ausgabedatei wieder in Cloud Storage speichern.

aufrufen.

Tab "Konfiguration"

Auf dem Tab Konfiguration können Sie Ihre YAML-Konfigurationsdateien hinzufügen, umbenennen, ansehen oder bearbeiten.Im Schema-Explorer finden Sie die Dokumentation für unterstützte Konfigurationstypen, die Ihnen beim Schreiben Ihrer YAML-Konfigurationsdateien helfen. Nachdem Sie die Konfigurations-YAML-Dateien bearbeitet haben, können Sie den Job erneut ausführen, um die neue Konfiguration zu verwenden.

So greifen Sie auf den Tab „Konfiguration“ zu:

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Suchen Sie in der Liste der Übersetzungsaufträge den Auftrag, der Sie interessiert, und klicken Sie dann auf den Auftragsnamen oder auf Weitere Optionen > Details anzeigen.
Klicken Sie im Fenster Übersetzungsdetails auf die Registerkarte Konfiguration.

Sehen Sie sich die Registerkarte „Konfiguration“ auf der Seite „SQL-Übersetzung“ an.

So fügen Sie eine neue Konfigurationsdatei hinzu:

Klicken Sie auf more_vert Weitere Optionen > YAML-Konfigurationsdatei erstellen.
Es wird ein Bereich angezeigt, in dem Sie den Typ, den Speicherort und den Namen der neuen YAML-Konfigurationsdatei auswählen können.
Klicken Sie auf Erstellen.

So bearbeiten Sie eine vorhandene Konfigurationsdatei:

Klicken Sie auf die YAML-Konfigurationsdatei.
Bearbeiten Sie die Datei und klicken Sie dann auf Speichern.
Klicken Sie auf Nochmal ausführen, um einen neuen Übersetzungsjob auszuführen, in dem die bearbeiteten YAML-Konfigurationsdateien verwendet werden.

Sie können eine bestehende Konfigurationsdatei umbenennen, indem Sie auf more_vert Weitere Optionen > Umbenennen klicken.

Verbrauchte Ausgabenamen-Zuordnungsdatei

Diese JSON-Datei enthält die Regeln für die Zuordnung des Ausgabenamens, die vom Übersetzungsjob verwendet wurden. Die Regeln in dieser Datei können sich von den Regeln der Ausgabenamenzuordnung, die Sie für den Übersetzungsjob angegeben haben, unterscheiden, entweder aufgrund von Konflikten in den Namenszuordnungsregeln oder aufgrund von fehlenden Namenszuordnungsregeln für SQL-Objekte, die während der Übersetzung identifiziert wurden. Prüfen Sie diese Datei, um festzustellen, ob die Namenszuordnungsregeln korrigiert werden müssen. Erstellen Sie in diesem Fall neue Zuordnungsregeln für den Ausgabenamen, die alle von Ihnen erkannten Probleme beheben, und führen Sie einen neuen Übersetzungsjob aus.

Übersetzte Dateien

Für jede Quelldatei wird eine entsprechende Ausgabedatei im Zielpfad generiert. Die Ausgabedatei enthält die übersetzte Abfrage.

Batch-übersetzte SQL-Abfragen mit dem interaktiven SQL-Übersetzer debuggen

Mit dem interaktiven BigQuery-SQL-Übersetzer können Sie eine SQL-Abfrage mit denselben Metadaten oder Objektnamenzuordnungsinformationen wie Ihre Quelldatenbank überprüfen oder debuggen. Nachdem Sie einen Batchübersetzungsjob abgeschlossen haben, generiert BigQuery eine Übersetzungskonfigurations-ID, die Informationen zu den Metadaten des Jobs, zur Objektzuordnung oder zum Schemasuchpfad enthält, je nachdem, was für die Abfrage gilt. Sie verwenden die ID der Batchübersetzungskonfiguration mit dem interaktiven SQL-Übersetzer, um SQL-Abfragen mit der angegebenen Konfiguration auszuführen.

Um eine interaktive SQL-Übersetzung mithilfe einer Batch-Übersetzungskonfigurations-ID zu starten, gehen Sie wie folgt vor:

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Suchen Sie in der Liste der Übersetzungsjobs nach dem gewünschten Job und klicken Sie dann auf Weitere Optionen> Interaktive Übersetzung öffnen.

Der interaktive BigQuery-SQL-Übersetzer wird jetzt mit der entsprechenden Batch-Übersetzungskonfigurations-ID geöffnet. Um die Übersetzungskonfigurations-ID für die interaktive Übersetzung anzuzeigen, klicken Sie im interaktiven SQL-Übersetzer auf Tools > Query translation > Translation settings.

Um eine Batch-Übersetzungsdatei im interaktiven SQL-Übersetzer zu debuggen, gehen Sie wie folgt vor:

Rufen Sie in der Google Cloud Console die Seite SQL-Übersetzung auf.

Zur SQL-Übersetzung
Suchen Sie in der Liste der Übersetzungsjobs nach dem gewünschten Job und klicken Sie dann auf den Jobnamen oder auf das Dreipunkt-Menü > Details anzeigen.
Klicken Sie im Fenster Übersetzungsdetails auf den Tab Code.
Klicken Sie im Datei-Explorer auf den Dateinamen, um die Datei zu öffnen.
Klicken Sie neben dem Ausgabedateinamen auf Bearbeiten, um die Dateien im interaktiven SQL-Übersetzer (Vorschau) zu öffnen.

Sie sehen die Eingabe- und Ausgabedateien im interaktiven SQL-Übersetzer, der nun die entsprechende Batch-Übersetzungskonfigurations-ID verwendet.
Wenn Sie die bearbeitete Ausgabedatei wieder in Cloud Storage speichern möchten, klicken Sie im interaktiven SQL-Übersetzer auf Speichern> In GCS speichern.

Beschränkungen

Der Übersetzer kann keine benutzerdefinierten Funktionen (UDFs) aus anderen Sprachen als SQL übersetzen, da er sie nicht parsen kann, um ihre Eingabe- und Ausgabedatentypen zu bestimmen. Dies führt dazu, dass die Übersetzung von SQL-Anweisungen, die auf diese UDFs verweisen, ungenau ist. Damit Nicht-SQL-UDFs während der Übersetzung ordnungsgemäß referenziert werden, verwenden Sie gültige SQL-Anweisungen, um Platzhalter-UDFs mit denselben Signaturen zu erstellen.

Beispiel: Sie haben eine UDF in C, die die Summe zweier Ganzzahlen berechnet. Um sicherzustellen, dass SQL-Anweisungen, die auf diese UDF verweisen, korrekt übersetzt werden, erstellen Sie eine Platzhalter-SQL-UDF, die dieselbe Signatur wie die C-UDF hat, wie im folgenden Beispiel gezeigt:

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

Speichern Sie diese Platzhalter-UDF in einer Textdatei und fügen Sie diese Datei als Quelldatei für den Übersetzungsjob ein. Dadurch kann der Übersetzer die UDF-Definition lernen und die erwarteten Eingabe- und Ausgabedatentypen identifizieren.

Kontingent und Limits

Dafür gelten die Kontingente der BigQuery Migration API.
Jedes Projekt kann höchstens 10 aktive Übersetzungsaufgaben haben.
Die Gesamtzahl der Quell- und Metadatendateien ist zwar nicht begrenzt, es empfiehlt sich jedoch, die Anzahl der Dateien unter 1.000 zu halten, um eine bessere Leistung zu erzielen.

Behebung von Übersetzungsfehlern

Übersetzungsprobleme `RelationNotFound` oder `AttributeNotFound`

Nach der Übersetzung einer Abfrage mit dem Batch-SQL-Übersetzer kann es zu einer fehlgeschlagenen Übersetzung mit dem Fehler RelationNotFound oder AttributeNotFound kommen.

Fehlgeschlagene Übersetzungen finden Sie, indem Sie zur Seite Übersetzungsdetails navigieren und die Registerkarte Protokollmeldungen öffnen.

Übersetzung funktioniert am besten mit Metadaten-DDLs. Wenn SQL-Objektdefinitionen nicht gefunden werden können, gibt die Übersetzungs-Engine RelationNotFound- oder AttributeNotFound-Probleme aus. Wir empfehlen die Verwendung des Metadaten-Extrahierers zum Generieren von Metadatenpaketen, um dafür zu sorgen, dass alle Objektdefinitionen vorhanden sind. Das Hinzufügen von Metadaten ist der erste empfohlene Schritt, um die meisten Übersetzungsfehler zu beheben, da oft viele andere Fehler behoben werden können, die indirekt durch ein Fehlen von Metadaten verursacht werden.

Weitere Informationen finden Sie unter Metadaten für Übersetzung und Bewertung generieren.

Übersetzungsprobleme mit Gemini beheben

Um fehlgeschlagene Übersetzungsjobs mit den Fehlern RelationNotFound oder AttributeNotFound zu beheben, können Sie auch Gemini verwenden. Gehen Sie dazu so vor:

Navigieren Sie zur Seite Übersetzungsdetails und öffnen Sie die Registerkarte Protokollmeldungen.
Klicken Sie auf die Abfrage, die in der Spalte Category die Meldung RelationNotFound oder AttributeNotFound enthält.
Klicken Sie auf die Fehlermeldung, um im Tab „Code“ zur Datei und Zeile mit dem Fehler zu gelangen.
Klicken Sie in der Spalte Aktion auf Vorgeschlagene Korrektur.
Wählen Sie eine der folgenden Optionen aus: Anwenden oder Anwenden und noch einmal ausführen:
- Klicken Sie auf Anwenden, um die generierte Schemadatei vom Ausgabeverzeichnis in das Eingabeverzeichnis zu kopieren.
- Klicken Sie auf Übernehmen und noch einmal ausführen, um die generierte Schemadatei aus dem Ausgabeverzeichnis in das Eingabeverzeichnis zu kopieren und ein Fenster für die erneute Ausführung zu öffnen.

Preise

Für die Verwendung des Batch-SQL-Übersetzers fallen keine Kosten an. Für die Speicherung von Eingabe- und Ausgabedateien werden jedoch die normalen Gebühren berechnet. Weitere Informationen finden Sie unter Speicherpreise.

Nächste Schritte

Mehr über die folgenden Schritte bei der Data Warehouse-Migration erfahren:

Code mit dem Batch-SQL-Übersetzer migrieren

Hinweis

SQL-Übersetzungen aktivieren

Erforderliche Berechtigungen

Erforderliche Berechtigungen

Quelldateien erfassen

Metadatendateien erstellen

Entscheiden, wie der Übersetzungsjob gesendet werden soll

Erstellen Sie Konfigurations-YAML-Dateien

Eingabedateien nach Cloud Storage hochladen

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

Wichtige Hinweise für Produktionsumgebungen:

Hilfs-UDFs in Ihrem Projekt bereitstellen:

Übersetzungsjob senden

Console

Batch-Übersetzungsclient

BigQuery-Befehlszeile

Übersetzungsausgabe ansehen

Google Cloud -Konsolenausgabe

Zusammenfassender Bericht

Tab „Code“

Tab "Konfiguration"

Verbrauchte Ausgabenamen-Zuordnungsdatei

Übersetzte Dateien

Batch-übersetzte SQL-Abfragen mit dem interaktiven SQL-Übersetzer debuggen

Beschränkungen

Kontingent und Limits

Behebung von Übersetzungsfehlern

Übersetzungsprobleme RelationNotFound oder AttributeNotFound

Übersetzungsprobleme mit Gemini beheben

Preise

Nächste Schritte

Übersetzungsprobleme `RelationNotFound` oder `AttributeNotFound`