Mapping des assets Dagster-dbt

L’intégration dagster-dbt lit le manifest.json d’un projet dbt et crée un asset Dagster par modèle, seed et snapshot. Les dépendances issues des appels ref() et source() dans le SQL deviennent des arêtes dans le graphe d’assets Dagster. La fonction de calcul exécute dbt build en arrière-plan.

La configuration de base

La configuration de base nécessite trois composants : un DbtProject pointant sur le répertoire du projet, un manifest que Dagster peut lire, et une fonction décorée avec @dbt_assets.

from dagster_dbt import DbtCliResource, DbtProject, dbt_assets
from pathlib import Path

my_project = DbtProject(project_dir=Path("./transform"))
my_project.prepare_if_dev()

@dbt_assets(manifest=my_project.manifest_path)
def my_dbt_assets(context, dbt: DbtCliResource):
    yield from dbt.cli(["build"], context=context).stream()

Trois choses se passent ici. DbtProject pointe Dagster vers le répertoire du projet dbt. prepare_if_dev() exécute dbt parse pour générer le manifest.json en développement local — en production, le manifest est construit au moment du déploiement avec dagster-dbt project prepare-and-package. Le décorateur @dbt_assets lit ce manifest et crée un asset par nœud.

Quand dagster dev est lancé et que localhost:3000 est ouvert, chaque modèle dbt apparaît dans le catalogue d’assets avec ses dépendances upstream et downstream visualisées. Si mrt__marketing__campaign_performance dépend de int__google_ads__clicks et int__meta_ads__impressions, le graphe montre ces relations automatiquement, extraites directement depuis les appels SQL ref().

Personnaliser le mapping avec DagsterDbtTranslator

Le mapping par défaut fonctionne pour la plupart des projets, mais DagsterDbtTranslator permet de contrôler comment les nœuds dbt deviennent des assets Dagster. Il suffit de le sous-classer et de surcharger des méthodes spécifiques.

Clés d’assets et groupes personnalisés

Par défaut, Dagster utilise le nom du modèle dbt comme clé d’asset. Si le projet suit une convention de nommage en couches avec des préfixes tels que base__, int__ et mrt__, les valeurs par défaut fonctionnent bien. Mais s’il faut mapper les modèles dans des groupes Dagster spécifiques ou ajuster les préfixes de clé :

from dagster_dbt import DagsterDbtTranslator, DbtCliResource, dbt_assets
from dagster import AssetKey

class CustomTranslator(DagsterDbtTranslator):
    def get_asset_key(self, dbt_resource_props):
        # Groupe les assets par chemin de modèle dbt : marts/marketing/model -> ["marketing", "model"]
        node_path = dbt_resource_props["path"]
        components = Path(node_path).stem
        return AssetKey(components)

    def get_group_name(self, dbt_resource_props):
        # Utilise le dossier dbt comme groupe Dagster
        return Path(dbt_resource_props["path"]).parts[0]

@dbt_assets(
    manifest=my_project.manifest_path,
    dagster_dbt_translator=CustomTranslator(),
)
def my_dbt_assets(context, dbt: DbtCliResource):
    yield from dbt.cli(["build"], context=context).stream()

La surcharge get_group_name est particulièrement utile pour les équipes utilisant une organisation par dossiers dans dbt. Si les modèles se trouvent dans marts/marketing/ et marts/finance/, Dagster les regroupe en conséquence dans l’UI, ce qui facilite le filtrage du graphe d’assets par domaine métier.

Tags, propriétaires et métadonnées depuis dbt Meta

Dagster lit la configuration meta de dbt. Les propriétés définies dans schema.yml se retrouvent dans l’UI Dagster :

models:
  - name: mrt__finance__monthly_revenue
    meta:
      dagster:
        owners: ["team:finance", "adrienne@example.com"]
        group: finance
    tags:
      - daily
      - critical
    columns:
      - name: revenue__total_usd
        description: "Revenus totaux en USD pour le mois"

Les tags de dbt sont mappés vers les tags Dagster. Les propriétaires spécifiés dans meta.dagster.owners apparaissent dans le catalogue d’assets et peuvent être utilisés pour filtrer le graphe de lineage par équipe. Cela signifie que la documentation existante du projet dbt sert aussi de métadonnées Dagster — pas besoin de maintenir deux sources de vérité pour la propriété et la classification.

