Seit dem 10. April 2026 heißt Dataplex Universal Catalog jetzt Knowledge Catalog. Die Namen der API, der Clientbibliothek, der CLI und von IAM bleiben unverändert. Weitere Informationen finden Sie unter Google Cloud Knowledge Catalog.

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

Metadaten aus dbt Core importieren

Mit Knowledge Catalog (ehemals Dataplex Universal Catalog) können Sie operative, semantische und Herkunftsmetadaten aus dbt Core, dbt Cloud und MetricFlow importieren. Verwenden Sie dazu die Google Cloud CLI und Ihre dbt-Artefaktdateien. Anstatt Transformationsmetadaten im dbt-Ökosystem zu belassen, können Sie sie zentralisieren, um Data Engineers, Analytics Engineers und Data Stewards bei der Erkennung und Verwaltung von Unternehmensdaten zu unterstützen.

Importierte Metadaten und Anwendungsfälle

Da dbt Core als Transformations-Engine und nicht als Speichersystem wie Oracle oder PostgreSQL fungiert, unterstützt der Import seiner Metadaten verschiedene Anwendungsfälle. Sie importieren Oracle- oder PostgreSQL-Metadaten, um die Frage „Welche Rohdaten haben wir?“ zu beantworten, und Sie importieren 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.

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

Technische Metadaten: Unternehmensdaten durch Erkunden wichtiger Ressourcen (Quellen, Seeds, Modelle) und ihrer technischen Eigenschaften (Spaltennamen, Datentypen, Zeilenanzahl) entdecken.
Geschäfts- und semantische Metadaten: Stellen Kontext für BI-Tools und KI-Agenten bereit, indem sie Geschäftsdefinitionen und ‑logik von dbt MetricFlow untersuchen, z. B. semantische Modelle, Messwerte und gespeicherte Abfragen.
Betriebs- und Datenqualitätsmetadaten: Überwachen Sie den Zustand der Pipeline und beheben Sie Datenprobleme, indem Sie Ausführungsmetadaten wie Zeit, Erfolgs- oder Fehlerstatus, Datenaktualität und Testergebnisse untersuchen.
Herkunfts- und Beziehungsmetadaten: Führen Sie eine nachgelagerte Auswirkungsanalyse und eine Ursachenverfolgung durch, indem Sie Transformationsgraphen (DAGs) und Abhängigkeiten zwischen dbt-Ressourcen, physischer Herkunft, die physische Transformationsblöcke verfolgt und verknüpft, Join-Schlüssel und dynamische Joins sowie Eltern-Kind-Beziehungen untersuchen.
Verbrauchsmetadaten: Beheben Sie Probleme mit der Nutzung transformierter Daten durch nachgelagerte Anwendungen, indem Sie Metadaten untersuchen, die in Exposures erfasst wurden, die die Verwendung von Daten außerhalb von dbt abbilden.

Beschränkungen

Unterstützt dbt Core v1 (validiert mit den Versionen 1.11 und 1.12), dbt Core v2 und dbt Fusion.
Die gcloud CLI ab Version 586.0.0 unterstützt die Integration von dbt und Knowledge Catalog. Informationen zum Installieren oder Aktualisieren der Befehlszeile 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, rufen Sie zuerst die Artefakte des Jobs ab. 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 die Größenbeschränkung pro Aspekt nicht überschreiten, sodass bei tief verschachtelten Schemas möglicherweise nachfolgende Felder verloren gehen.
--aspects-only kann Metadaten hinzufügen und aktualisieren, aber nicht entfernen. Zum Löschen einer dbt-Ressource ist eine vollständige Ausführung erforderlich.
Diese Integration unterstützt nur dbt-Herkunftsereignisse 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 Datenherkunft erfasst.
- Wenn Sie alle dbt-Herkunftsereignisse in die Data Lineage API aufnehmen möchten, verwenden Sie die OpenLineage-dbt-Integration. Anschließend binden Sie OpenLineage in Knowledge Catalog ein, um die Datenherkunft aus dbt zu importieren und zu visualisieren.

