Importer des métadonnées depuis dbt Core

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

Les métadonnées suivantes sont capturées par l'intégration dbt :

  • Métadonnées techniques : 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 : alimentées par dbt MetricFlow, ceci inclut 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 : incluent des métadonnées d'exécution telles que la durée, 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 de traçabilité et de relation : incluent des graphiques de transformation (DAG) et des dépendances entre les ressources dbt, la traçabilité physique qui suit et lie 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 : 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 de dbt Core et MetricFlow, effectuez les tâches suivantes :

  1. Attribuez les rôles et autorisations requis.
  2. Activez l'API Knowledge Catalog.
  3. Respectez les prérequis dbt .
  4. Créez le groupe d'entrées de destination entry group s'il n'existe pas déjà.
  5. Comprenez 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 au compte de service Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) le rôle Lecteur d'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.

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

Prérequis dbt

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

  • manifest.json (obligatoire) : structure de projet de base et graphique d'exécution. Contient également les modèles sémantiques, les métriques et les requêtes enregistrées de MetricFlow.
  • catalog.json: noms de colonnes et types de données. Sans catalog.json, l'aspect de 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 des 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 des fichiers JSON dbt générés. Il peut s'agir d'un chemin d'accès à un répertoire local sur votre machine ou votre exécuteur 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 à 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 a besoin 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/) 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 lors de l'ingestion. Vous fournissez cet URI à l'aide de l'indicateur --storage-uri. L'appelant qui exécute la commande gcloud a besoin d'un accès en écriture (roles/storage.objectCreator ou roles/storage.objectAdmin) pour importer le fichier, et l'agent de service Knowledge Catalog a besoin 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, vous pouvez utiliser la commande gcloud alpha dataplex dbt metadata-jobs create pour :

  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 : transformer le contenu au format d'importation de métadonnées Knowledge Catalog (dbt_metadata.jsonl).
  3. Importer dans la préproduction : importer 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 le job d'importation : déclencher un job d'importation de métadonnées Knowledge Catalog qui demande au compte de service Knowledge Catalog de lire et d'ingérer les métadonnées préproduites de --storage-uri dans les ressources Knowledge Catalog.

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 qu'un bucket Cloud Storage de préproduction de sortie est configuré avec les autorisations appropriées pour l'appelant et le compte de service Knowledge Catalog.

  3. À partir de Cloud Shell, d'un terminal local ou d'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: (Sortie/Préproduction) préfixe d'URI Cloud Storage (gs://bucket/path/) dans lequel le fichier JSONL transformé est importé et à partir duquel le job d'importation lit 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).

    Indicateurs 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/). 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: met à jour uniquement les métadonnées observées par cette exécution dbt et laisse 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 qu'une exécution précédente lui a attribuée. Utilisez cette option pour une ingestion de routine et répétée. Consultez Réexécuter l'ingestion.
    • --validate-only: crée et importe le fichier JSON, et valide le job de métadonnées, mais n'effectue pas l'ingestion.

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

  5. Une fois le job créé, Knowledge Catalog planifie la première exécution en fonction de votre configuration, ou vous pouvez 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. Cette option met à jour uniquement ce que l'exécution dbt a observé et laisse tout le reste dans le groupe d'entrées seul. Vous pouvez donc l'exécuter 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 des entrées change :

  • 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 changent.
  • 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 à partir d'un ensemble d'artefacts aussi complet que possible pour votre pipeline.

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

  • 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, retapée ou redécrite.
  • Le 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

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

    Accéder à la recherche

  2. Dans le panneau Filters (Filtres), vous pouvez filtrer les éléments dbt à l'aide des Project (Projet), System (Système) et Type aliases (Alias de type). Dans la section System (Système), sélectionnez Imported Context (Contexte importé). La sélection de ce filtre ouvre une sous-section Managed Connectors (Connecteurs gérés). Sélectionnez dbt pour filtrer toutes les métadonnées dbt.

  3. Vous pouvez utiliser le champ de recherche pour effectuer des requêtes de recherche. Vous pouvez effectuer une recherche par mots clés ou en langage naturel. Par exemple, pour afficher tous les éléments dbt via la recherche par mots clés, saisissez system=DBT.

    Pour en savoir plus sur la recherche de ressources, consultez Rechercher des ressources dans Knowledge Catalog. Pour en savoir plus sur les expressions que vous pouvez utiliser dans le champ de recherche, consultez la section Syntaxe de recherche pour Knowledge Catalog.

  4. Vous pouvez également utiliser l' LookupContext pour récupérer le contexte LLM pour des ressources dbt spécifiques.

Limites

  • Compatible avec les versions récentes de dbt Core v1 (validées par rapport aux versions 1.11 et 1.12). dbt Core v2 et dbt Fusion ne sont pas compatibles.
  • Les modèles dbt qui utilisent le contrôle des versions de modèle ne sont pas compatibles.
  • 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. 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.
  • Les liens d'entrée ne sont pas compatibles.
  • Cette intégration n'est compatible qu'avec les événements de traçabilité dbt sur les ressources BigQuery dans l'API et le graphique Data Lineage. Les entrées dbt (source, seeds, modèles) pour les sources tierces externes ne sont pas capturées dans la traçabilité des données.

Étape suivante