Connecteur dbt

Cet article explique le fonctionnement du connecteur dbt pour DataGalaxy.

Ce connecteur est disponible dans les modes suivants :

Ce connecteur supporte les modes d'import suivants:

Périmètre, attributs et représentation dans DataGalaxy

La représentation des objets dbt dans DataGalaxy dépend du mode d'import. Les Modèles dbt constituent à la fois une transformation et l'objet de stockage destination qui présente les données transformées ; ils sont donc représentés dans DataGalaxy à la fois dans le module « Dictionnaire » et dans le module « Traitements ».

En mode Standard, les Sources et les Modèles sont représentés dans le Dictionnaire sous forme d'objets utilisant la technologie dbt. Il s'agit de la même couche d'abstraction que celle proposée par dbt, qui masque les objets sous-jacents de la plateforme de données réelle. La hiérarchie des Sources et des Modèles en mode Standard dans le Dictionnaire suit l'organisation des packages, de même pour le module de Traitements.

En mode URN, actuellement disponible lors de l'utilisation de dbt avec Databricks, BigQuery ou Snowflake, les sources et les modèles sont résolus grâce aux informations de connexion (fichier profiles.yml pour dbt Core et connexions des projets liées à l'environnement de production pour dbt Platform), ce qui permet de créer les objets réels de la plateforme de données dans le Dictionnaire. Cela offre une meilleure visibilité sur le lineage au sein de la plateforme de données, qui peut être complétée en aval vers l'outil de visualisation de données (par exemple à l'aide du connecteur URN Power BI) ou en amont vers la couche d'ingestion Sources. La couche d'abstraction de dbt n'est pas représentée dans DataGalaxy en mode URN. Les modèles dbt sont toujours représentés dans le module Traitements. La hiérarchie des sources et des modèles dans le dictionnaire en mode URN suit celle de la plateforme de données, de sorte que ce mode est entièrement compatible avec d'autres connecteurs apportant des métadonnées aux mêmes objets (connecteurs Snowflake, Power BI, Sifflet, etc.).

⚠️  Si vous utilisez une plateforme de données autre que Snowflake, BigQuery ou Databricks avec dbt, il est préférable de désactiver le mode URN, car aucun objet ne sera créé dans le Dictionnaire et aucun lineage ne sera disponible.

Comme indiqué dans la section consacrée à la configuration de la connexion, les sources de métadonnées pour dbt Core sont les fichiers de documentation dbt au format .json (ainsi que le fichier profiles.yml en mode URN). Pour dbt Platform, il s'agit des API Administrative v3 et Discovery (l'état « Applied » de l'environnement de production associé au projet sélectionné est utilisé).

Objets

Certains attributs listés ci-dessous pourraient ne pas être présents par défaut dans la configuration de vos écrans. Pour les faire apparaître dans les écrans DataGalaxy, il peut être nécessaire d'adapter les configuration d'écrans des objets concernés avant de lancer le connecteur. Consultez cet article pour en savoir plus sur la personnalisation des écrans.

Compte

Le compte dbt Platform est représenté dans le Dictionnaire (mode Standard seulement) comme une Source base de données relationnelle, et dans le module Traitements comme un Data Flow. Pour dbt Core, le Compte est remplacé par un objet racine générique représentant le produit dbt Core.

L'URN suit cette syntaxe pour dbt Core :

urn:dbt-1:dbtcore.profile_name

urn:dbt-1:account_id

Les attributs suivants sont récupérés :

Projet

Le Projet ne concerne que dbt Platform et est représenté dans le Dictionnaire (mode Standard seulement) par un Modèle, et dans le module Traitements par un Data Flow.

L'URN suit cette syntaxe :

urn:dbt-1:account_id:project_id

Package/Dossier

Les packages et dossiers sont représentés dans le Dictionnaire (mode Standard seulement) par un Modèle, et dans le module Traitements par un Data Flow.

L'URN suit cette syntaxe :

urn:dbt-1:account_id:project_id:package:folder1:folder2

Source

Une source dbt est représentée par la structure correspondante (Table ou Vue) dans le Dictionnaire. En mode URN, l'objet réel de la plateforme de données sous-jascente à la Source est représenté, mais pas l'objet Source lui-même. En mode Standard, l'objet Source est représenté associé à la technologie dbt. 

