Limitations Jinja des doc blocks dbt

Les doc blocks semblent supporter Jinja parce qu’ils utilisent des balises {% docs %} / {% enddocs %} et résident dans des fichiers .md que le parseur Jinja de dbt traite. Mais le contexte Jinja à l’intérieur d’un doc block est fortement restreint, et mal comprendre cela cause des erreurs difficiles à déboguer.

Le contexte restreint

Les doc blocks sont compilés avec un contexte Jinja minimal. Les fonctions clés qui ne sont pas disponibles à l’intérieur des doc blocks :

ref() — vous ne pouvez pas référencer des modèles
source() — vous ne pouvez pas référencer des sources
config() — pas de contexte de configuration
var() — pas de variables de projet
La plupart des autres fonctions Jinja dbt

La fonction doc() elle-même fonctionne, ce qui signifie que vous pouvez référencer un doc block depuis un autre. Mais c’est essentiellement la seule fonction spécifique à dbt disponible.

Si vous essayez quelque chose comme ceci à l’intérieur d’un doc block :

{% docs order_status %}
Voir {{ ref('stg_orders') }} pour les valeurs de statut brutes.
{% enddocs %}

Vous obtiendrez une erreur 'ref' is undefined lors de la compilation. La solution de contournement pour référencer des modèles en croix est d’utiliser des chemins URL internes à la place :

{% docs order_status %}
Voir [stg_orders](#!/model/model.my_project.stg_orders) pour les valeurs de statut brutes.
{% enddocs %}

Le piège du parsing README

Le parseur Jinja de dbt traite tous les fichiers .md dans vos chemins de ressources, pas seulement les fichiers contenant des doc blocks. Cela surprend les gens quand ils ont un README.md dans leur répertoire de modèles.

Si votre README contient quoi que ce soit qui ressemble à de la syntaxe Jinja — {{ something }}, {% block %}, même des exemples de code montrant du Jinja — le parseur essaiera de l’évaluer et échouera avec 'ref' is undefined ou des erreurs similaires.

Deux solutions :

Déplacer les README hors des chemins de ressources. Gardez la documentation dans un dossier docs/ de premier niveau qui n’est pas listé dans model-paths, seed-paths ou d’autres configurations de chemins de ressources.
Éviter la syntaxe Jinja dans les README. Si vous devez avoir un README dans un répertoire de modèles, utilisez des blocs de code ou échappez les séquences {{ / {%. Vous pouvez utiliser {% raw %}...{% endraw %} pour empêcher le traitement Jinja d’un bloc.

Ce piège s’applique également aux fichiers .md tirés par les packages dbt. Si un package inclut des fichiers Markdown avec une syntaxe Jinja dans ses chemins de ressources, ces fichiers seront analysés également.

La fonctionnalité manquante : l’héritage des descriptions de colonnes

L’une des fonctionnalités les plus demandées dans dbt est l’héritage des descriptions de colonnes — où les modèles en aval récupèrent automatiquement les descriptions de colonnes de leurs parents en amont. Si vous décrivez customer_id dans votre modèle base, chaque modèle intermédiaire et mart qui utilise cette colonne hériterait de la description sans que vous n’ayez à faire quoi que ce soit.

Cela est suivi sous l’issue GitHub #1158 et n’a pas été implémenté nativement au début de 2026.

Sans héritage natif, vous avez deux options pour éviter la duplication des descriptions :

Doc blocks partagés

Définissez un doc block pour chaque colonne commune et référencez-le explicitement partout :

# Dans le YAML du modèle base
columns:
  - name: customer_id
    description: "{{ doc('customer_id') }}"

# Dans le YAML du modèle mart — même référence
columns:
  - name: customer_id
    description: "{{ doc('customer_id') }}"

Cela requiert que vous ajoutiez la référence {{ doc() }} dans le YAML de chaque modèle, mais au moins le texte de la description est défini en un seul endroit. Modifiez le doc block et cela se met à jour partout.

Propagation dbt-osmosis

dbt-osmosis résout cela de manière plus automatique. Il trace le lignage des colonnes dans votre DAG et copie les descriptions des modèles en amont vers ceux en aval. Exécuter dbt-osmosis yaml refactor propage les descriptions sans nécessiter de références doc blocks du tout — il copie simplement le texte dans le YAML de chaque modèle.

Le compromis : dbt-osmosis duplique le texte (chaque fichier YAML a donc sa propre copie de la description), tandis que les doc blocks maintiennent une source de vérité unique. Pour la plupart des équipes, dbt-osmosis est moins contraignant à maintenir car il s’exécute automatiquement, mais les doc blocks offrent des garanties plus solides de cohérence.

Implications pratiques

Ces limitations orientent la façon dont vous architecturez votre documentation :

Utilisez les doc blocks pour le texte de description lui-même, et les chemins URL #!/model/... pour les références croisées entre modèles
Gardez les fichiers Markdown non-doc-block hors des chemins de ressources, ou enveloppez leur contenu dans des balises {% raw %}
Pour la réutilisation des descriptions de colonnes, choisissez entre des doc blocks partagés (source de vérité unique, plus de configuration) et dbt-osmosis (propagation automatisée, texte dupliqué). Les deux résolvent le problème ; ils font des compromis différents