Filtrer les modèles qui deviennent des assets

Tous les nœuds dbt n’ont pas besoin d’être des assets Dagster. Les modèles éphémères ne produisent pas de tables, il n’y a donc aucune matérialisation à suivre. Ils peuvent être exclus en surchargeant get_asset_key pour retourner None, ou en utilisant la syntaxe de sélection dbt dans le paramètre select du décorateur @dbt_assets :

@dbt_assets(
    manifest=my_project.manifest_path,
    select="tag:dagster",  # Seulement les modèles tagués 'dagster' dans dbt
)
def my_dbt_assets(context, dbt: DbtCliResource):
    yield from dbt.cli(["build"], context=context).stream()

Cela offre un contrôle précis. En taguant les modèles critiques dans dbt, seuls ceux-là deviennent des assets tracés dans Dagster. Pour les grands projets dbt avec des centaines de modèles, le filtrage réduit le bruit dans l’UI Dagster et concentre la surveillance sur les modèles les plus importants.

Configuration du projet : deux approches

L’approche Components (recommandée pour les nouveaux projets)

Depuis le cycle 1.12, Dagster recommande le DbtProjectComponent pour les nouvelles intégrations dbt. Le CLI dg structure tout :

dg scaffold defs dagster_dbt.DbtProjectComponent transform \
  --project-path ./transform

Cela crée un defs.yaml qui gère la compilation et le cache du manifest automatiquement. Le component génère tous les assets depuis le projet dbt avec un minimum de Python. Pour les équipes qui souhaitent le mapping sans personnalisation approfondie, c’est le chemin le plus rapide.

L’approche traditionnelle

Pour les projets existants ou les équipes qui souhaitent plus de contrôle, le scaffolding traditionnel génère directement des fichiers Python :

dagster-dbt project scaffold \
  --project-name my_project \
  --dbt-project-dir ./transform

Cela produit un package Python avec le décorateur @dbt_assets, une définition DbtProject, et la configuration des ressources. Les fichiers Python sont modifiés directement pour personnaliser le comportement — les surcharges DagsterDbtTranslator, les filtres select, les définitions de schedule sont toutes dans du code que l’on contrôle.

Gestion du manifest

Le manifest est le pont entre dbt et Dagster. En développement local, prepare_if_dev() ou le framework Components gère la génération du manifest de façon transparente. Pour les déploiements en production, le manifest est construit dans le pipeline CI/CD :

# Dans le pipeline CI/CD
dbt deps --project-dir ./transform
dagster-dbt project prepare-and-package \
  --file ./my_project/project.py

Cela compile le manifest une seule fois au moment du déploiement, évitant à Dagster d’exécuter dbt parse en production. La séparation est importante : le développement local reste rapide (parsing à la volée), la production reste déterministe (manifest pré-construit).

Ce qu’apporte le mapping

Le mapping n’est pas qu’une commodité visuelle. Une fois que les modèles dbt existent comme assets Dagster, on bénéficie de :

• Une lineage cross-système. Les modèles dbt apparaissent aux côtés des assets Python, des syncs Fivetran et de toutes les autres données managées par Dagster dans un seul graphe. La couche de transformation dbt n’est pas isolée — elle est connectée à tout ce qui est en amont et en aval.
• Une exécution unifiée. dbt build s’exécute via l’orchestration Dagster, ce qui signifie que la planification, les politiques de retry et le suivi de fraîcheur s’appliquent.
• Une surveillance par asset. Chaque modèle possède son propre historique de matérialisation, son suivi de durée et ses checks de qualité. Il est possible de voir quand mrt__finance__monthly_revenue a été exécuté pour la dernière fois, combien de temps cela a pris et si ses tests ont réussi.
• Une matérialisation sélective. Dans l’UI Dagster, il est possible de sélectionner des assets spécifiques et de ne matérialiser que ceux-ci, plus leurs dépendances downstream. Utile pour des corrections ad hoc ou des backfills ciblés sans exécuter l’ensemble du projet dbt.

Le projet dbt ne change pas lors de l’ajout de Dagster. Dagster l’encapsule et ajoute des capacités d’orchestration par-dessus.