Associer les attributs des Sources sur les objets du Dictionnaire en mode URN est optionnel, dans la mesure où vous pourriez préférer remplir ces attributs grâce au connecteur dédié de la plateforme de données.

La structure de l'URN suit la structure définie pour chaque plateforme de données supportée (Snowflake, Databricks, BigQuery).

Les attributs suivants sont récupérés depuis les fichiers de documentation dbt (dbt Core) ou la Discovery API (dbt Platform) :

Modèle

Un Modèle dbt est représenté à la fois comme un objet Traitement dans le module Traitements et en tant que structure cible (Table ou Vue) dans le Dictionnaire. En mode URN, pour le Dictionnaire l'objet réel de la plateforme de données sous-jascente au Modèle est représenté, mais pas l'objet Modèle lui-même. En mode Standard, pour le Dictionnaire le Modèle est représenté, associé à la technologie dbt.

Associer les attributs des Modèles aux objets Dictionnaire en mode URN est optionnel, dans la mesure où vous pourriez préférer remplir ces attributs grâce au connecteur dédié de la plateforme de données.

La structure de l'URN suit la structure définie pour chaque plateforme de données supportée (Snowflake, Databricks, BigQuery).

Les attributs suivants sont récupérés depuis les fichiers de configuration dbt (dbt Core) ou la Discovery API (dbt Platform) :

Pour les objets du module Processing :

Pour les objets Dictionnaire* :

* si option sélectionnée

Colonne/Champ

Les Colonnes ou Champs des Sources et Modèles dbt sont représentés par des Colonnes ou Champs dans le Dictionnaire, sous la structure représentant la Source ou le Modèle correspondant.

Associer les attributs des Colonnes et Champs aux objets du Dictionnaire en mode URN est optionnel, dans la mesure où vous pourriez préférer remplir ces attributs grâce au connecteur dédié de la plateforme de données.

La structure de l'URN suit la structure définie pour chaque plateforme de données supportée (Snowflake, Databricks, BigQuery).

Les attributs suivants sont récupérés* depuis les fichiers de configuration dbt (dbt Core) ou la Discovery API (dbt Platform), ici dans l'exemple d'un Modèle mais le mapping pour une Source est similaire :

* si option sélectionnée

Liens

Les liens créés par le connecteur dbt sont les liens de lineage entre les Modèles et les Sources/Modèles amonts. En mode URN, les liens sont créés vers les structures réelles (Tables/Vues) représentant les objets de la plateforme de données dans le Dictionnaire. En mode Standard, les liens sont créés avec les objets Dictionnaire représentant les Sources et Modèles dbt.

ℹ️ La granularité du lineage est au niveau table entre un objet Traitement et ses objets Dictionnaire en entrée, et au niveau colonne avec l'objet Dictionnaire en sortie. dbt ne fourni pas encore le lineage complet à la colonne, donc théoriquement le lineage devrait être à la table partout. Mais dans la mesure où nous sommes sûrs que les colonnes en sortie sont impactées par la transformation (puisqu'elles sont gérées par dbt), nous avons décidé de lier chaque colonne de la structure cible à l'objet Traitement représentant le Modèle.
A l'écoute des retours de nos clients, nous pourrions changer ce comportement et lier tous les objets au niveau table pour plus de clarté. Puis, lorsque dbt fournira le lineage complet à la colonne, nous serons en mesure de proposer cette fonctionnalité également.

Informations techniques et permissions dbt

Avec dbt Core, le connecteur dbt utilise les fichiers suivants de dbt : 

• manifest.json : décrit l’ensemble du projet dbt
• catalog.json : décrit les métadonnées des tables ou vues manipulées dans les scripts SQL
• profiles.yml : en mode URN, ce fichier fournit les informations nécessaires à la création des URN des tables et des vues de la plateforme de données connectée à dbt, afin de pouvoir générer un lineage entre ces objets dans le Dictionnaire de DataGalaxy.

Le fichier profiles.yml fait partie du projet dbt. Les deux fichiers .json correspondent à la documentation d'un projet dbt et sont générés à l'aide de la commande dbt suivante dans le dossier target/ du projet : 

dbt docs generate

Du mode Standard au mode URN

Différences

