Metadaten aus dbt Core importieren

Für Data Engineers, Analytics Engineers und Data Stewards ist die Zentralisierung von Metadaten entscheidend für die unternehmensweite Datenermittlung und ‑verwaltung. Wenn Teams dbt für die Datentransformation verwenden, werden wertvolle Betriebs-, semantische und Lineage-Metadaten generiert, die jedoch häufig im dbt-Ökosystem verbleiben.

Wenn Sie diese Informationen in Ihren zentralen Katalog einbinden möchten, können Sie Metadaten aus dbt Core, dbt Cloud und MetricFlow in Knowledge Catalog (früher Dataplex Universal Catalog) importieren.

Da dbt Core als Transformations-Engine und nicht als Speichersystem wie Oracle oder PostgreSQL fungiert, sind durch den Import der Metadaten verschiedene Anwendungsfälle möglich. Sie importieren Oracle- oder PostgreSQL-Metadaten, um die Frage „Welche Rohdaten haben wir?“ zu beantworten, und dbt Core-Metadaten, um die Frage „Wie werden unsere Daten transformiert, sind sie zuverlässig und was bedeuten sie für das Unternehmen?“ zu beantworten.

In diesem Dokument wird beschrieben, wie Sie Metadaten mit dem Google Cloud CLI-Befehl und Ihren dbt-Artefaktdateien importieren.

Wenn Sie die dbt-Integration ausführen, werden die folgenden Metadaten erfasst:

  • Technische Metadaten: Unternehmensdaten ermitteln, indem Sie wichtige Ressourcen (Quellen, Seeds, Modelle) und ihre technischen Eigenschaften (Spaltennamen, Datentypen, Zeilenanzahl) untersuchen.
  • Geschäftliche und semantische Metadaten: Sie bieten Kontext für BI-Tools und KI-Agents, indem sie Geschäftsdefinitionen und Logik auf Grundlage von dbt MetricFlow untersuchen, z. B. semantische Modelle, Messwerte und gespeicherte Abfragen.
  • Metadaten zur Betriebs- und Datenqualität: Überwachen Sie den Zustand der Pipeline und beheben Sie Datenprobleme, indem Sie Ausführungsmetadaten wie Timing, Status (Erfolg oder Fehler), Datenaktualität und Testergebnisse untersuchen.
  • Metadaten zu Herkunft und Beziehungen: Ermöglichen die Analyse von Downstream-Auswirkungen und die Suche nach der Ursache, indem Sie 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 untersuchen.
  • Metadaten zur Nutzung: Hier können Sie Probleme mit der Nutzung transformierter Daten durch Downstream-Anwendungen beheben. Dazu sehen Sie sich Metadaten in den Exposures an, die zeigen, wie Daten außerhalb von dbt verwendet werden.

Beschränkungen

  • Unterstützt dbt Core v1 (getestet mit den Versionen 1.11 und 1.12), dbt Core v2 und dbt Fusion.
  • Die dbt- und BigQuery-Integration wird ab der gcloud CLI-Version 586.0.0 unterstützt. Informationen zum Installieren oder Aktualisieren der CLI finden Sie unter Google Cloud CLI installieren.
  • Es gibt keine direkte Verbindung zu dbt Cloud. Wenn Sie Metadaten aus einem dbt Cloud-Job importieren möchten, müssen Sie zuerst die Artefakte des Jobs abrufen. Weitere Informationen finden Sie unter Metadaten aus dbt Cloud-Ausführungen importieren.
  • Sehr große oder tief verschachtelte Schemas werden gekürzt: Ein einzelner Aspekt darf das Größenlimit pro Aspekt nicht überschreiten. Bei tief verschachtelten Schemas gehen daher möglicherweise nachfolgende Felder verloren.
  • --aspects-only kann Metadaten hinzufügen und aktualisieren, aber nicht entfernen. Zum Löschen einer dbt-Ressource ist ein vollständiger Lauf erforderlich.
  • Diese Integration unterstützt nur dbt-Abstammungsereignisse für BigQuery-Ressourcen in der Data Lineage API und im ‑Diagramm. dbt-Einträge (Quellen, Seeds, Modelle) für externe Drittanbieterquellen werden nicht in der Datenabstammung erfasst.

