Options de formatage YAML pour les descriptions dbt

Le champ description du YAML dbt accepte quatre syntaxes : chaîne inline, scalaire replié, scalaire littéral et doc block. Chacune se rend différemment, interagit différemment avec les espaces blancs et présente des compromis de lisibilité différents dans un fichier YAML de schéma.

Chaîne inline

L’option la plus simple. Fonctionne pour les descriptions courtes sur une seule ligne qui tiennent confortablement sur une ligne :

- name: mrt__core__orders
  description: "Une ligne par commande Shopify complète, hors transactions de test."

Les guillemets sont optionnels pour le texte simple, mais les inclure est une bonne pratique — ils empêchent YAML d’interpréter mal les deux-points, les caractères spéciaux ou les valeurs qui ressemblent à des booléens. Gardez les descriptions inline en dessous de 100 caractères. Quand elles se coupent dans votre éditeur, la lisibilité se dégrade et vous devriez passer à un bloc scalaire.

Les chaînes inline sont le bon choix pour les descriptions de modèles base où le grain et la source sont simples et bien compris, et pour les descriptions de colonnes auto-explicites où vous ajoutez principalement des unités ou une brève clarification.

Scalaire replié (>)

Le scalaire replié replie les sauts de ligne en espaces. Vous pouvez couper les longues descriptions sur plusieurs lignes dans votre éditeur pendant que la description se rend comme un seul paragraphe continu :

- name: mrt__marketing__customer_ltv
  description: >
    Calculs de la valeur vie client sur une fenêtre glissante de 3 ans
    et méthodologie des flux de trésorerie actualisés (taux d'actualisation
    annuel de 10 %). Une ligne par client. Exclut les clients sans commande
    complète. Sources : commandes Shopify via base__shopify__orders et
    paiements Stripe via base__stripe__payments.

Cela se rend comme : « Calculs de la valeur vie client sur une fenêtre glissante de 3 ans et méthodologie des flux de trésorerie actualisés (taux d’actualisation annuel de 10 %). Une ligne par client. Exclut les clients sans commande complète. Sources : commandes Shopify via base__shopify__orders et paiements Stripe via base__stripe__payments. »

Les sauts de ligne dans le YAML sont purement pour la lisibilité dans l’éditeur — ils n’apparaissent pas dans la description rendue. C’est le bon défaut pour la plupart des descriptions de modèles. Il permet d’écrire des descriptions suffisamment longues pour être utiles sans transformer votre YAML de schéma en mur de texte.

Un piège : les lignes vides deviennent des sauts de paragraphe. Si vous laissez une ligne vide à l’intérieur d’un bloc scalaire replié, vous obtenez deux paragraphes. Ce n’est généralement pas ce que vous souhaitez. Si vous voulez des paragraphes, utilisez le scalaire littéral à la place.

Scalaire littéral (|)

Le scalaire littéral préserve les sauts de ligne exactement tels qu’ils sont écrits. C’est utile quand vous souhaitez une séparation de paragraphes délibérée ou quand vous utilisez le formatage Markdown :

- name: mrt__marketing__customer_ltv
  description: |
    Calculs de la valeur vie client.

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

    **Détails techniques :** Utilise une fenêtre glissante de 3 ans et une
    méthodologie de flux de trésorerie actualisés avec un taux d'actualisation
    annuel de 10 %.

Les lignes vides se rendent en sauts de paragraphe, et le gras Markdown (**) se rend sur le site dbt docs. C’est le bon choix quand :

• Vous souhaitez séparer une section de contexte métier d’une section technique
• Vous documentez un modèle mart complexe où le partage d’audience (analystes vs ingénieurs) justifie des sections différentes
• Vous utilisez des tables ou des listes Markdown à l’intérieur de la description

Le compromis : les scalaires littéraux allongent les fichiers YAML et les rendent plus difficiles à parcourir. Réservez-les aux descriptions de modèles mart où la structure supplémentaire justifie son coût. Les descriptions de modèles staging nécessitent rarement ce niveau de structure.

Une note importante sur le rendu Markdown : le site dbt docs rend le Markdown dans les descriptions, mais persist_docs supprime tout le formatage Markdown. Si vous activez persist_docs pour pousser les descriptions dans les commentaires du warehouse, vos en-têtes en gras deviennent du texte brut. Rédigez des descriptions qui ont du sens dans les deux contextes si vous utilisez les deux fonctionnalités.

Doc blocks ({{ doc() }})

Les doc blocks référencent du contenu de description défini dans un fichier .md séparé. C’est l’option la plus puissante et la plus laborieuse à mettre en place :

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

Le doc block réside dans un fichier .md dans vos chemins de ressources :

{% docs customer__id %}
Identifiant unique du client dans le système source. Clé primaire dans
mrt__core__customers, clé étrangère dans les modèles de commandes et
de transactions.
{% enddocs %}

Les doc blocks sont le bon choix quand :

• La même colonne apparaît dans plusieurs modèles — définissez la description une fois, référencez-la partout, modifiez-la en un seul endroit
• Une description de niveau modèle est suffisamment longue pour que la placer dans le YAML encombre le fichier de schéma
• Vous souhaitez utiliser les pleines capacités Markdown (le doc block peut contenir des tables, des en-têtes et du formatage qui seraient maladroits dans un scalaire YAML)

Les pleines capacités, conventions de nommage, patterns d’organisation de fichiers et limitations des doc blocks sont couverts dans Syntaxe et patterns de réutilisation des doc blocks dbt et Organisation des fichiers de doc blocks dbt.

Choisir la bonne option

La règle générale : chaînes inline pour les colonnes simples, scalaires repliés pour la plupart des descriptions de modèles, scalaires littéraux quand la structure compte, doc blocks quand la réutilisation ou la longueur l’exige. De nombreuses équipes finissent par utiliser un mélange — inline pour les colonnes de la couche staging, scalaires repliés pour les descriptions de modèles mart, doc blocks pour les définitions de colonnes partagées comme les IDs et les timestamps.

Le choix de formatage n’affecte pas ce qui est rendu sur le site dbt docs — chacun de ces formats peut produire une bonne documentation. Ce qu’il affecte, c’est la facilité de lecture et de maintenance des fichiers YAML eux-mêmes, ce sur quoi votre équipe passera la plupart de son temps avec les descriptions.