Metadaten aus dbt Core importieren

In diesem Dokument wird beschrieben, wie Sie mit dem Befehl gcloud Metadaten aus dbt Core und MetricFlow in Knowledge Catalog (früher Dataplex Universal Catalog) importieren.

Die folgenden Metadaten werden von der dbt-Integration erfasst:

  • Technische Metadaten: Dazu gehören wichtige Ressourcen (Quellen, Ausgangswerte, Modelle) und ihre technischen Eigenschaften (Spaltennamen, Datentypen, Zeilenanzahl).
  • Geschäfts- und semantische Metadaten: Diese werden von dbt MetricFlow unterstützt und umfassen Geschäftsdefinitionen und ‑logik wie semantische Modelle, Messwerte und gespeicherte Abfragen.
  • Metadaten zur Betriebs- und Datenqualität: Dazu gehören Ausführungsmetadaten wie Zeitangaben, Status (Erfolg oder Fehler), Datenaktualität, Tests und Testergebnisse.
  • Metadaten zu Herkunft und Beziehungen: Dazu gehören Transformationsdiagramme (DAGs) und Abhängigkeiten zwischen dbt-Ressourcen, physische Herkunft, die physische Transformationsblöcke, Join-Schlüssel und dynamische Joins verfolgt und verknüpft, sowie Beziehungen zwischen über- und untergeordneten Elementen.
  • Metadaten zur Nutzung: Dazu gehören Metadaten, die in Exposures erfasst werden und die zeigen, wie Daten außerhalb von dbt verwendet werden.

Bevor Sie Metadaten aus dbt Core und MetricFlow importieren können, müssen Sie die folgenden Aufgaben ausführen:

  1. Weisen Sie die erforderlichen Rollen und Berechtigungen zu.
  2. Knowledge Catalog API aktivieren
  3. Erfüllen Sie die dbt-Voraussetzungen.
  4. Erstellen Sie die Zieleintragsgruppe, falls sie noch nicht vorhanden ist.
  5. Cloud Storage-Rollen

IAM-Rollen und -Berechtigungen

Zum Erstellen und Verwalten eines Knowledge Catalog-Connector-Jobs benötigen Sie IAM-Rollen (Identity and Access Management), die Berechtigungen für Knowledge Catalog und Cloud Storage gewähren.

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren eines dbt-Connectors benötigen:

  • Zum Erstellen und Verwalten von Eintragsgruppen benötigen Sie die Rolle Dataplex Catalog Admin (roles/dataplex.catalogAdmin), Dataplex Catalog Editor (roles/dataplex.catalogEditor) oder Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) für das Projekt.

  • So führen Sie den dbt-Befehl gcloud aus und erstellen Metadaten-Importjobs: Um das Prinzip der geringsten Berechtigung zu befolgen, weisen Sie die folgenden Rollen zu:

    Alternativ können Sie die Rolle Dataplex Catalog Admin (roles/dataplex.catalogAdmin) und die Rolle Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) für das Projekt zuweisen.

  • So laden Sie transformierte Metadaten in den Ausgabebucket (--storage-uri) hoch: Storage-Objekt-Ersteller (roles/storage.objectCreator) oder Storage-Objekt-Administrator (roles/storage.objectAdmin) für den Staging-Bucket.

  • Zum Lesen von dbt-Artefakten aus einem Cloud Storage-Eingabe-Bucket (--artifacts-path, wenn Cloud Storage verwendet wird): Storage-Objekt-Betrachter (roles/storage.objectViewer) oder Storage-Objekt-Administrator (roles/storage.objectAdmin) für den Bucket mit den Eingabeartefakten. Wenn Sie die Rolle „Storage-Objekt-Administrator“ haben, ist die Rolle „Storage-Objekt-Betrachter“ nicht erforderlich.

  • So rufen Sie dbt-Metadaten auf: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) für das Projekt.

  • So rufen Sie Logs in Cloud Logging auf: Loganzeige (roles/logging.viewer) für das Projekt.

