Importer des métadonnées depuis dbt Core

Pour les ingénieurs de données, les ingénieurs analytiques et les intendants des données, la centralisation des métadonnées est essentielle pour la découverte et la gouvernance des données d'entreprise. Lorsque les équipes utilisent dbt pour la transformation des données, des métadonnées opérationnelles, sémantiques et de traçabilité précieuses sont générées, mais restent souvent cloisonnées dans l'écosystème dbt.

Pour intégrer ces informations à votre catalogue centralisé, vous pouvez importer des métadonnées depuis dbt Core, dbt Cloud et MetricFlow vers Knowledge Catalog (anciennement Dataplex Universal Catalog).

Comme dbt Core fonctionne comme un moteur de transformation plutôt que comme un système de stockage tel qu'Oracle ou PostgreSQL, l'importation de ses métadonnées permet différents cas d'utilisation. Vous importez des métadonnées Oracle ou PostgreSQL pour répondre à la question "Quelles sont nos données brutes ?", et vous importez des métadonnées dbt Core pour répondre à la question "Comment nos données sont-elles transformées, sont-elles fiables et que signifient-elles pour l'entreprise ?".

Ce document explique comment importer des métadonnées à l'aide de la commande Google Cloud CLI et de vos fichiers d'artefacts dbt.

Lorsque vous exécutez l'intégration dbt, vous capturez les métadonnées suivantes :

  • Métadonnées techniques : découvrez les données d'entreprise en explorant 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 : fournissez du contexte aux outils de BI et aux agents d'IA en explorant les définitions et la logique métier fournies par dbt MetricFlow, comme les modèles sémantiques, les métriques et les requêtes enregistrées.
  • Métadonnées opérationnelles et de qualité des données : surveillez l'état du pipeline et résolvez les problèmes de données en explorant 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 et les résultats des tests.
  • Métadonnées sur la traçabilité et les relations : permettez l'analyse de l'impact en aval et le traçage de la cause première en explorant 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 : résolvez les problèmes liés à la façon dont les applications en aval consomment les données transformées en explorant les métadonnées capturées dans les expositions qui mappent la façon dont les données sont utilisées en dehors de dbt.

Limites

  • Compatible avec dbt Core v1 (validé avec les versions 1.11 et 1.12), dbt Core v2 et dbt Fusion.
  • gcloud CLI version 586.0.0 et ultérieure est compatible avec l'intégration dbt et BigQuery. Pour installer ou mettre à jour la CLI, consultez Installer la Google Cloud CLI.
  • Il n'y a pas de connexion directe à dbt Cloud. Pour importer des métadonnées à partir d'un job dbt Cloud, commencez par obtenir les artefacts du job. Consultez Importer des métadonnées à partir d'exécutions dbt Cloud.
  • 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.
  • Cette intégration n'est compatible qu'avec les événements de lineage 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 lineage des données.

Avant de commencer

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 :

Si vous disposez des autorisations nécessaires pour gérer l'accès IAM dans votre projet, vous pouvez accorder ces rôles à votre propre compte utilisateur en exécutant les commandes gcloud suivantes :

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"

Si vous exécutez l'importation à l'aide d'un compte de service, par exemple dans un pipeline CI/CD automatisé, vous pouvez attribuer ces rôles au compte de service en exécutant les commandes gcloud suivantes :

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"

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 des résultats (--storage-uri) afin que le job d'importation puisse lire le fichier de métadonnées préparé :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • USER_EMAIL : adresse e-mail de votre compte utilisateur.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail de votre compte de service.
  • STAGING_BUCKET : nom de votre bucket Cloud Storage de préparation des sorties (--storage-uri).
  • PROJECT_NUMBER : numéro de votre projet Google Cloud .

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.