Hinweis

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 und Eintragslinks 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: Halten Sie sich an das Prinzip der geringsten Berechtigung und weisen Sie die folgenden Rollen zu:

    • Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) für das Projekt.
    • Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) für die Ziel-Eintragsgruppe oder das Projekt. Wenn Sie auch Eintragslinks importieren, gewähren Sie stattdessen die Rolle Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) für das Projekt. Gewähren Sie außerdem die Rolle Dataplex Entry Owner (roles/dataplex.entryOwner) für jedes Projekt, das die BigQuery-Tabellen enthält, in die Ihre dbt-Modelle schreiben. Für benutzerdefinierte Rollen sind die Berechtigungen für den Einstiegslink dataplex.entryGroups.useReferenceEntryLink, dataplex.entryGroups.useSchemaJoinEntryLink und dataplex.entryLinks.reference.

    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.

Wenn Sie die erforderlichen Berechtigungen zum Verwalten des IAM-Zugriffs in Ihrem Projekt haben, können Sie diese Rollen Ihrem eigenen Nutzerkonto zuweisen, indem Sie die folgenden gcloud-Befehle ausführen:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

Wenn Sie den Import mit einem Dienstkonto ausführen, z. B. in einer automatisierten CI/CD-Pipeline, können Sie dem Dienstkonto diese Rollen zuweisen, indem Sie die folgenden gcloud-Befehle ausführen:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

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:

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • USER_EMAIL: die E-Mail-Adresse Ihres Kontos.
  • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse Ihres Dienstkontos.
  • STAGING_BUCKET: Der Name Ihres Cloud Storage-Bucket für die Ausgabebereitstellung (--storage-uri).
  • PROJECT_NUMBER: Ihre Google Cloud Projektnummer

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.

Wechseln Sie in Ihrem lokalen Terminal, in Cloud Shell oder in der automatisierten CI/CD-Umgebung, in der dbt installiert ist, zum Stammverzeichnis des dbt-Projekts und führen Sie die folgenden dbt-Befehle in der angegebenen Reihenfolge für ein einzelnes Profil und Ziel aus, um den vollständigen Satz von JSON-Dateien für dbt-Metadatenartefakte zu generieren:

  • Für dbt Core 2.x und dbt Fusion:

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • Für dbt Core 1.x (wo dbt parse keinen Katalog schreibt):

    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.

Metadaten aus dbt Cloud-Ausführungen importieren

Knowledge Catalog stellt keine direkte Verbindung zu dbt Cloud her. Da bei einem dbt Cloud-Job dieselben Artefaktdateien wie bei dbt Core generiert werden, können Sie Metadaten aus dbt Cloud importieren, indem Sie diese Artefaktdateien in ein lokales Verzeichnis oder einen Cloud Storage-Eingabe-Bucket abrufen und den Befehl gcloud ausführen.

Bevor Sie die Artefakte abrufen, konfigurieren Sie den dbt Cloud-Job, um den vollständigen Artefaktsatz zu generieren. Sie können die Artefaktdateien dann mit einer der folgenden Methoden aus einem dbt Cloud-Joblauf abrufen:

dbt Cloud-Job einrichten