1. En mode Standard, le nom des objets racines est celui que vous donnez à la création de la connexion. En mode URN, il n'y a plus d'objet racine dbt dans le Dictionnaire (voir plus haut la description de la représentation dans DataGalaxy) et pour le module Traitements l'objet racine représente votre plateforme dbt Platform (si vous êtes client dbt Platform) ou une plateforme générique dbt Core (si vous utilisez dbt Core). Son nom est géré automatiquement et correspond au dernier segment de l'URN de l'objet.
2. En mode Standard, il n'y a pas de différences entre la hiérarchie des objets pour dbt Core et dbt Platform, car l'objet racine représente le projet dbt. En mode URN, pour dbt Platform l'objet racine représente la plateforme elle-même et les projets sont au niveau en-dessous en tant qu'enfants. Il y a donc un niveau de hiérarchie supplémentaire.

Guide de migration

ℹ️ Ce guide de migration est utile si vos objets DataGalaxy sont enrichis (attributs custom, liens ...). Si toute l'information sur vos objets viennent du connecteur, le chemin le plus rapide pour la migration est de supprimer les objets existants de DataGalaxy et de relancer le connecteur en mode URN.

ℹ️ Gardez en tête qu'en mode URN, la représentation des objets dans le Dictionnaire change complètement, de la représentation des Modèles dbt associés à une Technologie dbt, à la représentation des objets réels de votre plateforme de données (Snowflake, BigQuery, Databricks). Comme cette représentation est nouvelle, migrer des métadonnées de l'ancienne à la nouvelle représentation peut ne pas être pertinent. Si vous utilisez une autre plateforme de données que les 3 supportées actuellement, veuillez nous contacter via le support ou votre AM avant de migrer (voir la FAQ également).

Pour dbt Core

Si vous avez des enrichissements que vous souhaitez conserver sur les objets du Dictionnaire, vous aurez à les exporter grâce à l'export CSV puis les réimporter sur les nouveaux objets après avoir exécuté le connecteur en mode URN. Ensuite, supprimez la hiérarchie d'objets du Dictionnaire associés à la Technologie dbt étant donné qu'ils ne sont plus pertinents en mode URN.

Pour le module Traitements, si vous souhaitez conserver votre hiérarchie d'objets du mode Standard, voici les étapes à suivre :

• Si vous avez automatisé la mise à disposition des fichiers catalog.json et manifest.json au connecteur, vous devrez en faire de même pour le fichier profiles.yml pour utiliser le mode URN. Notez bien que le connecteur n'a pas besoin des mots de passe de votre plateforme de données, nous vous recommandons donc de les supprimer du fichier que vous mettez à disposition du connecteur;
• Ajoutez l'attribut URN sur les écrans des objets Data Flow si ce n'est pas déjà le cas;
• Ajoutez la valeur de l'URN de l'objet racine du module Traitements utilisé par votre connexion en mode Standard, en suivant ce format : urn:dbt-1:dbtcore.<nom_de_votre_profil_dbt> . Par exemple, si le profil que vous utilisez dans le fichier profiles.yml est my-dbt-prod, l'URN de l'objet racine devrait être : urn:dbt-1:dbtcore.my-dbt-prod .
• Soyez sûrs d'être en vue Technique (bouton bascule dans le menu en haut à droite) et changez le nom Technique de l'objet racine du module Traitements utilisé par votre connexion en mode Standard, en suivant ce format : dbtcore.<nom_de_votre_profil_dbt> . Par exemple, si le profil que vous utilisez dans le fichier profiles.yml est my-dbt-prod, le nom Technique de l'objet racine devrait être : dbtcore.my-dbt-prod .
• Lancez le connecteur et activez le mode URN. Vous aurez quelques nouveaux paramètres à renseigner, notamment le profil du fichier profiles.yml et la target correspondante, ainsi que quelques nouvelles options au sujet des attributs (voir autres chapitres de cette documentation).
• Après avoir exécuté le connecteur, le Dictionnaire devrait être rempli avec vos objets de votre plateforme de données (Snowflake, BigQuery, Databricks) et tous les objets dbt du module Traitements devraient avoir été mis à jour avec leur propre URN.

Félicitations, vous avez migré avec succès !

Pour dbt Platform

Si vous êtes client dbt Platform (Starter, Enterprise, Enterprise+), veuillez nous contacter afin que nous puissions vous accompagner dans cette migration. 

Exécution du connecteur

Etape 1 : Installation