Außerdem müssen Sie dem Knowledge Catalog-Dienst-Agenten (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) die Rolle Storage Object Viewer (roles/storage.objectViewer) für den Cloud Storage-Bucket für das Staging der Ausgabe (--storage-uri) zuweisen, damit der Importjob die bereitgestellte Metadatendatei lesen kann.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

APIs aktivieren

Aktivieren Sie die Knowledge Catalog API.

API aktivieren

dbt-Voraussetzungen

Wenn Sie alle dbt-Metadaten importieren möchten, empfehlen wir, alle vier dbt-JSON-Artefaktdateien zu erstellen. Nur manifest.json ist erforderlich. Die anderen Felder optimieren den Import. Ohne sie wird die Transformation jedoch nicht beeinträchtigt:

  • manifest.json (erforderlich): Kernprojektstruktur und Ausführungsdiagramm. Außerdem enthält sie die semantischen Modelle, Messwerte und gespeicherten Abfragen von MetricFlow.
  • catalog.json: Spaltennamen und Datentypen. Ohne catalog.json wird der Schemaaspekt mit Spalten ohne Typ importiert.
  • run_results.json: Testergebnisse und Ausführungsmetadaten.
  • sources.json: Aktualität der Quelle.

Wenn Sie den vollständigen Satz von JSON-Dateien für dbt-Metadatenartefakte generieren möchten, können Sie die folgenden dbt-Befehle in dieser Reihenfolge ausführen:

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

Cloud Storage-Rollen