Konfigurieren Sie in der dbt Google Cloud -Konsole die Job-Einstellungen, um den vollständigen Satz von Metadatenartefakten zu generieren:

  1. Wählen Sie im Abschnitt Ausführungseinstellungen die Option Quellaktualität ausführen aus. dbt Cloud führt dbt source freshness vor den Jobbefehlen aus, um sources.json zu generieren.
  2. Fügen Sie im Bereich Befehle dbt build hinzu.
  3. Fügen Sie einen Befehl hinzu, um catalog.json basierend auf Ihrem Release-Track zu generieren:
    • Für dbt Core 2.x- und dbt Fusion-Release-Tracks: Fügen Sie dbt parse --write-catalog als Jobbefehl hinzu.
    • Für dbt Core 1.x-Releases: Fügen Sie dbt docs generate --no-compile als Jobbefehl hinzu, anstatt die Option Dokumente bei Ausführung generieren auszuwählen. Wenn Sie das Kästchen Dokumente bei Ausführung generieren aktivieren, wird dbt docs generate ohne --no-compile ausgeführt. Dadurch werden die Testergebnisse aus dbt build überschrieben, wie unter dbt-Voraussetzungen beschrieben. Wenn ein Befehlsschritt fehlschlägt, schlägt auch der Job fehl. Bei einem Kontrollkästchenschritt ist das nicht der Fall.

Wenn dbt build fehlschlägt, z. B. weil ein Test fehlschlägt, überspringt dbt Cloud die nachfolgenden Befehle und der Lauf hat keine catalog.json. Wenn Sie immer eine erstellen möchten, fügen Sie den Katalogbefehl vor dbt build ein. Im Katalog werden die Tabellen dann so beschrieben, wie sie vor dem Build waren.

Weitere Informationen finden Sie in der dbt-Dokumentation unter Job commands und Release tracks.

Artefakte aus der dbt Google Cloud -Konsole herunterladen

So laden Sie Artefakte aus einem abgeschlossenen Lauf in der dbt-Google Cloud Konsole manuell herunter:

  1. Öffnen Sie in der dbt Google Cloud Console den abgeschlossenen Joblauf.
  2. Rufen Sie den Tab Artefakte auf, um die generierten Artefaktdaten zu sehen.
  3. Laden Sie manifest.json, catalog.json, run_results.json und sources.json in ein lokales Verzeichnis herunter.
  4. Führen Sie in Ihrem lokalen Terminal oder in Cloud Shell den gcloud-Importbefehl aus, der unter dbt-Verbindung konfigurieren beschrieben wird, und legen Sie --artifacts-path auf das Verzeichnis fest, das die heruntergeladenen Dateien enthält.

Weitere Informationen finden Sie in der dbt-Dokumentation unter Run visibility.

Artefakte mit der dbt-Plattform-CLI herunterladen

Mit der dbt-Plattform-CLI (früher dbt Cloud-CLI) werden dbt-Befehle auf der dbt Cloud-Plattform über Ihr lokales Terminal ausgeführt und die generierten Artefakte werden automatisch in das Verzeichnis target/ Ihres lokalen dbt-Projekts heruntergeladen.

  1. Wechseln Sie in Ihrem lokalen Terminal zum Stammverzeichnis Ihres dbt-Projekts und führen Sie die drei Befehle aus, die unter dbt-Voraussetzungen aufgeführt sind.
  2. Führen Sie den in dbt-Verbindung konfigurieren beschriebenen gcloud-Importbefehl aus und legen Sie --artifacts-path auf das Projektstammverzeichnis oder das Verzeichnis target/ fest.

Die CLI wird in Ihrer Entwicklungsumgebung mit Ihren persönlichen Anmeldedaten für das Data Warehouse ausgeführt. Die generierten Metadaten spiegeln also Ihr Entwicklungsschema und nicht die Produktionstabellen wider, die von einem geplanten Job erstellt wurden. Verwenden Sie die CLI für Test- oder Entwicklungs-Workflows und einen Bereitstellungsjob für geplante Produktionsimporte.

Weitere Informationen finden Sie in der dbt-Dokumentation unter Install the dbt platform CLI.

Artefakte mit der dbt Administrative API herunterladen

