Importer des métadonnées depuis dbt Core

Knowledge Catalog (anciennement Dataplex Universal Catalog) vous permet d'importer des métadonnées opérationnelles, sémantiques et de traçabilité depuis dbt Core, dbt Cloud et MetricFlow à l'aide de la Google Cloud CLI et de vos fichiers d'artefacts dbt. Au lieu de laisser les métadonnées de transformation cloisonnées dans l'écosystème dbt, vous pouvez les centraliser pour aider les ingénieurs de données, les ingénieurs d'analyse et les intendants de données à découvrir et à gouverner les données d'entreprise.

Métadonnées importées et cas d'utilisation

Étant donné que 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 de répondre à différents cas d'utilisation. Vous importez des métadonnées Oracle ou PostgreSQL pour répondre à la question "Quelles données brutes avons-nous ?", 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 ?".

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 IA en explorant les définitions et la logique métier optimisées par dbt MetricFlow, telles que 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 temps, l'état de réussite ou d'échec, la fraîcheur des données et les résultats des tests.
  • Métadonnées de traçabilité et de relation : effectuez une analyse d'impact en aval et un traçage des causes principales en explorant les graphiques de transformation (DAG) et les dépendances entre les ressources dbt, la traçabilité physique qui suit et associe 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 l'utilisation des donné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.
  • La version 586.0.0 et les versions ultérieures de gcloud CLI sont compatibles avec l'intégration de dbt et de Knowledge Catalog. Pour installer ou mettre à jour la CLI, consultez Installer la Google Cloud CLI.
  • Il n'existe pas de connexion directe à dbt Cloud. Pour importer des métadonnées à partir d'un job dbt Cloud, commencez par récupérer 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. Par conséquent, les schémas profondément imbriqués peuvent 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 traçabilité dbt sur les ressources BigQuery dans l'API Data Lineage et le graphique. Les entrées dbt (sources, graines, modèles) pour les sources tierces externes ne sont pas capturées dans la traçabilité 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. Accordez les rôles et autorisations requis.
  2. Activez l'API Dataplex.
  3. Remplissez les conditions préalables pour dbt.
  4. Créez le groupe d'entrées de destination s'il n'existe pas déjà.
  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 IAM (Identity and Access Management) 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 attribuer à 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 préproduit :

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 : l'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éproduction de sortie (--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

Activer l'API Dataplex

Activer l'API

Prérequis dbt

Pour importer l'ensemble des métadonnées dbt, nous vous recommandons de produire les quatre fichiers d'artefacts JSON dbt. Seul manifest.json est obligatoire. Les autres enrichissent l'importation, et la transformation se dégrade de manière fluide sans eux :

  • manifest.json (obligatoire) : structure du projet principal 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 de colonnes et types de données. Sans catalog.json, l'aspect du schéma est importé avec des colonnes non typées.
  •  : résultats des tests et métadonnées d'exécution.run_results.json
  • sources.json : fraîcheur de la source.

