Importer des métadonnées depuis dbt Core

Ce document explique comment importer des métadonnées depuis dbt Core et MetricFlow dans Knowledge Catalog (anciennement Dataplex Universal Catalog) à l'aide de la commande gcloud.

L'intégration dbt capture les métadonnées suivantes :

  • Métadonnées techniques : elles incluent les ressources clés (sources, seeds, modèles) et leurs propriétés techniques (noms de colonnes, types de données, nombre de lignes).
  • Métadonnées métier et sémantiques : optimisées par dbt MetricFlow, elles incluent des définitions et une logique métier telles que des modèles sémantiques, des métriques et des requêtes enregistrées.
  • Métadonnées opérationnelles et de qualité des données : elles incluent les métadonnées d'exécution telles que le timing, l'état de réussite ou d'échec, la fraîcheur des données, les tests et les résultats des tests.
  • Métadonnées sur la traçabilité et les relations : elles incluent les graphiques de transformation (DAG) et les dépendances entre les ressources dbt, la traçabilité physique qui suit et relie les blocs de transformation physique, les clés de jointure et les jointures dynamiques, ainsi que les relations parent-enfant.
  • Métadonnées de consommation : elles incluent les métadonnées capturées dans les expositions qui indiquent comment les données sont utilisées en dehors de dbt.

Avant de pouvoir importer des métadonnées depuis dbt Core et MetricFlow, effectuez les tâches suivantes :

  1. Attribuez les rôles et autorisations requis.
  2. Activez l'API Knowledge Catalog.
  3. Remplissez les conditions préalables de dbt.
  4. Créez le groupe d'entrées de destination s'il n'existe pas encore.
  5. Comprendre les rôles Cloud Storage

Rôles et autorisations IAM

Pour créer et gérer un job de connecteur Knowledge Catalog, vous avez besoin de rôles Identity and Access Management (IAM) qui accordent des autorisations pour Knowledge Catalog et Cloud Storage.

Pour obtenir les autorisations nécessaires pour configurer un connecteur dbt, demandez à votre administrateur de vous accorder les rôles IAM suivants :

De plus, vous devez accorder à l'agent de service Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) le rôle Lecteur des objets Storage (roles/storage.objectViewer) sur le bucket Cloud Storage de préproduction de sortie (--storage-uri) afin que le job d'importation puisse lire le fichier de métadonnées de préproduction.

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Activer les API

Activez l'API Knowledge Catalog.

Activer l'API

Conditions préalables dbt

Pour importer l'ensemble complet des métadonnées dbt, nous vous recommandons de générer les quatre fichiers d'artefacts JSON dbt. Seul manifest.json est requis. Les autres enrichissent l'importation et la transformation se dégrade progressivement sans eux :

  • manifest.json (obligatoire) : structure de base du projet et graphique d'exécution. Contient également les modèles sémantiques, les métriques et les requêtes enregistrées MetricFlow.
  • catalog.json : noms et types de données des colonnes. Sans catalog.json, l'aspect du schéma est importé avec des colonnes non typées.
  • run_results.json : résultats des tests et métadonnées d'exécution.
  • sources.json : fraîcheur de la source.

Pour générer l'ensemble complet de fichiers JSON d'artefacts de métadonnées dbt, vous pouvez exécuter les commandes dbt suivantes dans cet ordre :

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

Comprendre les rôles Cloud Storage