Mit der dbt Administrative API können Sie Artefakte aus einem abgeschlossenen Joblauf programmatisch abrufen. Der Endpunkt List Run Artifacts gibt die von einem Lauf generierten Dateipfade zurück und der Endpunkt Retrieve Run Artifact lädt eine bestimmte Artefaktdatei von der folgenden URL herunter:

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL hängt von der Region ab, in der Ihr dbt Cloud-Konto gehostet wird. Anfragen mit einem dbt Cloud-Dienst-Token authentifizieren Weitere Informationen finden Sie auf den folgenden Seiten in der dbt-Dokumentation:

Laden Sie manifest.json, catalog.json, run_results.json und sources.json über Ihr lokales Terminal, Cloud Shell oder die Umgebung für automatisierte Workflows in ein lokales Verzeichnis oder einen Cloud Storage-Bucket herunter und führen Sie dann den in dbt-Verbindung konfigurieren beschriebenen gcloud-Befehl für diesen Pfad aus.

Standardmäßig gibt der Artefaktendpunkt Artefakte aus dem letzten Schritt des Laufs zurück, sofern Sie den Abfrageparameter step nicht angeben. Wenn Sie den Job wie unter dbt Cloud-Job einrichten beschrieben konfigurieren, ist der letzte Schritt dbt parse --write-catalog oder dbt docs generate --no-compile. Dabei wird nur catalog.json geschrieben und die anderen drei Artefakte bleiben im Standardschritt unverändert.

Lauf-ID abrufen

Wenn Sie die Artefakte eines bestimmten Laufs herunterladen möchten, benötigen Sie die Lauf-ID. Sie können die Ausführungs-ID aus der Ausführungs-URL in der dbt Google Cloud Console kopieren oder die API über Ihr Terminal oder Workflow-Skript nach der letzten erfolgreichen Ausführung eines Jobs abfragen:

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

In den Suchparametern wird mit status=10 nach abgeschlossenen Läufen mit dem Status Success gefiltert. Sie können diesen Endpunkt regelmäßig abfragen, um den letzten erfolgreichen Lauf zu ermitteln, seine Artefakte herunterzuladen und den gcloud-Importbefehl auszuführen.

Import über einen Webhook auslösen

Anstatt die API abzufragen, können Sie einen dbt Cloud-Webhook konfigurieren, um einen automatischen Metadatenimport auszulösen, wenn ein Joblauf abgeschlossen ist. Der Webhook sendet eine Nutzlast an einen von Ihnen angegebenen HTTP-Endpunkt:

  1. Rufen Sie in der dbt Google Cloud -Konsole Kontoeinstellungen > Webhooks auf und klicken Sie auf Webhook erstellen (oder Neuen Webhook erstellen). Konfigurieren Sie das Webhook-Abo:
    • Ereignisse: Wählen Sie Lauf abgeschlossen (job.run.completed) aus. Diese Option wird erst ausgelöst, wenn der Lauf abgeschlossen ist und die zugehörigen Artefakte zum Herunterladen verfügbar sind.
    • Jobs: Wählen Sie die dbt Cloud-Bereitstellungsjobs aus, die Sie überwachen möchten.
    • Endpunkt: Geben Sie die HTTPS-URL eines Dienstes ein, den Sie ausführen, z. B. einen Cloud Run-Dienst oder eine Cloud Run-Funktion.
  2. Speichern Sie das von dbt Cloud angezeigte Webhook-Secret-Token. Ihr Dienst verwendet diesen geheimen Schlüssel, um den Authorization-Header zu überprüfen, der eine HMAC-SHA256-Signatur des Anfragetexts enthält.
  3. Lesen Sie in Ihrem Dienst data.runId aus der JSON-Nutzlast, laden Sie die Artefakte des Laufs mit der Administrative API wie oben beschrieben herunter und führen Sie den Befehl gcloud alpha dataplex dbt metadata-jobs create aus.

