dbt: Stratégie de debug par modèles intermédiaires (`debug models`) chaînés avec `ref()`

---

🎯 Objectif

Identifier où et pourquoi des valeurs inattendues apparaissent dans un pipeline dbt en traçant étape par étape les transformations via des modèles intermédiaires.

---

🧠 Problème typique

Tu constates par exemple :

• des valeurs NULL dans une colonne censée être toujours présente
• des doublons alors que tu appliques un distinct
• une incohérence métier dans un modèle final

Mais… tu ne sais pas à quelle étape du pipeline la mauvaise donnée est introduite.

---

✅ Solution : Créer une chaîne de modèles debug basés sur ref()

Chaque modèle debug te permet d’examiner l’état des données après chaque transformation.

---

📁 Exemple de structure

Imaginons ce pipeline dbt :

source("erp", "orders_raw")
    ↓
stg_orders.sql
    ↓
int_orders_cleaned.sql
    ↓
fct_orders.sql

Tu as un bug dans fct_orders : le champ total_amount est négatif, ce qui ne devrait jamais arriver.

---

🪛 Étape 1 : créer des modèles debug

Tu crées des modèles intermédiaires sans rien modifier dans ton pipeline original, juste pour inspecter :

debug_stg_orders.sql

SELECT * FROM {{ ref('stg_orders') }}
WHERE total_amount < 0

debug_int_orders_cleaned.sql

SELECT * FROM {{ ref('int_orders_cleaned') }}
WHERE total_amount < 0

debug_fct_orders.sql

SELECT * FROM {{ ref('fct_orders') }}
WHERE total_amount < 0

Ces modèles te montrent si l’erreur est déjà présente à chaque étape.

---

✅ Avantages de cette approche

Avantage	Détail
🔎 Trace précise	Tu identifies quelle étape introduit ou amplifie le problème
🧱 Réutilise le ref()	Tu profites du graphe de dépendance dbt sans casser le pipeline
💬 Collaboration	Tu peux partager un modèle de debug précis avec ton équipe
🧾 Documentation du bug	Tu peux garder ces modèles pour en faire des tests ultérieurs
🧪 Compatible tests	Tu peux rajouter des tests sur les debug_* pour valider des hypothèses

---

⚙️ Option : désactiver le debug_* après correction

Tu peux soit :

• les supprimer
• les taguer debug et les ignorer par défaut :

models:
  my_project:
    debug:
      +enabled: false

Et lancer ponctuellement :

dbt run --select tag:debug

---

✅ Résumé

Créer des modèles debug_* avec ref() te permet de tracer l’état des données étape par étape dans un pipeline dbt, d’identifier précisément l’origine d’une valeur erronée, et de partager facilement les résultats avec ton équipe.

---