• Télécharger le connecteur DataGalaxy depuis le portail (voir ici)
• Extraire l'archive du connecteur dans le répertoire de votre choix
• Télécharger le plug-in dbt depuis le portail et le copier dans le répertoire /lib du connecteur

Etape 2 : Exécution du connecteur dbt

• Après avoir démarré le connecteur, accéder aux connecteurs de type Dictionnaire ou Traitement  

• S'il a été correctement installé, le plug-in dbt apparaît dans la liste

• Les informations suivantes sont demandées pour dbt Core :
  

• Les informations suivantes sont demandées pour dbt Platform :

Liste complète des paramètres :

* voir Questions fréquentes pour plus d'informations sur ce privilège.

Le bouton Tester permet de contrôler que l'ensemble des fichiers nécessaires pour réaliser l'import soient bien présents dans le dossier de travail sélectionné.

Questions fréquentes

Dois-je utiliser le lineage proposé par dbt ou celui proposé par le connecteur de ma plateforme de données (Snowflake, Databricks, BigQuery) ?

Les deux solutions présentent des avantages et des inconvénients. Tout d’abord, soyez assurés qu’en mode URN, vous disposez des deux options, vous pouvez donc les tester et choisir celle qui correspond le mieux à vos besoins.

Étant donné que le lineage fourni par dbt ne porte que sur le niveau tables, vous préférerez peut-être utiliser celui fourni par votre plateforme de données si vous souhaitez un lineage au niveau colonne. Mais dans ce cas, les liens seront créés directement entre les objets du Dictionnaire, sans passer par l'objet Traitement de dbt (qui représente le Modèle responsable de la transformation). D'un autre côté, sur certaines plateformes de données, l'obtention du lineage peut entraîner des coûts (coûts de tracking pour BigQuery, coûts de compute pour Snowflake ...), alors que le lineage fourni par dbt est disponible gratuitement.

Comment la fonctionnalité de gestion des objets orphelins gère-t-elle les objets de la plateforme de données en mode URN ? Leur statut peut-il passer à « Obsolete » ou peuvent-ils être supprimés s'ils n'existent plus après une modification du modèle dans dbt ?

En effet, si un Modèle a été modifié ou supprimé dans dbt, l'objet cible correspondant sur la plateforme de données pourrait être affecté lors de la prochaine exécution du projet dbt ; il peut donc être judicieux d'appliquer à ces derniers l'action relative aux objets orphelins.

En raison d'une limitation actuelle, un connecteur ne peut pas prendre en compte les objets orphelins provenant d'une autre technologie. Le connecteur dbt ne peut donc pas gérer les objets orphelins pour Snowflake, Databricks ou BigQuery. L'équipe est consciente de cette limitation et une mise à jour sera disponible pour y remédier. Cela restera optionnel : l'utilisateur aura le choix de laisser le connecteur considérer les objets de la plateforme de données (dans le Dictionnaire) comme faisant partie du périmètre des objets orphelins dbt, ou non, car il pourrait préférer gérer les objets orphelins avec le connecteur dédié de la plateforme de données concernée. 

Est-il prévu de prendre en charge d'autres plateformes de données connectées à dbt en mode URN ?

La prise en charge de dbt + Postgres est prévue. Si vous recherchez une autre plateforme de données, veuillez nous contacter par l'intermédiaire de votre Account Manager. En fonction de la complexité et de nos priorités, nous pourrions ajouter la prise en charge d'autres technologies à notre roadmap.

Pourquoi dois-je accorder des privilèges de « Account Viewer » en plus du jeu d'autorisations « Metadata only » ?

Le connecteur utilise davantage de endpoints API dbt afin de récupérer la liste des environnements et de sélectionner automatiquement celui destiné au déploiement. Ces appels nécessitent pour l'instant le privilège « Account Viewer ». Nous avons estimé qu'il serait plus simple pour nos clients de limiter le nombre de paramètres à fournir au connecteur. Nous pourrions adopter une autre approche qui nécessiterait seulement des privilèges « Metadata Only », ce qui impliquerait de définir davantage de paramètres dans la configuration du connecteur. Si vous estimez que c'est une option plus sûre et plus adaptée à votre contexte, n'hésitez pas à nous contacter. Nous sommes très attentifs aux retours d'expérience, en particulier lorsqu'il s'agit de sécurité.

Releases