Beachten Sie bei der Implementierung des Webhook-Handlers Folgendes:

  • dbt Cloud wartet maximal 10 Sekunden auf eine Antwort. Da der Metadatenimport mehrere Minuten dauert, sollten Sie zuerst eine HTTP-Antwort zurückgeben und den Import im Hintergrund ausführen (z. B. als Cloud Run-Job oder mit dem Flag --async).
  • job.run.completed wird auch für fehlgeschlagene Läufe ausgelöst, sodass Läufe mit fehlgeschlagenen Tests weiterhin importiert werden. Abonnieren Sie job.run.errored nicht, da es ausgelöst werden kann, bevor die Artefakte des Laufs verfügbar sind.

Weitere Informationen zu Webhook-Nutzlasten und zur Signaturprüfung finden Sie in der dbt-Dokumentation unter Webhooks for your jobs.

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, es wird kein Eintragslink ausgegeben und ein Aspekt, dessen dbt-Artefakt in diesem Lauf nicht vorhanden war, behält den Wert bei, den er in einem vorherigen Lauf hatte. Verwenden Sie diese Option für die routinemäßige, wiederholte Aufnahme. Weitere Informationen finden Sie unter Datenaufnahme noch einmal ausführen.
    • --include-entry-links: Gibt Links zu Einträgen für dbt-Beziehungen aus. Diese Einstellung ist standardmäßig aktiviert. Verwenden Sie --no-include-entry-links, um die Funktion zu deaktivieren. Der Befehl gibt die folgenden Linktypen aus:
      • reference: Eine Ressource hängt von einer anderen ab, beschreibt oder verwendet sie. Dazu gehören dbt-Abhängigkeiten zwischen Knoten, ein Test und die Ressource, die getestet wird, ein semantisches Modell oder ein Messwert und die Ressource, auf der es basiert, ein Knoten und die Projektmakros, die er aufruft, sowie ein Knoten und die BigQuery-Tabelle, in die er materialisiert wird.
      • schema-join: Spalten, die durch einen dbt-relationships-Test deklariert werden und für Joins verwendet werden können.
    • --skip-bigquery-link: reference-Links überspringen (dbt-Knoten → physische BigQuery-Tabelle). Standardmäßig wird für jeden materialisierten dbt-Knoten (Modell, Seed, Snapshot), dessen BigQuery-Dataset sich am Importort (--location) befindet, ein reference-Link ausgegeben. dbt-Quellen erhalten keinen reference-Link zu ihrer BigQuery-Tabelle. Eintragslinks können nur auf @bigquery-Einträge in derselben Region verweisen. Datasets in einer anderen Region werden daher automatisch übersprungen. Um die Region jedes Datasets zu ermitteln, ruft der Befehl die BigQuery API auf. Daher benötigt der Aufrufer die Berechtigung bigquery.datasets.get für diese Datasets. Andernfalls kann der Befehl Datasets in anderen Regionen nicht überspringen und Links zu ihnen können nicht aufgelöst werden. Wenn die BigQuery-Tabellen nicht im Knowledge Catalog katalogisiert sind, verwenden Sie --skip-bigquery-link.
    • --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.
  • dbt-Abhängigkeiten ändern sich, z. B. wenn ein ref()-, source()-, Test- oder Makroaufruf hinzugefügt oder entfernt wird. Bei --aspects-only-Ausführungen werden keine Eintragslinks erstellt oder aktualisiert.
  • Sie ändern --include-entry-links oder --skip-bigquery-link.

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.

Rufen Sie die Methode projects.locations:lookupEntryLinks auf, um die Eintragslinks eines dbt-Eintrags aufzulisten. So rufen Sie beispielsweise die BigQuery-Tabelle ab, in der ein dbt-Modell materialisiert wird:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME ist der vollständige Ressourcenname des dbt-Eintrags. Die Ergebnisse sind paginiert und enthalten maximal 10 Links pro Seite.

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.

Nächste Schritte