Dans votre terminal local, Cloud Shell ou environnement CI/CD automatisé où dbt est installé, accédez au répertoire racine du projet dbt et exécutez les commandes dbt suivantes dans l'ordre par rapport à un seul profil et une seule cible pour générer l'ensemble complet de fichiers JSON d'artefacts de métadonnées dbt :

  • Pour dbt Core 2.x et dbt Fusion :

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • Pour dbt Core 1.x (où dbt parse n'écrit pas de catalogue) :

    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.

Importer des métadonnées à partir des exécutions dbt Cloud

Knowledge Catalog ne se connecte pas directement à dbt Cloud. Étant donné qu'un job dbt Cloud génère les mêmes fichiers d'artefacts que dbt Core, vous pouvez importer des métadonnées depuis dbt Cloud en récupérant ces fichiers d'artefacts dans un répertoire local ou un bucket Cloud Storage d'entrée, puis en exécutant la commande gcloud.

Avant de récupérer les artefacts, configurez le job dbt Cloud pour générer l'ensemble complet d'artefacts. Vous pouvez ensuite récupérer les fichiers d'artefact à partir d'une exécution de job dbt Cloud à l'aide de l'une des méthodes suivantes :

Configurer le job dbt Cloud

Dans la console dbt Google Cloud , configurez les paramètres de votre job pour générer l'ensemble complet d'artefacts de métadonnées :

  1. Dans la section Paramètres d'exécution, sélectionnez Exécuter la fraîcheur de la source. dbt Cloud exécute dbt source freshness avant les commandes du job pour générer sources.json.
  2. Dans la section Commandes, ajoutez dbt build.
  3. Ajoutez une commande pour générer catalog.json en fonction de votre canal de publication :
    • Pour les versions dbt Core 2.x et dbt Fusion : ajoutez dbt parse --write-catalog en tant que commande de job.
    • Pour les versions 1.x de dbt Core : ajoutez dbt docs generate --no-compile en tant que commande de job au lieu de sélectionner l'option Générer des documents lors de l'exécution. La case à cocher Generate docs on run (Générer des documents lors de l'exécution) exécute dbt docs generate sans --no-compile, ce qui écrase les résultats des tests de dbt build, comme décrit dans les conditions préalables de dbt. Notez que si une étape de commande échoue, le job échoue également, alors que l'étape de case à cocher n'entraîne pas l'échec du job.

Si dbt build échoue, par exemple en raison d'un test qui échoue, dbt Cloud ignore les commandes qui suivent et l'exécution n'a pas de catalog.json. Pour toujours en produire un, ajoutez la commande de catalogue avant dbt build. Le catalogue décrit ensuite les tables telles qu'elles étaient avant la compilation.

Pour en savoir plus, consultez Commandes de job et Canaux de publication dans la documentation dbt.

Télécharger des artefacts depuis la console dbt Google Cloud

Pour télécharger manuellement les artefacts d'une exécution terminée dans la console dbtGoogle Cloud  :

  1. Dans la console dbt Google Cloud , ouvrez l'exécution du job terminé.
  2. Accédez à l'onglet Artefacts pour afficher les fichiers d'artefact générés.
  3. Téléchargez manifest.json, catalog.json, run_results.json et sources.json dans un répertoire local.
  4. Dans votre terminal local ou Cloud Shell, exécutez la commande d'importation gcloud décrite dans Configurer la connectivité dbt et définissez --artifacts-path sur le répertoire contenant les fichiers téléchargés.

Pour en savoir plus, consultez Visibilité des exécutions dans la documentation dbt.

Télécharger des artefacts à l'aide de la CLI de la plate-forme dbt

La CLI de la plate-forme dbt (anciennement la CLI dbt Cloud) exécute les commandes dbt sur la plate-forme dbt Cloud à partir de votre terminal local et télécharge automatiquement les artefacts générés dans le répertoire target/ de votre projet dbt local.

  1. Dans votre terminal local, accédez au répertoire racine de votre projet dbt et exécutez les trois commandes listées dans Conditions requises pour dbt.
  2. Exécutez la commande d'importation gcloud décrite dans Configurer la connectivité dbt et définissez --artifacts-path sur la racine du projet ou le répertoire target/.

La CLI s'exécute dans votre environnement de développement à l'aide de vos identifiants personnels pour l'entrepôt de données. Par conséquent, les métadonnées générées reflètent votre schéma de développement plutôt que les tables de production créées par un job planifié. Utilisez la CLI pour les workflows de test ou de développement, et un job de déploiement pour les importations de production planifiées.

Pour en savoir plus, consultez Installer la CLI de la plate-forme dbt dans la documentation dbt.

Télécharger des artefacts à l'aide de l'API d'administration dbt

Vous pouvez utiliser l'API d'administration dbt pour récupérer de manière programmatique des artefacts à partir de n'importe quelle exécution de job terminée. Le point de terminaison List Run Artifacts renvoie les chemins d'accès aux fichiers générés par une exécution, et le point de terminaison Retrieve Run Artifact télécharge un fichier d'artefact spécifique à partir de l'URL suivante :

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

ACCESS_URL dépend de la région qui héberge votre compte dbt Cloud. Authentifiez les requêtes à l'aide d'un jeton de service dbt Cloud. Pour en savoir plus, consultez les pages suivantes de la documentation dbt :

À partir de votre terminal local, de Cloud Shell ou de votre environnement de workflow automatisé, téléchargez manifest.json, catalog.json, run_results.json et sources.json dans un répertoire local ou un bucket Cloud Storage, puis exécutez la commande gcloud décrite dans Configurer la connectivité dbt par rapport à ce chemin d'accès.

Par défaut, le point de terminaison des artefacts renvoie les artefacts de la dernière étape de l'exécution, sauf si vous spécifiez le paramètre de requête step. Lorsque vous configurez le job comme décrit dans Configurer le job dbt Cloud, la dernière étape est dbt parse --write-catalog ou dbt docs generate --no-compile, qui n'écrit que catalog.json et laisse les trois autres artefacts intacts à l'étape par défaut.

Récupérer l'ID d'exécution

Pour télécharger les artefacts d'une exécution spécifique, vous avez besoin de son ID d'exécution. Vous pouvez copier l'ID d'exécution à partir de l'URL d'exécution dans la console dbt Google Cloud , ou interroger l'API à partir de votre terminal ou de votre script de workflow pour obtenir la dernière exécution réussie d'un job :

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

Dans les paramètres de requête, status=10 filtre les exécutions terminées avec un état Success. Vous pouvez interroger ce point de terminaison selon une planification pour identifier la dernière exécution réussie, télécharger ses artefacts et exécuter la commande d'importation gcloud.

Déclencher l'importation à l'aide d'un webhook

Au lieu d'interroger l'API, vous pouvez configurer un webhook dbt Cloud pour déclencher une importation automatique de métadonnées chaque fois qu'une exécution de job se termine. Le webhook envoie une charge utile à un point de terminaison HTTP que vous fournissez :

  1. Dans la console dbt Google Cloud , accédez à Account settings > Webhooks, puis cliquez sur Create webhook (ou Create new webhook). Configurez l'abonnement au webhook :
    • Événements : sélectionnez Exécution terminée (job.run.completed), qui ne se déclenche qu'une fois l'exécution terminée et ses artefacts disponibles au téléchargement.
    • Jobs : sélectionnez les jobs de déploiement dbt Cloud que vous souhaitez surveiller.
    • Point de terminaison : saisissez l'URL HTTPS d'un service que vous exécutez (par exemple, un service Cloud Run ou une fonction Cloud Run).
  2. Enregistrez le jeton secret du webhook affiché par dbt Cloud. Votre service utilise ce secret pour vérifier l'en-tête Authorization, qui contient une signature HMAC-SHA256 du corps de la requête.
  3. Dans votre service, lisez data.runId à partir de la charge utile JSON, téléchargez les artefacts de l'exécution à l'aide de l'API Administrative comme décrit précédemment, puis exécutez la commande gcloud alpha dataplex dbt metadata-jobs create.

Lorsque vous implémentez votre gestionnaire de webhook, tenez compte des points suivants :

  • dbt Cloud attend une réponse pendant 10 secondes maximum. Étant donné que l'importation des métadonnées prend plusieurs minutes, renvoyez d'abord une réponse HTTP et exécutez l'importation en arrière-plan (par exemple, en tant que job Cloud Run ou avec l'indicateur --async).
  • job.run.completed se déclenche également pour les exécutions ayant échoué. Les exécutions avec des tests ayant échoué sont donc toujours importées. Ne vous abonnez pas à job.run.errored, car il peut se déclencher avant que les artefacts de l'exécution ne soient disponibles.

Pour en savoir plus sur les charges utiles de webhook et la validation des signatures, consultez Webhooks for your jobs (Webhooks pour vos jobs) dans la documentation dbt.

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 à un parent, aucun lien d'entrée n'est émis et un aspect dont l'artefact dbt était absent de cette exécution conserve la valeur que lui avait attribuée une exécution précédente. Utilisez cette option pour l'ingestion de routine et répétée. Consultez Réexécuter l'ingestion.
    • --include-entry-links : émet des liens d'entrée pour les relations dbt. Cette option est activée par défaut. Pour le désactiver, utilisez --no-include-entry-links. La commande émet les types de liens d'entrée suivants :
      • reference : une ressource dépend d'une autre, la décrit ou l'utilise. Cela inclut les dépendances dbt entre les nœuds, un test et la ressource qu'il teste, un modèle sémantique ou une métrique et la ressource sur laquelle il est basé, un nœud et les macros de projet qu'il appelle, ainsi qu'un nœud et la table BigQuery dans laquelle il se matérialise.
      • schema-join : colonnes pouvant être jointes déclarées par un test relationships dbt.
    • --skip-bigquery-link : ignorer les liens reference (nœud dbt → table BigQuery physique). Par défaut, un lien reference est émis pour chaque nœud dbt matérialisé (modèle, seed, snapshot) dont l'ensemble de données BigQuery se trouve dans l'emplacement d'importation (--location). Les sources dbt ne reçoivent pas de lien reference vers leur table BigQuery. Les liens d'entrée ne peuvent faire référence qu'à des entrées @bigquery dans la même région. Les ensembles de données d'une autre région sont donc automatiquement ignorés. Pour déterminer la région de chaque ensemble de données, la commande appelle l'API BigQuery. L'appelant a donc besoin de l'autorisation bigquery.datasets.get sur ces ensembles de données. Sans cette autorisation, la commande ne peut pas ignorer les ensembles de données dans d'autres régions et les liens vers ceux-ci ne sont pas résolus. Lorsque les tables BigQuery ne sont pas cataloguées dans Knowledge Catalog, utilisez --skip-bigquery-link.
    • --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.
  • Les dépendances dbt changent, par exemple lorsqu'un appel ref(), source(), de test ou de macro est ajouté ou supprimé. Les exécutions --aspects-only ne créent ni ne mettent à jour les liens d'entrée.
  • Vous modifiez --include-entry-links ou --skip-bigquery-link.

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 lister les liens d'entrée d'une entrée dbt, appelez la méthode projects.locations:lookupEntryLinks. Par exemple, pour récupérer la table BigQuery dans laquelle un modèle dbt est matérialisé :

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 correspond au nom complet de la ressource de l'entrée dbt. Les résultats sont paginés, avec au maximum 10 liens par page.

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.

Étapes suivantes