L'importation de métadonnées dbt implique deux emplacements Cloud Storage distincts qui servent des objectifs différents et ne doivent pas être confondus :

  • Entrée (artefacts sources dbt) : emplacement de vos fichiers JSON dbt générés. Il peut s'agir d'un chemin d'accès à un répertoire local sur votre ordinateur ou votre runner CI (tel que ./target/ ou .), ou d'un préfixe d'URI de bucket Cloud Storage d'entrée (tel que gs://my-dbt-artifacts-bucket/target/). Vous fournissez ce chemin d'accès à l'aide de l'indicateur --artifacts-path. La commande gcloud lit ces fichiers d'entrée lors de la préparation du job. L'appelant qui exécute la commande gcloud doit disposer d'un accès en lecture (roles/storage.objectViewer ou roles/storage.objectAdmin) s'il utilise Cloud Storage. L'agent de service Knowledge Catalog n'a pas besoin d'accéder au bucket d'artefacts d'entrée.
  • Sortie (bucket de préproduction pour l'importation Knowledge Catalog) : préfixe d'URI de bucket Cloud Storage (tel que gs://my-staging-bucket/dbt-imports/) dans lequel la commande gcloud importe le fichier d'importation de métadonnées transformé (dbt_metadata.jsonl) et à partir duquel le job d'importation Knowledge Catalog lit les données lors de l'ingestion. Vous fournissez cet URI à l'aide de l'option --storage-uri. L'appelant qui exécute la commande gcloud doit disposer d'un accès en écriture (roles/storage.objectCreator ou roles/storage.objectAdmin) pour mettre en ligne le fichier, et l'agent de service du Knowledge Catalog doit disposer d'un accès en lecture (roles/storage.objectViewer) pour l'importer.

Configurer la connectivité dbt

Pour établir la connectivité dbt, vous devez d'abord exécuter les commandes dbt appropriées pour générer les artefacts de métadonnées. Une fois les fichiers JSON stockés et accessibles, le processus d'importation effectue les actions suivantes :

  1. Lire les artefacts d'entrée : lire les artefacts JSON générés par dbt Core et MetricFlow à partir de l'emplacement d'entrée (répertoire local ou URI Cloud Storage spécifié dans --artifacts-path).
  2. Transformer les métadonnées : transformez le contenu au format d'importation des métadonnées Knowledge Catalog (dbt_metadata.jsonl).
  3. Importer dans la zone de préparation : importez le fichier d'importation de métadonnées transformé dans l'emplacement Cloud Storage de préparation des sorties spécifié dans --storage-uri.
  4. Déclencher un job d'importation : déclenchez un job d'importation de métadonnées Knowledge Catalog qui demande à l'agent de service Knowledge Catalog de lire et d'ingérer les métadonnées préparées à partir de --storage-uri dans les ressources Knowledge Catalog.

Console

  1. Dans la console Google Cloud , accédez à la page Connecteurs Knowledge Catalog.

    Accéder à "Connecteurs"

  2. Cliquez sur Ajouter une connexion.

  3. Dans la liste Connecteurs, sélectionnez la fiche dbt Core et MetricFlow.

  4. Pour afficher vos assets dbt importés, accédez à la page Recherche ou à la page Groupes d'entrées de destination.

gcloud

Pour créer un job de métadonnées dbt, procédez comme suit :

  1. Assurez-vous que les fichiers d'artefact de métadonnées dbt sont stockés localement ou dans un bucket Cloud Storage d'entrée.
  2. Assurez-vous d'avoir configuré un bucket Cloud Storage de préproduction de sortie avec les autorisations appropriées pour l'appelant et l'agent de service Knowledge Catalog.

  3. Depuis Cloud Shell, un terminal local ou un outil de workflow automatisé, exécutez la commande gcloud :

    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/

    Indicateurs obligatoires

    • --storage-uri=STORAGE_URI : préfixe d'URI Cloud Storage (sortie/staging) (gs://bucket/path/) où le fichier JSONL transformé est importé et où le job d'importation lit les données lors de l'ingestion. L'appelant doit disposer d'un accès en écriture (roles/storage.objectCreator ou roles/storage.objectAdmin), et l'agent de service Knowledge Catalog doit disposer d'un accès en lecture (roles/storage.objectViewer).

    Flags facultatifs

    • --artifacts-path=ARTIFACTS_PATH : (entrée) chemin d'accès aux artefacts dbt sources. Il peut s'agir d'un chemin d'accès à un répertoire local (tel que . ou ./target) ou d'un préfixe d'URI Cloud Storage (tel que gs://my-bucket/dbt-artifacts/). Il peut pointer vers la racine du projet dbt (le sous-répertoire target/ est détecté automatiquement) ou directement vers le répertoire contenant manifest.json. La valeur par défaut est .. Si un URI Cloud Storage est fourni, l'appelant doit disposer d'un accès en lecture (roles/storage.objectViewer ou roles/storage.objectAdmin) au bucket d'entrée.
    • --async : renvoie immédiatement une réponse, sans attendre la fin de l'opération en cours.
    • --entry-group=ENTRY_GROUP : ID abrégé du groupe d'entrées qui reçoit les entrées dbt. Doit déjà exister dans le projet et l'emplacement (la valeur par défaut est dbt-metadata-ingestion).
    • --aspects-only : ne mettez à jour que les métadonnées observées par cette exécution dbt et laissez le reste du groupe d'entrées intact. Aucune entrée n'est créée, supprimée ni réattribuée, et un aspect dont l'artefact dbt était absent de cette exécution conserve la valeur qui lui avait été attribuée lors d'une exécution précédente. Utilisez cette option pour l'ingestion répétée et de routine. Consultez Réexécuter l'ingestion.
    • --validate-only : créez et importez le fichier JSON, puis validez le job de métadonnées, mais n'ingérez pas les données.

  4. Vérifiez que l'état Créé s'affiche.

REST

Pour importer des métadonnées dbt à l'aide de l'API REST :

  1. Générez les artefacts dbt et transformez-les en fichier d'importation JSON Knowledge Catalog (dbt_metadata.jsonl).
  2. Importez le fichier transformé dans votre bucket de préproduction Cloud Storage (gs://BUCKET_NAME/PATH/).

  3. Appelez la méthode projects.locations.metadataJobs.create :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID du projet Google Cloud dans lequel se trouve votre groupe d'entrées.
    • LOCATION : région de votre groupe d'entrées (par exemple, us-central1).
    • JOB_ID : identifiant unique du job de métadonnées.
    • BUCKET_NAME/PATH : préfixe de l'URI Cloud Storage où dbt_metadata.jsonl a été importé.
    • ENTRY_GROUP : ID abrégé du groupe d'entrées de destination.

  4. Pour suivre l'état de votre job d'importation, utilisez la méthode projects.locations.metadataJobs.get :

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

Une fois le job créé, Knowledge Catalog planifie la première exécution en fonction de votre configuration. Vous pouvez également la démarrer manuellement.

Réexécuter l'ingestion

Après la première importation, la plupart des exécutions n'ont besoin que d'actualiser les métadonnées des ressources qui existent déjà. Utilisez --aspects-only pour ces exécutions. Il ne met à jour que ce que l'exécution dbt a observé et laisse tout le reste du groupe d'entrée intact. Vous pouvez donc l'exécuter plusieurs fois, selon n'importe quel calendrier et à partir de plusieurs tâches.

Exécutez une ingestion complète (omettez --aspects-only) lorsque l'ensemble des entrées change :

  • Première importation dans un groupe d'entrées.
  • Une ressource dbt est ajoutée, renommée ou supprimée.
  • Le nom à afficher, la description ou les libellés d'une entrée ont été modifiés.
  • La hiérarchie des entrées change.

Une exécution complète réécrit les aspects requis de chaque entrée à partir des artefacts sur le disque. Exécutez-la donc à partir d'un ensemble d'artefacts aussi complet que possible pour votre pipeline.

Exécutez --aspects-only pour les actualisations régulières :

  • Après la commande dbt exécutée par votre pipeline : dbt build, dbt test, dbt source freshness ou une reconstruction limitée par --select.
  • Une colonne est ajoutée, supprimée, modifiée ou redécrite.
  • Le code SQL du modèle a été modifié et l'exécution a également écrit catalog.json.
  • Nouveaux résultats de test ou fraîcheur de la source.

--aspects-only peut ajouter et actualiser des métadonnées, mais pas les supprimer.

Rechercher et afficher les métadonnées dbt

Console

  1. Dans la console Google Cloud , accédez à la page Rechercher de Knowledge Catalog.

    Accéder à la recherche

  2. Dans le panneau Filtres, filtrez les composants dbt :

    • Dans la section Système, sélectionnez Contexte importé.
    • Dans la sous-section Connecteurs gérés qui s'affiche, sélectionnez dbt.

  3. Dans le champ de recherche, saisissez votre requête à l'aide de mots clés ou en langage naturel. Par exemple, pour afficher tous les composants dbt à l'aide de la recherche par mot clé, saisissez system=DBT ou system=DBT AND type=dbt-model.

  4. Dans les résultats de recherche, cliquez sur un asset dbt pour ouvrir la page d'informations correspondante et afficher son schéma, sa traçabilité et ses aspects techniques.

gcloud

  1. Pour rechercher des entrées dbt dans votre projet, utilisez la commande gcloud dataplex entries search :

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

    Pour filtrer par type d'entrée dbt spécifique (comme les modèles ou les sources) :

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

  2. Pour afficher tous les détails et aspects d'une entrée dbt spécifique, utilisez la commande gcloud dataplex entries lookup :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • LOCATION : emplacement du groupe d'entrées (par exemple, us-central1).
    • ENTRY_GROUP : ID abrégé de votre groupe d'entrées de destination (par exemple, dbt-metadata-ingestion).
    • ENTRY_ID : ID court ou nom de ressource relatif de l'entrée dbt.

REST

  1. Pour rechercher des entrées dbt, appelez la méthode projects.locations:searchEntries :

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

    Pour filtrer par type de ressource dbt spécifique :

    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. Pour récupérer tous les détails et aspects des métadonnées d'une entrée spécifique, appelez la méthode projects.locations.entryGroups.entries.get :

    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. Pour récupérer le contexte LLM pour des ressources dbt spécifiques, utilisez l'API projects.locations:lookupContext :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • LOCATION : emplacement du groupe d'entrées (par exemple, us-central1).
    • ENTRY_GROUP : ID abrégé de votre groupe d'entrées de destination (par exemple, dbt-metadata-ingestion).
    • ENTRY_ID : ID court ou nom de ressource relatif de l'entrée dbt.

Pour en savoir plus sur la recherche de ressources, consultez Rechercher des ressources dans Knowledge Catalog. Pour en savoir plus sur les expressions de requête et les filtres, consultez la syntaxe de recherche pour Knowledge Catalog.

Limites

  • Compatible avec les versions 1 récentes de dbt Core (validées avec les versions 1.11 et 1.12). dbt Core v2 et dbt Fusion ne sont pas compatibles.
  • Les modèles dbt qui utilisent la gestion des versions de modèle ne sont pas acceptés.
  • dbt Cloud n'est pas compatible.
  • Les schémas très volumineux ou profondément imbriqués sont tronqués : un seul aspect ne peut pas dépasser la limite de taille par aspect. Les schémas profondément imbriqués peuvent donc perdre des champs de fin.
  • --aspects-only peut ajouter et actualiser des métadonnées, mais pas les supprimer. La suppression d'une ressource dbt nécessite une exécution complète.
  • Les liens d'entrée ne sont pas acceptés.
  • Cette intégration n'est compatible qu'avec les événements de lignage dbt sur les ressources BigQuery dans l'API et le graphique Data Lineage. Les entrées dbt (sources, seeds, modèles) pour les sources tierces externes ne sont pas capturées dans le lignage des données.

Étapes suivantes