Patterns de rédaction des descriptions de modèles dbt

Une description de modèle dbt utile répond à la finalité métier plutôt que de reformuler le nom du modèle. « Table des commandes » n’apprend rien à un utilisateur qu’il ne sache déjà lire dans le nom du modèle. Les descriptions rédigées dans un objectif métier — système source, granularité, inclusions et exclusions — communiquent des informations que le nom seul ne peut pas transmettre.

Le cadre des trois questions pour les descriptions de modèles

Une description de modèle utile répond à trois questions :

De quel système proviennent ces données ?
Que représente chaque ligne ?
Qu’est-ce qui est inclus ou exclu ?

Comparons deux descriptions du même modèle :

# Mauvais : reformule le nom du modèle
models:
  - name: base__shopify__orders
    description: "Table des commandes"

# Bon : répond aux trois questions
models:
  - name: base__shopify__orders
    description: >
      Commandes e-commerce finalisées depuis Shopify, incluant
      les détails de transaction et les informations client. Une ligne
      par commande. Exclut les transactions annulées et de test.

La bonne version indique à un utilisateur l’origine des données (Shopify), la granularité (une ligne par commande) et ce qui est délibérément exclu (les commandes annulées et de test). Un analyste qui voit cette description dans le panneau de schéma BigQuery ou dans le navigateur de colonnes de son outil BI sait immédiatement si c’est la table dont il a besoin.

Le pattern « une ligne par » est particulièrement précieux. Il communique la granularité de la table sans exiger d’inspecter les données ni de retracer le SQL. « Une ligne par client par jour » indique qu’il s’agit d’un snapshot quotidien. « Une ligne par événement » indique un niveau événementiel. Cette formule unique élimine toute une catégorie d’erreurs d’utilisation où quelqu’un agrège des données au mauvais niveau.

Patterns de description de colonnes

Les descriptions de colonnes suivent le même principe : répondre à « et alors ? » plutôt que reformuler le nom de la colonne.

Au lieu de…	Écrivez…
Price amount	Prix unitaire en USD au moment de l’achat
Created timestamp	Date de passation de la commande, en UTC
Customer segment	Classification marketing basée sur les dépenses annuelles (PRD-102)
Is active	Indique si le client a passé une commande au cours des 90 derniers jours
Revenue	Revenu net après remboursements, hors taxes et frais de livraison

Les patterns qui rendent les descriptions de colonnes utiles :

Spécifier les unités. amount est-il en USD ou en centimes ? duration est-il en secondes ou en millisecondes ? Si chaque colonne de montant dans votre projet inclut la devise et la dénomination, vous évitez toute une classe d’erreurs de calcul.
Spécifier les fuseaux horaires. created_at est-il en UTC, dans le fuseau de l’utilisateur ou du serveur ? Cela compte davantage que la plupart des équipes ne le réalisent, jusqu’au moment où quelqu’un produit un rapport décalé de quelques heures.
Indiquer les relations clés. « Clé étrangère vers dim_customers.customer_id » évite à quelqu’un de retracer les jointures dans votre SQL.
Expliquer la logique de calcul pour les champs dérivés. « Valeur moyenne des commandes calculée comme le revenu total divisé par le nombre de commandes, en excluant les commandes inférieures à 1 $ » indique à un analyste si cette définition correspond à la sienne pour l’AOV.
Mentionner explicitement les exclusions. Une colonne status qui n’inclut pas tous les statuts possibles doit préciser lesquels sont filtrés. « Statut de commande. Inclut uniquement ‘completed’ et ‘shipped’ ; exclut ‘cancelled’, ‘draft’ et ‘test’ » évite d’utiliser ce modèle pour une analyse nécessitant ces statuts exclus.

Lorsque vos descriptions de colonnes suivent ces patterns de manière cohérente, les doc blocks deviennent particulièrement puissants. Définissez customer_id, created_at et vos colonnes les plus répétées une seule fois avec leur contexte complet, puis référencez-les partout où elles apparaissent.

Descriptions de sources

Les descriptions de sources méritent autant de soin que les descriptions de modèles, en mettant l’accent sur les détails opérationnels qui aident à déboguer les problèmes de fraîcheur et de qualité :

sources:
  - name: salesforce
    description: >
      Données CRM de Salesforce, chargées via le connecteur Fivetran
      avec une fréquence de synchronisation de 15 minutes. Contient les objets
      account, contact, opportunity et activity.
    tables:
      - name: account
        description: >
          Enregistrements Salesforce Account. Une ligne par compte.
          Inclut les comptes actifs et archivés.
          Synchronisé toutes les 15 minutes via Fivetran.

Trois éléments rendent les descriptions de sources utiles : le nom du système en amont, la méthode d’ingestion et la cadence de rafraîchissement. Lorsqu’un problème de fraîcheur survient, un ingénieur qui voit « chargé via le connecteur Fivetran avec une fréquence de synchronisation de 15 minutes » sait exactement où chercher sans fouiller dans les configurations de pipeline.

description vs meta : deux rôles distincts

dbt offre deux emplacements pour attacher des métadonnées aux modèles : description et meta. Ils servent des objectifs différents et sont suffisamment souvent confondus pour que la distinction mérite d’être expliquée.

description est destiné à la prose lisible par les humains. Il s’affiche dans le site de documentation dbt, est poussé vers les commentaires du warehouse via persist_docs, et c’est ce que voient les analystes lorsqu’ils explorent votre schéma. Rédigez-le pour les personnes.

meta est destiné aux paires clé-valeur structurées compilées dans manifest.json. Il est consommé programmatiquement par des outils externes — catalogues de données, orchestrateurs, plateformes de gouvernance, scripts personnalisés. Rédigez-le pour les machines.

models:
  - name: mrt__marketing__campaign_performance
    description: >
      Métriques de performance de campagne quotidiennes agrégées depuis
      Google Ads et Meta Ads. Une ligne par campagne par jour.
    meta:
      owner: "marketing_analytics"
      contains_pii: false
      sla_hours: 4
      maturity: "production"

La propriété, la classification PII, les SLA, les niveaux de sensibilité des données — ces éléments appartiennent à meta parce que les outils doivent les lire programmatiquement. Ce que fait le modèle, ce que représente chaque ligne et ce qui est exclu — ces éléments appartiennent à description parce que les humains doivent les lire en contexte.

Mélanger les deux — mettre la propriété dans les descriptions ou rédiger de la prose dans meta — rend les deux moins utiles. La description se retrouve encombrée de métadonnées qui devraient être lisibles par des machines. Le meta devient un dépotoir de texte qu’aucun outil ne peut analyser de manière fiable.

Priorisation

Dans un projet avec de nombreux modèles non documentés, les modèles mart sont les cibles les plus prioritaires. Ce sont eux que les utilisateurs métier interrogent, et des descriptions manquantes ou inexactes à cette couche génèrent le plus de confusion. Utilisez les outils de scaffolding de documentation dbt pour générer des stubs YAML avec les noms de colonnes issus du warehouse. Rédigez d’abord les descriptions de modèles, puis les descriptions de colonnes. L’option upstream_descriptions: true hérite des descriptions des modèles parents, de sorte que seules les colonnes dont le sens change au niveau de la couche mart ont besoin de nouvelles descriptions.