Metadaten aus dbt Core importieren

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

Die folgenden Metadaten werden von der dbt-Integration erfasst:

  • Technische Metadaten: Dazu gehören wichtige Ressourcen (Quellen, Seeds, Modelle) und ihre technischen Eigenschaften (Spaltennamen, Datentypen, Zeilen anzahl).
  • Geschäftliche und semantische Metadaten: Diese werden von dbt MetricFlow bereitgestellt und umfassen geschäftliche Definitionen und Logik wie semantische Modelle, Messwerte, und gespeicherte Abfragen.
  • Betriebliche Metadaten und Metadaten zur Datenqualität: Dazu gehören Ausführungs metadaten wie Timing, Status (Erfolg oder Fehler), Datenaktualität, Tests und Testergebnisse.
  • Metadaten zu Herkunft und Beziehungen: Dazu gehören Transformations diagramme (DAGs) und Abhängigkeiten zwischen dbt-Ressourcen, physische Herkunft, die physische Transformationsblöcke verfolgt und verknüpft, Join-Schlüssel und dynamische Joins sowie Beziehungen zwischen über- und untergeordneten Elementen.
  • Nutzungsmetadaten: Dazu gehören Metadaten, die in Exposures erfasst werden und beschreiben, 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. Erteilen Sie die erforderlichen Rollen und Berechtigungen.
  2. Aktivieren Sie die Knowledge Catalog API.
  3. Erfüllen Sie die dbt Voraussetzungen.
  4. Erstellen Sie die Ziel-Eintragsgruppe falls sie noch nicht vorhanden ist.
  5. Machen Sie sich mit den Cloud Storage-Rollen vertraut.

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 zur Konfiguration eines dbt-Connectors benötigen:

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

  • Zum Ausführen des gcloud-Befehls von dbt und zum Erstellen von Metadatenimportjobs: Um das Prinzip der geringsten Berechtigung zu befolgen, weisen Sie die folgenden Rollen zu:

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

  • Zum Hochladen transformierter Metadaten in den Staging-Bucket für die Ausgabe (--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-Bucket für die Eingabe (--artifacts-path, wenn Cloud Storage verwendet wird): Storage-Objekt-Betrachter (roles/storage.objectViewer) oder Storage-Objekt-Administrator (roles/storage.objectAdmin) für den Bucket für Eingabeartefakte. 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: Logs-Betrachter (roles/logging.viewer) für das Projekt.

Außerdem müssen Sie dem Knowledge Catalog-Dienstkonto (service-PROJECT_NUMBER@gcp-sa-dataplex.) die Rolle „Storage-Objekt-Betrachter“ (roles/storage.objectViewer) für den Cloud Storage-Staging-Bucket für die 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 Dateien erweitern den Import und die Transformation wird ohne sie ordnungsgemäß ausgeführt:

  • manifest.json (erforderlich): Kernprojektstruktur und Ausführungsdiagramm. 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: Quellenaktualität.

Wenn Sie alle 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 werden zwei verschiedene Cloud Storage-Speicherorte verwendet, die unterschiedliche Zwecke erfüllen und nicht verwechselt werden sollten:

  • Eingabe (dbt-Quellartefakte): Hier befinden sich die generierten dbt-JSON-Dateien. Dies kann ein lokaler Verzeichnispfad auf Ihrem Computer oder CI-Runner sein (z. B. ./target/ oder .) oder ein URI-Präfix für einen Cloud Storage-Bucket für die Eingabe (z. B. gs://my-dbt-artifacts-bucket/target/). Sie geben diesen Pfad mit dem Flag --artifacts-path an. Der gcloud-Befehl liest diese Eingabedateien während der Jobvorbereitung. Der Aufrufer, der den gcloud-Befehl ausführt, benötigt Lesezugriff (roles/storage.objectViewer oder roles/storage.objectAdmin), wenn Cloud Storage verwendet wird. Das Knowledge Catalog-Dienstkonto benötigt keinen Zugriff auf den Bucket für Eingabeartefakte.
  • Ausgabe (Knowledge Catalog-Staging-Bucket für den Import): Ein URI Präfix für einen Cloud Storage-Bucket (z. B. gs://my-staging-bucket/dbt-imports/), in den der gcloud Befehl die transformierte Metadatenimportdatei (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 gcloud-Befehl ausführt, benötigt Schreibzugriff (roles/storage.objectCreator oder roles/storage.objectAdmin), um die Datei hochzuladen, und das Knowledge Catalog-Dienstkonto 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, können Sie mit dem Befehl gcloud alpha dataplex dbt metadata-jobs create Folgendes tun:

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

So erstellen Sie einen dbt-Metadatenjob:

  1. Achten Sie darauf, dass die dbt-Metadatenartefaktdateien lokal oder in einem Cloud Storage-Bucket für die Eingabe gespeichert sind.
  2. Achten Sie darauf, dass ein Cloud Storage-Staging-Bucket für die Ausgabe mit den entsprechenden Berechtigungen für den Aufrufer und das Knowledge Catalog-Dienstkonto konfiguriert ist.

  3. Führen Sie den gcloud-Befehl über Cloud Shell, ein lokales Terminal oder ein automatisiertes Workflowtool 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 sein (z. B. gs://my-bucket/dbt-artifacts/). Er kann auf das Stammverzeichnis des dbt-Projekts verweisen (das target/ Unterverzeichnis wird automatisch erkannt) oder direkt auf das Verzeichnis mit manifest.json. 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: Gibt die Steuerung sofort zurück, ohne auf den Abschluss des Vorgangs zu warten.
    • --entry-group=ENTRY_GROUP: Kurze ID der Eintragsgruppe, die die dbt-Einträge erhält. Muss bereits im Projekt und am Standort vorhanden sein (Standardeinstellung ist dbt-metadata-ingestion).
    • --aspects-only: Aktualisiert nur die Metadaten, die bei dieser dbt-Ausführung beobachtet wurden, und lässt den Rest der Eintragsgruppe unverändert. Es werden keine Einträge erstellt, gelöscht oder neu übergeordnet und ein Aspekt, dessen dbt-Artefakt bei dieser Ausführung nicht vorhanden war, behält den Wert, der ihm bei einer vorherigen Ausführung zugewiesen wurde. Verwenden Sie diese Option für die routinemäßige, wiederholte Aufnahme. Weitere Informationen finden Sie unter Aufnahme wiederholen.
    • --validate-only: Erstellt und lädt die JSON-Datei hoch und validiert den Metadatenjob, nimmt aber keine Daten auf.

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

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

Aufnahme wiederholen

Nach dem ersten Import müssen bei den meisten Ausführungen nur die 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, und alles andere in der Eintragsgruppe bleibt unverändert. Daher kann es wiederholt, nach einem beliebigen Zeitplan und von mehreren Jobs aus ausgeführt werden.

Führen Sie eine vollständige Aufnahme aus (lassen Sie --aspects-only weg), 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 Eintragsstruktur ändert sich.

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 einer möglichst vollständigen Artefaktmenge aus, die Ihre Pipeline erstellen kann.

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

  • Nach dem dbt-Befehl, der von Ihrer Pipeline ausgeführt wird: 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 bei der Ausführung wurde auch catalog.json geschrieben.
  • Neue Testergebnisse oder Quellenaktualität.

Mit --aspects-only können Metadaten hinzugefügt und aktualisiert, aber nicht entfernt werden.

dbt-Metadaten suchen und ansehen

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

    Zur Suche

  2. Im Bereich Filters (Filter) können Sie nach dbt-Assets filtern. Verwenden Sie dazu die Project (Projekt), System und Type aliases (Typaliase). Wählen Sie im Bereich System die Option Imported Context (Importierter Kontext) aus. Wenn Sie diesen Filter auswählen, wird der Unterbereich Managed Connectors (Verwaltete Connectors) geöffnet. Wählen Sie dbt aus, um nach allen dbt-Metadaten zu filtern.

  3. Sie können das Suchfeld verwenden, um Suchanfragen auszuführen. Sie können eine Suche nach Keywords oder in natürlicher Sprache durchführen. Wenn Sie beispielsweise alle dbt-Assets über die Suche nach Keywords aufrufen möchten, geben Sie system=DBT ein.

    Weitere Informationen zum Suchen nach Ressourcen finden Sie unter Ressourcen in Knowledge Catalog suchen. Weitere Informationen zu den Ausdrücken, die Sie im Suchfeld verwenden können, finden Sie unter Suchsyntax für Knowledge Catalog.

  4. Sie können auch die LookupContext API verwenden, um LLM-Kontext für bestimmte dbt-Ressourcen abzurufen.

Beschränkungen

  • Unterstützt aktuelle dbt Core-Versionen 1 (getestet mit den Versionen 1.11 und 1.12). dbt Core 2 und dbt Fusion werden nicht unterstützt.
  • dbt-Modelle, die die Modellversionierung verwenden, werden nicht unterstützt.
  • dbt Cloud wird nicht unterstützt.
  • Sehr große oder tief verschachtelte Schemas werden abgeschnitten: Ein einzelner Aspekt darf die Größenbeschränkung pro Aspekt nicht überschreiten. Daher können bei tief verschachtelten Schemas nachfolgende Felder verloren gehen.
  • Mit --aspects-only können Metadaten hinzugefügt und aktualisiert, aber nicht entfernt werden. Zum Löschen einer dbt-Ressource ist eine vollständige Ausführung erforderlich.
  • Eintragslinks werden nicht unterstützt.
  • Diese Integration unterstützt nur dbt-Herkunftsereignisse 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 Datenherkunft erfasst.

Nächste Schritte