Hinweis

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

Weisen Sie die erforderlichen Rollen und Berechtigungen zu.
Aktivieren Sie die Dataplex API.
Erfüllen Sie die Voraussetzungen für dbt.
Erstellen Sie die Zieleintragsgruppe, falls sie noch nicht vorhanden ist.
Informationen zu 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: 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 Jobs für den Metadatenimport: Folgen Sie dem 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, weisen Sie stattdessen die Rolle Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) für das Projekt zu. Gewähren Sie außerdem Dataplex-Eintragsinhaber (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 Eintragslinks 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.
Zum Hochladen transformierter Metadaten in den Ausgabe-Staging-Bucket (--storage-uri): 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.
Zum Aufrufen von dbt-Metadaten: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) für das Projekt.
Zum Aufrufen von Logs in Cloud Logging: 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 Ihrem eigenen Nutzerkonto diese Rollen zuweisen. Führen Sie dazu die folgenden gcloud-Befehle aus:

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-Objekt-Betrachter (roles/storage.objectViewer) für den Cloud Storage-Bucket für das Ausgabe-Staging (--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 Nutzerkontos.
SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse Ihres Dienstkontos.
STAGING_BUCKET: der Name Ihres Cloud Storage-Bucket für das Ausgabe-Staging (--storage-uri).
PROJECT_NUMBER: Ihre Google Cloud Projektnummer

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

APIs aktivieren

Dataplex API aktivieren

API aktivieren

dbt-Voraussetzungen

Wenn Sie den vollständigen Satz von dbt-Metadaten importieren möchten, empfehlen wir, alle vier dbt-JSON-Artefaktdateien zu erstellen. Nur manifest.json ist erforderlich. Die anderen reichern den Import an und die Transformation wird ohne sie ordnungsgemäß herabgestuft:

manifest.json (erforderlich): Zentrale Projektstruktur und Ausführungsgrafik. Enthält auch die semantischen Modelle, Messwerte und gespeicherten Abfragen von MetricFlow.
catalog.json: Spaltennamen und Datentypen. Ohne catalog.json wird der Schemaaspekt mit nicht typisierten Spalten importiert.
run_results.json: Testergebnisse und Ausführungsmetadaten.
sources.json: Aktualität der Quelle.

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

Für dbt Core 2.x und dbt Fusion:
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  Warnung: Verwenden Sie dbt docs generate nicht mit dbt Core 2.x oder dbt Fusion. catalog.json wird nicht geschrieben und run_results.json wird ohne Testergebnisse überschrieben. dbt build --write-catalog schreibt auch keinen Katalog. Verwenden Sie daher einen separaten dbt parse --write-catalog-Schritt.
Für dbt Core 1.x (wobei dbt parse keinen Katalog schreibt):
1. dbt source freshness
2. dbt build
3. dbt docs generate --no-compile
  
  Warnung: Ohne --no-compile überschreibt dbt docs generate run_results.json mit dem Status success für jeden Knoten. Testergebnisse aus den vorherigen dbt build gehen verloren und der Katalog meldet, dass alle Datenqualitätstests bestanden wurden.

Cloud Storage-Rollen

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

Eingabe (dbt-Quellartefakte): Speicherort der 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 den Eingabe-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 Befehl gcloud 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 (Staging-Bucket für den Knowledge Catalog-Import): Ein URI-Präfix für einen Cloud Storage-Bucket (z. B. gs://my-staging-bucket/dbt-imports/), in den der Befehl gcloud die transformierte Metadaten-Importdatei (dbt_metadata.jsonl) hochlädt 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 Befehl gcloud ausführt, benötigt Schreibzugriff (roles/storage.objectCreator oder roles/storage.objectAdmin), um die Datei hochzuladen, und der Knowledge Catalog-Dienst-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 ein dbt Cloud-Job dieselben Artefaktdateien wie dbt Core generiert, 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 so, dass der vollständige Artefaktsatz generiert wird. Anschließend können Sie die Artefaktdateien aus einer dbt Cloud-Jobausführung mit einer der folgenden Methoden abrufen:

Artefakte aus der dbt Cloud Console herunterladen: Laden Sie die Artefaktdateien manuell von der Detailseite der Jobausführung in der dbt Cloud-Benutzeroberfläche herunter, um sie einmalig zu importieren oder erste Tests durchzuführen.
Artefakte mit der dbt-Plattform-CLI herunterladen: Führen Sie dbt-Befehle in dbt Cloud über Ihr lokales Terminal aus, um die generierten Artefakte während der Entwicklung automatisch in Ihrem lokalen Projektverzeichnis zu speichern.
Artefakte mit der dbt Administrative API herunterladen: Artefakte aus abgeschlossenen Ausführungen programmatisch über HTTP für automatisierte, geplante Pipelines abrufen.

dbt Cloud-Job einrichten

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

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.
Fügen Sie im Abschnitt Befehle dbt build hinzu.
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-Release-Tracks: Fügen Sie dbt docs generate --no-compile als Jobbefehl hinzu, anstatt die Option Dokumente bei Ausführung generieren auszuwählen. Wenn das Kästchen Dokumente bei Ausführung generieren aktiviert ist, wird dbt docs generate ohne --no-compile ausgeführt. Dadurch werden die Testergebnisse von dbt build überschrieben, wie unter Voraussetzungen für dbt beschrieben. Wenn ein Befehlsschritt fehlschlägt, schlägt auch der Job fehl. Ein fehlgeschlagener Schritt mit Kästchen führt dagegen nicht dazu, dass der Job fehlschlägt.

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

Weitere Informationen finden Sie in der dbt-Dokumentation unter Jobbefehle und Release-Tracks.

Artefakte aus der dbt Google Cloud -Konsole herunterladen

So laden Sie Artefakte aus einer abgeschlossenen Ausführung in der dbt-Google Cloud -Konsole manuell herunter:

Öffnen Sie in der dbt Google Cloud -Konsole die abgeschlossene Jobausführung.
Rufen Sie den Tab Artefakte auf, um die generierten Artefaktdateien anzusehen.
Laden Sie manifest.json, catalog.json, run_results.json und sources.json in ein lokales Verzeichnis herunter.
Führen Sie in Ihrem lokalen Terminal oder in Cloud Shell den gcloud-Importbefehl aus, der unter dbt-Verbindung konfigurieren beschrieben ist, und legen Sie --artifacts-path auf das Verzeichnis mit den heruntergeladenen Dateien fest.

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

Artefakte über die dbt-Plattform-Befehlszeile herunterladen

Die dbt Platform CLI (früher dbt Cloud CLI) führt dbt-Befehle auf der dbt Cloud-Plattform über Ihr lokales Terminal aus und lädt die generierten Artefakte automatisch in das Verzeichnis target/ Ihres lokalen dbt-Projekts herunter.

Wechseln Sie in Ihrem lokalen Terminal zum Stammverzeichnis Ihres dbt-Projekts und führen Sie die drei Befehle aus, die unter Voraussetzungen für dbt aufgeführt sind.
Führen Sie den Importbefehl gcloud aus, der unter dbt-Konnektivität konfigurieren beschrieben wird, und legen Sie --artifacts-path auf das Projektstammverzeichnis oder das Verzeichnis target/ fest.

Die Befehlszeile wird in Ihrer Entwicklungsumgebung mit Ihren persönlichen Data-Warehouse-Anmeldedaten ausgeführt. Die generierten Metadaten spiegeln daher Ihr Entwicklungsschema wider und nicht die Produktionstabellen, die von einem geplanten Job erstellt wurden. Verwenden Sie die Befehlszeile für Test- oder Entwicklungsworkflows 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 jeder abgeschlossenen Jobausführung programmatisch abrufen. Der Endpunkt List Run Artifacts gibt die von einer Ausführung 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-Diensttoken authentifizieren. Weitere Informationen finden Sie auf den folgenden Seiten der dbt-Dokumentation:

Laden Sie manifest.json, catalog.json, run_results.json und sources.json von Ihrem lokalen Terminal, Cloud Shell oder Ihrer automatisierten Workflow-Umgebung in ein lokales Verzeichnis oder einen Cloud Storage-Bucket herunter und führen Sie dann den Befehl gcloud aus, der unter dbt-Konnektivität konfigurieren für diesen Pfad beschrieben wird.

Standardmäßig gibt der Artefakt-Endpunkt Artefakte aus dem letzten Schritt der Ausführung zurück, es sei denn, Sie geben den Suchparameter step an. 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. Dadurch wird nur catalog.json geschrieben und die anderen drei Artefakte bleiben im Standardschritt intakt.

Ausführungs-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 -Konsole 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 filtert status=10 nach abgeschlossenen Ausführungen mit dem Status Success. Sie können diesen Endpunkt nach einem Zeitplan abfragen, um die letzte erfolgreiche Ausführung zu ermitteln, die Artefakte herunterzuladen und den Importbefehl gcloud 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 eine Jobausführung abgeschlossen ist. Der Webhook sendet eine Nutzlast an einen von Ihnen angegebenen HTTP-Endpunkt:

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 Ausführung abgeschlossen (job.run.completed) aus. Dadurch wird die Ausführung erst ausgelöst, wenn sie abgeschlossen ist und die Artefakte zum Download 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).
Speichern Sie das von dbt Cloud angezeigte Webhook-Secret-Token. Ihr Dienst verwendet dieses Secret, um den Authorization-Header zu prüfen, der eine HMAC-SHA256-Signatur des Anfragetexts enthält.
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 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 einige 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 Ausführungen ausgelöst, sodass Ausführungen mit fehlgeschlagenen Tests weiterhin importiert werden. Abonnieren Sie job.run.errored nicht, da es ausgelöst werden kann, bevor die Artefakte der Ausführung verfügbar sind.

Weitere Informationen zu Webhook-Nutzlasten und zur Signaturprüfung finden Sie in der dbt-Dokumentation unter Webhooks für Ihre Jobs.

dbt-Verbindung konfigurieren

Wenn Sie eine dbt-Verbindung herstellen möchten, müssen Sie zuerst die entsprechenden dbt-Befehle ausführen, um die Metadatenartefakte zu generieren. Sobald die JSON-Dateien gespeichert und zugänglich sind, führt der Importvorgang die folgenden Aktionen aus:

Eingabeartefakte lesen: Die von dbt Core und MetricFlow generierten JSON-Artefakte werden aus dem Eingabespeicherort (lokales Verzeichnis oder Cloud Storage-URI, der in --artifacts-path angegeben ist) gelesen.
Metadaten transformieren: Transformieren Sie den Inhalt in das Metadatenimportformat von Knowledge Catalog (dbt_metadata.jsonl).
In Staging hochladen: Laden Sie die transformierte Metadaten-Importdatei in den Cloud Storage-Staging-Speicherort für die Ausgabe hoch, der in --storage-uri angegeben ist.
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

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

Zu „Connectors“
Klicken Sie auf Verbindung hinzufügen.
Wählen Sie in der Liste Connectors die Karte dbt Core und MetricFlow aus.

Hinweis: Da für die Aufnahme von dbt Core-Metadaten clientseitige dbt-Artefakt-JSON-Dateien (manifest.json, catalog.json, run_results.json, sources.json) vor der Aufnahme in das Knowledge Catalog-Importformat umgewandelt werden müssen, werden Sie durch Auswahl dieser Karte zur Anleitung für die Befehlszeile oder API weitergeleitet.
Wenn Sie Ihre importierten dbt-Assets ansehen möchten, rufen Sie die Seite Suchen oder die Seite Eintragsgruppen für das Ziel auf.

gcloud

So erstellen Sie einen dbt-Metadatenjob:

Die dbt-Metadatenartefaktdateien müssen lokal oder in einem Cloud Storage-Eingabe-Bucket gespeichert sein.
Sie benötigen einen Cloud Storage-Bucket für das Ausgabe-Staging, der mit den entsprechenden Berechtigungen für den Aufrufer und den Knowledge Catalog-Dienst-Agent konfiguriert ist.
Führen Sie in Cloud Shell, einem lokalen Terminal oder einem automatisierten Workflow-Tool den Befehl gcloud aus:
```
gcloud 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 dbt-Projektstammverzeichnis (das Unterverzeichnis target/ wird automatisch erkannt) oder direkt auf das Verzeichnis mit manifest.json verweisen. Die Standardeinstellung ist .. Wenn ein Cloud Storage-URI angegeben ist, muss der Aufrufer Lesezugriff (roles/storage.objectViewer oder roles/storage.objectAdmin) auf den Eingabe-Bucket haben.
- --async: Sofort zurückkehren, ohne auf den Abschluss des laufenden Vorgangs zu warten.
- --entry-group=ENTRY_GROUP: Kurze ID der Eintraggruppe, 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 dieser dbt-Ausführung beobachtet wurden, und den Rest der Eintraggruppe unverändert lassen. Es wird kein Eintrag erstellt, gelöscht oder neu übergeordnet, es wird kein Eintragslink ausgegeben und ein Aspekt, dessen dbt-Artefakt in dieser Ausführung nicht vorhanden war, behält den Wert, den er in einer vorherigen Ausführung erhalten hat. 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 Eintragslinks für dbt-Beziehungen aus. Diese Einstellung ist standardmäßig aktiviert. Verwenden Sie --no-include-entry-links, um sie zu deaktivieren. Der Befehl gibt die folgenden Eintrag-Linktypen aus:
  - reference: Eine Ressource hängt von einer anderen ab, beschreibt sie oder verwendet sie. Dazu gehören dbt-Abhängigkeiten zwischen Knoten, ein Test und die Ressource, die er testet, ein semantisches Modell oder ein Messwert und die Ressource, auf der er basiert, ein Knoten und die Projektmakros, die er aufruft, sowie ein Knoten und die BigQuery-Tabelle, in der er materialisiert wird.
  - schema-join: verknüpfbare Spalten, die von einem dbt-relationships-Test deklariert wurden.
- --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 bestimmen, ruft der Befehl die BigQuery API auf. Der Aufrufer benötigt daher die Berechtigung bigquery.datasets.get für diese Datasets. Ohne diese Berechtigung kann der Befehl Datasets in anderen Regionen nicht überspringen und Links zu ihnen werden nicht aufgelöst. Wenn die BigQuery-Tabellen nicht in Knowledge Catalog katalogisiert sind, verwenden Sie --skip-bigquery-link.
- --validate-only: Erstellt und lädt die JSON-Datei hoch und validiert den Metadatenjob, nimmt aber keine Daten auf.
Prüfen Sie, ob Sie den Status Erstellt erhalten haben.

REST

So importieren Sie dbt-Metadaten mit der REST API:

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

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, in der sich Ihre Eintraggruppe befindet.
LOCATION: die Region Ihrer Eintraggruppe (z. B. us-central1).
JOB_ID: Eine eindeutige Kennung für den Metadatenjob.
BUCKET_NAME/PATH: das Cloud Storage-URI-Präfix, unter dem dbt_metadata.jsonl hochgeladen wurde.
ENTRY_GROUP: die Kurz-ID der Ziel-Eintragsgruppe.

Mit der Methode projects.locations.metadataJobs.get können Sie den Status Ihres Importjobs 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 gemäß Ihrer Konfiguration. Sie können sie aber auch manuell starten.

Aufnahme noch einmal ausführen

Nach dem ersten Import müssen bei den meisten Ausführungen nur Metadaten für bereits vorhandene Ressourcen aktualisiert werden. Verwenden Sie für diese Ausführungen --aspects-only. Es werden nur die Daten aktualisiert, die bei der dbt-Ausführung beobachtet wurden. Alle anderen Daten in der Eintraggruppe bleiben unverändert. Daher kann es sicher wiederholt, nach einem beliebigen Zeitplan und von mehr als einem Job ausgeführt werden.

Führen Sie eine vollständige Aufnahme aus (lassen Sie --aspects-only weg), wenn sich die Einträge ändern:

Die erste Aufnahme in eine Eintragungsgruppe.
Eine dbt-Ressource wird hinzugefügt, umbenannt oder gelöscht.
Der Anzeigename, die Beschreibung oder die Labels eines Eintrags ändern sich.
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. --aspects-only-Ausführungen erstellen oder aktualisieren keine Eintragslinks.
Sie ändern --include-entry-links oder --skip-bigquery-link.

Bei einer vollständigen Ausführung werden die erforderlichen Aspekte jedes Eintrags aus den Artefakten auf dem Laufwerk neu geschrieben. Führen Sie sie daher mit einem möglichst vollständigen Artefaktsatz aus, den Ihre Pipeline erzeugen kann.

Führen Sie --aspects-only für routinemäßige Aktualisierungen aus:

Nach dem dbt-Befehl, den Ihre Pipeline ausführt: dbt build, dbt test, dbt source freshness oder eine mit --select eingeschränkte Neuerstellung.
Eine Spalte wird hinzugefügt, entfernt, neu typisiert oder neu beschrieben.
Der SQL-Code des Modells 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

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

Zur Suche
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 angezeigten Unterabschnitt Verwaltete Connectors die Option dbt aus.
Geben Sie Ihre Suchanfrage 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.
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

Verwenden Sie den Befehl gcloud dataplex entries search, um in Ihrem 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
```
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 Standort der Eintragsgruppe (z. B. us-central1).
- ENTRY_GROUP: die Kurz-ID Ihrer Ziel-Eintragsgruppe (z. B. dbt-metadata-ingestion).
- ENTRY_ID: die Kurz-ID oder der relative Ressourcenname des dbt-Eintrags.

REST

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

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

Verwenden Sie die projects.locations:lookupContext API, um 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 Standort der Eintragsgruppe (z. B. us-central1).
ENTRY_GROUP: die Kurz-ID Ihrer Ziel-Eintragsgruppe (z. B. dbt-metadata-ingestion).
ENTRY_ID: die Kurz-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 die 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, mit maximal 10 Links pro Seite.

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

Nächste Schritte

Connector-Jobs verwalten

Metadaten aus dbt Core importieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Importierte Metadaten und Anwendungsfälle

Beschränkungen

Hinweis

IAM-Rollen und -Berechtigungen

APIs aktivieren

dbt-Voraussetzungen

Cloud Storage-Rollen

Metadaten aus dbt Cloud-Ausführungen importieren

dbt Cloud-Job einrichten

Artefakte aus der dbt Google Cloud -Konsole herunterladen

Artefakte über die dbt-Plattform-Befehlszeile herunterladen

Artefakte mit der dbt Administrative API herunterladen

Ausführungs-ID abrufen

Import über einen Webhook auslösen

dbt-Verbindung konfigurieren

Console

gcloud

Erforderliche Flags

Optionale Flags

REST

Aufnahme noch einmal ausführen

dbt-Metadaten suchen und ansehen

Console

gcloud

REST

Nächste Schritte

Metadaten aus dbt Core importieren