Syntaxe et patterns de réutilisation des doc blocks dbt

Les doc blocks permettent de définir les descriptions de colonnes et de modèles une fois dans un fichier .md et de les référencer depuis n’importe quel nombre de fichiers YAML de schéma. Cela empêche les descriptions dupliquées de diverger entre les modèles.

La syntaxe

Un doc block réside dans n’importe quel fichier .md au sein des chemins de ressources de votre projet dbt (model-paths, seed-paths, etc.) :

{% docs customer_id %}
Identifiant unique pour un client dans notre système. Généré comme une
clé de substitution depuis le numéro de référence client du système source.
{% enddocs %}

Vous le référencez depuis le YAML avec la fonction doc() :

columns:
  - name: customer_id
    description: "{{ doc('customer_id') }}"

Plusieurs doc blocks peuvent résider dans le même fichier .md. Les noms doivent être globalement uniques dans tout votre projet (y compris les packages installés), ne peuvent pas commencer par un chiffre et n’autorisent que des caractères alphanumériques plus les underscores. Si un package dbt que vous avez installé définit un doc block customer_id, le vôtre entrera en collision. La forme à deux arguments gère les références inter-packages :

description: "{{ doc('my_package', 'customer_id') }}"

Les doc blocks fonctionnent pour les modèles, les colonnes, les sources, les seeds, les snapshots, les analyses, les macros et les arguments de macros. Des bugs connus existent avec les exposures et les modèles versionnés où des erreurs 'doc' is undefined peuvent apparaître.

Écrire les descriptions une seule fois

La vraie valeur vient de la définition des descriptions de colonnes communes sous forme de doc blocks partagés. Une colonne comme customer_id ou order__created_at qui apparaît dans tout votre projet obtient une définition unique faisant autorité :

{% docs customer_id %}
Identifiant unique pour un client dans notre système. Généré comme une
clé de substitution depuis le numéro de référence client du système source.
{% enddocs %}

{% docs order__created_at %}
Timestamp (UTC) de la première création de la commande dans le système source.
Cela reflète l'heure de création initiale, pas l'heure à laquelle elle a été
chargée dans le warehouse.
{% enddocs %}

Chaque modèle qui possède ces colonnes référence le même doc block. Modifiez le texte une fois, et cela se propage partout au prochain dbt docs generate.

Doc blocks au niveau des modèles

Pour les descriptions de modèles qui nécessitent plus d’espace qu’une ligne YAML ne le permet, les doc blocks vous permettent d’utiliser le Markdown complet avec des en-têtes, des tables et du formatage :

{% docs mrt__marketing__customer_ltv %}
Calculs de la valeur vie client sur une fenêtre glissante de 3 ans.

**Contexte métier** : Utilisé par l'équipe marketing de fidélisation pour
identifier les clients à haute valeur pour des campagnes ciblées.

**Méthodologie** : Flux de trésorerie actualisés avec un taux d'actualisation
annuel de 10 %, appliqués à toutes les commandes complètes (hors transactions
remboursées).

| Métrique | Définition |
|--------|-----------|
| customer__ltv_usd | Revenus actualisés totaux sur la fenêtre glissante |
| customer__ltv_tier | Quartile (1-4) basé sur ltv_usd |
{% enddocs %}

Référencez-le dans votre YAML de schéma : description: "{{ doc('mrt__marketing__customer_ltv') }}". Pour les détails sur les fonctionnalités Markdown supportées, voir Capacités Markdown du site dbt docs.

Conventions de nommage

Les conventions de nommage communautaires varient. Les principaux patterns :

• Noms de colonnes simples (customer_id) quand une seule définition fonctionne à l’échelle du projet. Le plus simple, fonctionne bien quand la sémantique des colonnes est cohérente.
• Noms de colonnes scoped par modèle (orders_col_total_amount) quand une colonne a des significations différentes dans différents modèles. Plus verbeux mais évite l’ambiguïté.
• Blocks au niveau modèle utilisent souvent table_<nom_modèle> pour les distinguer des blocks de colonnes.

Choisissez une convention, documentez-la dans votre guide de style et tenez-vous-y. L’incohérence dans le nommage est pire que n’importe quel choix particulier.

Pattern d’adoption

Les doc blocks partagés pour les colonnes les plus répétées (IDs, timestamps, métriques communes) adressent la majorité des descriptions dupliquées et incohérentes — typiquement 10 à 15 noms de colonnes représentent l’essentiel de la répétition. Les doc blocks au niveau modèle pour les modèles mart constituent le prochain domaine, car ce sont ceux que les utilisateurs métier rencontrent le plus souvent. persist_docs peut pousser les descriptions dans les commentaires du warehouse en parallèle du site de documentation.

Arrêter un pattern d’organisation de fichiers tôt évite une refactorisation ultérieure. Pour propager automatiquement les descriptions existantes dans le DAG sans écrire de doc blocks pour chaque colonne, voir dbt-osmosis.