Dans votre terminal local, Cloud Shell ou l'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 sur un seul profil et une seule cible pour générer l'ensemble complet des 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 ont 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 au répertoire local sur votre machine ou votre exécuteur d'intégration continue (par exemple, ./target/ ou .) ou d'un préfixe d'URI de bucket Cloud Storage d'entrée (par exemple, gs://my-dbt-artifacts-bucket/target/). Vous fournissez ce chemin d'accès à l'aide de l'option --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 d'importation Knowledge Catalog) : préfixe d'URI de bucket Cloud Storage (tel que gs://my-staging-bucket/dbt-imports/) où 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 pendant 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 importer le fichier, et l'agent de service Knowledge Catalog doit disposer d'un accès en lecture (roles/storage.objectViewer) pour l'importer.

Importer des métadonnées à partir d'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'artefact que dbt Core, vous pouvez importer des métadonnées depuis dbt Cloud en récupérant ces fichiers d'artefact 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 l'actualisation de la source. dbt Cloud exécute dbt source freshness avant les commandes de 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 canaux de publication dbt Core 2.x et dbt Fusion : ajoutez dbt parse --write-catalog en tant que commande de job.
    • Pour les canaux de publication dbt Core 1.x : 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 Générer des documents lors de l'exécution exécute dbt docs generate sans --no-compile, ce qui écrase les résultats de test de dbt build, comme décrit dans la section Prérequis dbt. Notez que si une étape de commande échoue, le job échoue également, tandis que l'étape de case à cocher ne fait pas échouer le job.

Si dbt build échoue, par exemple en raison de l'échec d'un test, 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 de job terminée.
  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é de l'exécution 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 CLI dbt Cloud) exécute des 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 Prérequis 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 sur le répertoire target/.

La CLI s'exécute dans votre environnement de développement à l'aide de vos identifiants d'entrepôt de données personnels. Les métadonnées générées reflètent donc votre schéma de développement plutôt que les tables de production créées par une tâche planifiée. 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 dbt Administrative

Vous pouvez utiliser l'API dbt Administrative pour récupérer de manière programmatique les artefacts 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 :

Depuis votre terminal local, Cloud Shell ou 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 sur ce chemin d'accès.

Par défaut, le point de terminaison d'artefact 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 l'exécution réussie la plus récente 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 l'état Success. Vous pouvez interroger ce point de terminaison de manière planifiée 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 des 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 (Paramètres du compte) > Webhooks, puis cliquez sur Create webhook (Créer un webhook) ou Create new webhook (Créer un 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 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 au maximum. Comme 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'option --async).
  • job.run.completed se déclenche également pour les exécutions ayant échoué. Ainsi, les exécutions avec des tests ayant échoué sont 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 des webhooks et la validation des signatures, consultez 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 : lisez 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 en préproduction : importez le fichier d'importation de métadonnées transformé dans l'emplacement Cloud Storage de préproduction de sortie 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 indique à l'agent de service Knowledge Catalog de lire et d'ingérer les métadonnées préparées depuis --storage-uri dans les ressources Knowledge Catalog.

Console

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

    Accéder à la page "Connecteurs"

  2. Cliquez sur Ajouter une connexion.

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

  4. Pour afficher vos éléments 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'artefacts de métadonnées dbt sont stockés localement ou dans un bucket Cloud Storage d'entrée.
  2. Assurez-vous de disposer d'un bucket Cloud Storage de préproduction de sortie configuré 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 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/

    Options obligatoires

    • --storage-uri=STORAGE_URI : (Sortie/Staging) Préfixe d'URI Cloud Storage (gs://bucket/path/) vers lequel le fichier JSONL transformé est importé et à partir duquel 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 au répertoire local (tel que . ou ./target) ou d'un préfixe d'URI Cloud Storage (tel que gs://my-bucket/dbt-artifacts/). 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 court 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 met à jour que les métadonnées observées par cette exécution dbt et ne modifie pas le reste du groupe d'entrées. Aucune entrée n'est créée, supprimée ou réassociée, aucun lien d'entrée n'est émis, et un aspect dont l'artefact dbt était absent de cette exécution conserve la valeur qu'une exécution précédente lui a attribuée. Utilisez cette option pour l'ingestion de routine 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 la 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 couvre 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, et un nœud et la table BigQuery dans laquelle il est matérialisé.
      • schema-join : colonnes joignables déclarées par un test dbt relationships.
    • --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, instantané) 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'aux entrées @bigquery de cette 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 doit donc disposer 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 situés dans d'autres régions, et les liens vers ces ensembles de données 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'effectuez pas l'ingestion.

  4. Vérifiez que l'état Created (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 court 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 dans le groupe d'entrées, de sorte qu'il peut être exécuté de manière répétée, selon n'importe quelle planification et à partir de plusieurs jobs.

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

  • La première ingestion 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 sont 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 que votre pipeline peut produire.

Exécutez --aspects-only pour les actualisations de routine :

  • Après l'exécution de la commande dbt de votre pipeline : dbt build, dbt test, dbt source freshness ou une recompilation limitée à --select.
  • Une colonne est ajoutée, supprimée, retypé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 éléments 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 en utilisant la recherche par mot clé ou en langage naturel. Par exemple, pour afficher tous les éléments 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 sa page d'informations 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 des modèles ou des 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 court 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 l'intégralité des métadonnées et des aspects 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 de 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 court 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'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 est le nom de ressource complet de l'entrée dbt. Les résultats sont paginés, avec un maximum de 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 Syntaxe de recherche pour Knowledge Catalog.

Étapes suivantes