Beim Importieren von dbt-Metadaten sind zwei verschiedene Cloud Storage-Speicherorte beteiligt, die unterschiedliche Zwecke erfüllen und nicht verwechselt werden sollten:

  • Eingabe (dbt-Quellartefakte): Hier befinden sich Ihre generierten dbt-JSON-Dateien. Dies kann ein lokaler Verzeichnispfad auf Ihrem Computer oder CI-Runner (z. B. ./target/ oder .) oder ein URI-Präfix für einen Cloud Storage-Bucket (z. B. gs://my-dbt-artifacts-bucket/target/) sein. Sie geben diesen Pfad mit dem Flag --artifacts-path an. Mit dem Befehl gcloud werden diese Eingabedateien während der Jobvorbereitung gelesen. Der Aufrufer, der den gcloud-Befehl ausführt, benötigt Lesezugriff (roles/storage.objectViewer oder roles/storage.objectAdmin), wenn Cloud Storage verwendet wird. Der Knowledge Catalog-Dienst-Agent benötigt keinen Zugriff auf den Bucket für Eingabeartefakte.
  • Ausgabe (Knowledge Catalog-Import-Staging-Bucket): Ein Cloud Storage-Bucket-URI-Präfix (z. B. gs://my-staging-bucket/dbt-imports/), in das mit dem gcloud-Befehl die transformierte Metadaten-Importdatei (dbt_metadata.jsonl) hochgeladen wird und aus dem der Knowledge Catalog-Importjob während der Aufnahme liest. Sie geben diesen URI mit dem Flag --storage-uri an. Der Aufrufer, der den gcloud-Befehl ausführt, benötigt Schreibzugriff (roles/storage.objectCreator oder roles/storage.objectAdmin), um die Datei hochzuladen, und der Knowledge Catalog-Service-Agent benötigt Lesezugriff (roles/storage.objectViewer), um sie zu importieren.

dbt-Verbindung konfigurieren

Um eine dbt-Verbindung herzustellen, müssen Sie zuerst die entsprechenden dbt-Befehle ausführen, um die Metadatenartefakte zu generieren. Sobald die JSON-Dateien gespeichert und zugänglich sind, werden beim Importvorgang die folgenden Aktionen ausgeführt:

  1. Eingabeartefakte lesen: Die von dbt Core und MetricFlow generierten JSON-Artefakte werden aus dem Eingabespeicherort gelesen (lokales Verzeichnis oder Cloud Storage-URI, der in --artifacts-path angegeben ist).
  2. Metadaten transformieren: Transformieren Sie den Inhalt in das Knowledge Catalog-Metadatenimportformat (dbt_metadata.jsonl).
  3. In Staging hochladen: Laden Sie die transformierte Metadaten-Importdatei an den in --storage-uri angegebenen Cloud Storage-Ausgabe-Staging-Speicherort hoch.
  4. Importjob auslösen: Lösen Sie einen Knowledge Catalog-Metadatenimportjob aus, der den Knowledge Catalog-Dienst-Agent anweist, die bereitgestellten Metadaten aus --storage-uri zu lesen und in Knowledge Catalog-Ressourcen aufzunehmen.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Knowledge Catalog Connectors auf.

    Zu „Connectors“

  2. Klicken Sie auf Verbindung hinzufügen.

  3. Wählen Sie in der Liste Connectors die Karte dbt Core und MetricFlow aus.

  4. Wenn Sie Ihre importierten dbt-Assets aufrufen möchten, rufen Sie die Seite Suche oder die Zielseite Eintragsgruppen auf.

gcloud

So erstellen Sie einen dbt-Metadatenjob:

  1. Achten Sie darauf, dass die dbt-Metadatenartefaktdateien lokal oder in einem Cloud Storage-Eingabe-Bucket gespeichert sind.
  2. Sie müssen einen Cloud Storage-Staging-Bucket für die Ausgabe mit den entsprechenden Berechtigungen für den Aufrufer und den Knowledge Catalog-Dienst-Agent konfiguriert haben.

  3. Führen Sie den gcloud-Befehl über Cloud Shell, ein lokales Terminal oder ein automatisiertes Workflow-Tool aus:

    gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/

    Erforderliche Flags

    • --storage-uri=STORAGE_URI: (Ausgabe/Staging) Cloud Storage-URI-Präfix (gs://bucket/path/), in das die transformierte JSONL-Datei hochgeladen wird und aus dem der Importjob während der Aufnahme liest. Der Aufrufer muss Schreibzugriff (roles/storage.objectCreator oder roles/storage.objectAdmin) und der Knowledge Catalog-Dienst-Agent Lesezugriff (roles/storage.objectViewer) haben.

    Optionale Flags

    • --artifacts-path=ARTIFACTS_PATH: (Eingabe) Pfad zu den dbt-Quellartefakten. Dies kann ein lokaler Verzeichnispfad (z. B. . oder ./target) oder ein Cloud Storage-URI-Präfix (z. B. gs://my-bucket/dbt-artifacts/) sein. Er kann auf das Stammverzeichnis des dbt-Projekts (das Unterverzeichnis target/ wird automatisch erkannt) oder direkt auf das Verzeichnis mit manifest.json verweisen. Die Standardeinstellung ist .. Wenn ein Cloud Storage-URI angegeben wird, muss der Aufrufer Lesezugriff (roles/storage.objectViewer oder roles/storage.objectAdmin) auf den Eingabe-Bucket haben.
    • --async: Es wird sofort zurückgegeben, ohne auf den Abschluss des laufenden Vorgangs zu warten.
    • --entry-group=ENTRY_GROUP: Kurze ID der Eintragsgruppe, die die dbt-Einträge empfängt. Muss bereits im Projekt und am Standort vorhanden sein (Standard ist dbt-metadata-ingestion).
    • --aspects-only: Nur die Metadaten aktualisieren, die bei diesem dbt-Lauf beobachtet wurden, und den Rest der Eintragsgruppe unverändert lassen. Es wird kein Eintrag erstellt, gelöscht oder neu zugeordnet. Ein Aspekt, dessen dbt-Artefakt in diesem Lauf nicht vorhanden war, behält den Wert aus einem vorherigen Lauf bei. Verwenden Sie diese Option für die routinemäßige, wiederholte Aufnahme. Weitere Informationen finden Sie unter Datenaufnahme noch einmal ausführen.
    • --validate-only: Erstellt und lädt die JSON-Datei hoch und validiert den Metadatenjob, führt aber keine Aufnahme durch.

  4. Prüfen Sie, ob Sie den Status Created (Erstellt) erhalten haben.

REST

So importieren Sie dbt-Metadaten mit der REST API:

  1. Generieren Sie die dbt-Artefakte und wandeln Sie sie in die JSON-Importdatei (dbt_metadata.jsonl) für Knowledge Catalog um.
  2. Laden Sie die transformierte Datei in Ihren Cloud Storage-Staging-Bucket (gs://BUCKET_NAME/PATH/) hoch.

  3. Rufen Sie die Methode projects.locations.metadataJobs.create auf.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die Google Cloud Projekt-ID des Projekts, in dem sich Ihre Eintragsgruppe befindet.
    • LOCATION: Die Region Ihrer Eintragsgruppe, z. B. us-central1.
    • JOB_ID: Eine eindeutige Kennung für den Metadatenjob.
    • BUCKET_NAME/PATH: Das Cloud Storage-URI-Präfix, in das dbt_metadata.jsonl hochgeladen wurde.
    • ENTRY_GROUP: die kurze ID der Zielgruppe.

  4. Verwenden Sie die Methode projects.locations.metadataJobs.get, um den Status Ihres Importjobs zu verfolgen:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

Nachdem Sie den Job erstellt haben, plant Knowledge Catalog die erste Ausführung entsprechend Ihrer Konfiguration oder Sie können sie manuell starten.

Aufnahme noch einmal ausführen

Nach dem ersten Import muss bei den meisten Ausführungen nur die Aktualisierung der Metadaten für bereits vorhandene Ressourcen erfolgen. Verwenden Sie für diese Läufe --aspects-only. Es werden nur die Änderungen aktualisiert, die beim dbt-Lauf beobachtet wurden. Alles andere in der Eingabegruppe bleibt unverändert. Der Prozess kann also beliebig oft, nach einem beliebigen Zeitplan und von mehreren Jobs aus ausgeführt werden.

Vollständige Aufnahme ausführen (--aspects-only weglassen), wenn sich die Menge der Einträge ändert:

  • Die erste Aufnahme in eine Eintragsgruppe.
  • Eine dbt-Ressource wird hinzugefügt, umbenannt oder gelöscht.
  • Der Anzeigename, die Beschreibung oder die Labels eines Eintrags werden geändert.
  • Die Hierarchie der Einträge ändert sich.

Bei einem vollständigen Lauf werden die erforderlichen Aspekte jedes Eintrags aus den Artefakten auf der Festplatte neu geschrieben. Führen Sie ihn daher mit einem möglichst vollständigen Artefaktsatz aus, den Ihre Pipeline erzeugen kann.

--aspects-only für regelmäßige Aktualisierungen ausführen:

  • Nach dem dbt-Befehl, der in Ihrer Pipeline ausgeführt wird: dbt build, dbt test, dbt source freshness oder ein auf --select beschränkter Neuaufbau.
  • Eine Spalte wird hinzugefügt, entfernt, neu typisiert oder neu beschrieben.
  • Das Modell-SQL wurde geändert und beim Ausführen wurde auch catalog.json geschrieben.
  • Neue Testergebnisse oder Aktualität der Quelle.

--aspects-only kann Metadaten hinzufügen und aktualisieren, aber nicht entfernen.

dbt-Metadaten suchen und ansehen

Console

  1. Rufen Sie in der Google Cloud Console die Seite Suchen im Knowledge Catalog auf.

    Zur Suche

  2. Filtern Sie im Bereich Filter nach dbt-Assets:

    • Wählen Sie im Bereich System die Option Imported Context (Importierter Kontext) aus.
    • Wählen Sie im Unterabschnitt Managed Connectors (Verwaltete Connectors) die Option dbt aus.

  3. Geben Sie Ihre Anfrage im Suchfeld ein. Sie können dazu Keywords oder natürliche Sprache verwenden. Wenn Sie beispielsweise alle dbt-Assets mithilfe der Keyword-Suche aufrufen möchten, geben Sie system=DBT oder system=DBT AND type=dbt-model ein.

  4. Klicken Sie in den Suchergebnissen auf ein beliebiges dbt-Asset, um die Seite mit den Eintragsdetails zu öffnen und das Schema, die Herkunft und die technischen Aspekte anzusehen.

gcloud

  1. Verwenden Sie den Befehl gcloud dataplex entries search, um in Ihrem gesamten Projekt nach dbt-Einträgen zu suchen:

    gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

    So filtern Sie nach einem bestimmten dbt-Eintragstyp (z. B. Modelle oder Quellen):

    gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

  2. Wenn Sie die vollständigen Details und Aspekte eines bestimmten dbt-Eintrags aufrufen möchten, verwenden Sie den Befehl gcloud dataplex entries lookup:

    gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Projekt-ID in Google Cloud .
    • LOCATION: Der Speicherort der Eintragsgruppe, z. B. us-central1.
    • ENTRY_GROUP: die kurze ID Ihrer Zielgruppe (z. B. dbt-metadata-ingestion).
    • ENTRY_ID: die kurze ID oder der relative Ressourcenname des dbt-Eintrags.

REST

  1. Rufen Sie die Methode projects.locations:searchEntries auf, um nach dbt-Einträgen zu suchen:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

    So filtern Sie nach einem bestimmten dbt-Ressourcentyp:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

  2. Rufen Sie die Methode projects.locations.entryGroups.entries.get auf, um vollständige Metadatendetails und Aspekte für einen bestimmten Eintrag abzurufen:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

  3. Verwenden Sie die projects.locations:lookupContext API, um den LLM-Kontext für bestimmte dbt-Ressourcen abzurufen:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Projekt-ID in Google Cloud .
    • LOCATION: Der Speicherort der Eintragsgruppe, z. B. us-central1.
    • ENTRY_GROUP: die kurze ID Ihrer Zielgruppe (z. B. dbt-metadata-ingestion).
    • ENTRY_ID: die kurze ID oder der relative Ressourcenname des dbt-Eintrags.

Weitere Informationen zum Suchen nach Ressourcen finden Sie unter Nach Ressourcen in Knowledge Catalog suchen. Weitere Informationen zu Abfrageausdrücken und Filtern finden Sie unter Suchsyntax für Knowledge Catalog.

Beschränkungen

  • Unterstützt aktuelle dbt Core v1-Versionen (getestet mit den Versionen 1.11 und 1.12). dbt Core v2 und dbt Fusion werden nicht unterstützt.
  • dbt-Modelle, die Modellversionierung verwenden, werden nicht unterstützt.
  • dbt Cloud wird nicht unterstützt.
  • Sehr große oder tief verschachtelte Schemas werden gekürzt: Ein einzelner Aspekt darf die Größenbeschränkung pro Aspekt nicht überschreiten. Bei tief verschachtelten Schemas können daher nachfolgende Felder verloren gehen.
  • --aspects-only kann Metadaten hinzufügen und aktualisieren, aber nicht entfernen. Zum Löschen einer dbt-Ressource ist ein vollständiger Lauf erforderlich.
  • Eintrag-Links werden nicht unterstützt.
  • Diese Integration unterstützt nur dbt-Abstammungsereignisse für BigQuery-Ressourcen in der Data Lineage API und im ‑Diagramm. dbt-Einträge (Quelle, Seeds, Modelle) für externe Drittanbieterquellen werden nicht in der Datenabstammung erfasst.

Nächste Schritte