dbt persist_docs pour les commentaires warehouse

persist_docs pousse les descriptions YAML dbt directement dans le warehouse sous forme de commentaires natifs de tables et de colonnes, rendant la documentation visible dans les clients SQL, les navigateurs de schémas des outils BI et les catalogues de données — partout où les analystes interrogent déjà le warehouse — sans nécessiter une visite du site de documentation dbt.

Configuration

Activez-le dans dbt_project.yml au niveau du projet ou par répertoire :

models:
  my_project:
    +persist_docs:
      relation: true
      columns: true

• relation: true pousse les descriptions au niveau du modèle comme commentaires de table
• columns: true pousse les descriptions au niveau des colonnes comme commentaires de colonne

Vous pouvez limiter cela à des couches spécifiques si vous souhaitez uniquement documenter les modèles mart dans le warehouse :

models:
  my_project:
    marts:
      +persist_docs:
        relation: true
        columns: true

Ou le définir par modèle dans le bloc config du modèle :

{{ config(
    persist_docs={"relation": true, "columns": true}
) }}

Fonctionnement

Quand dbt exécute un modèle avec persist_docs activé, il émet des instructions COMMENT ON TABLE et COMMENT ON COLUMN (ou leur équivalent pour la plateforme) après avoir matérialisé le modèle. Les descriptions proviennent de votre YAML de schéma — soit du texte en ligne soit des références {{ doc() }} résolues.

Comportements clés :

• Les doc blocks sont entièrement résolus. Si votre YAML indique description: "{{ doc('customer_id') }}", le commentaire warehouse contient le texte développé du doc block, pas la référence Jinja.
• Le Markdown est supprimé. En-têtes, gras, tableaux, liens — toute la mise en forme Markdown est retirée. Le commentaire warehouse est en texte brut. Rédigez des descriptions lisibles sans mise en forme si vous utilisez persist_docs.
• Les commentaires persistent entre les exécutions. Une fois qu’un commentaire est défini, il reste jusqu’à être écrasé par une exécution dbt ultérieure. Supprimer une description du YAML ne supprime pas le commentaire du warehouse.
• Les modèles incrémentaux réappliquent les commentaires. Même lors d’exécutions incrémentales qui n’insèrent que de nouvelles lignes, dbt réapplique les commentaires de table et de colonne.

Support des plateformes

persist_docs fonctionne sur toutes les principales plateformes warehouse :

Où persist_docs apporte le plus de valeur

La valeur est maximale pour les équipes où les utilisateurs métier interrogent directement le warehouse. Un analyste exécutant DESCRIBE TABLE ou des requêtes INFORMATION_SCHEMA dans BigQuery voit vos descriptions soigneusement rédigées directement dans le schéma. Pas besoin d’un site de documentation séparé. Les catalogues de données qui lisent les métadonnées du warehouse (Dataplex, Alation, Atlan, Select Star) captent également ces commentaires automatiquement.

Le site de documentation dbt nécessite que quelqu’un le visite activement. Les commentaires warehouse apparaissent passivement — dans les clients SQL, les navigateurs de schémas des outils BI et les résultats de recherche des catalogues — pour quiconque interroge le warehouse. Voir les patterns de documentation dbt pour un contexte plus large.

Association avec les doc blocks

persist_docs et les doc blocks fonctionnent naturellement ensemble. Rédigez vos descriptions sous forme de doc blocks pour une réutilisation en source unique à travers les modèles, et activez persist_docs pour pousser ces mêmes descriptions dans le warehouse. La combinaison vous offre :

1. Un seul endroit pour mettre à jour chaque description (le doc block)
2. Des descriptions cohérentes sur tous les modèles référençant le même doc block
3. Une visibilité native dans le warehouse sans obliger qui que ce soit à visiter le site de documentation

Pour les modèles mart — la couche que les utilisateurs métier interrogent directement — cette combinaison est la plus impactante. L’application CI garantit que les descriptions existent avant que les modèles n’atteignent la production.

Limitations

• Pas de rendu Markdown. Comme mentionné ci-dessus, toute la mise en forme est supprimée. Si vos doc blocks reposent fortement sur des tableaux ou de la mise en forme structurée, les commentaires warehouse seront moins lisibles que la version du site de documentation.
• Pas de suppression. Supprimer une description du YAML ne supprime pas le commentaire warehouse. Vous devez exécuter manuellement une instruction COMMENT ON ... IS NULL ou recréer la table.
• Surcharge de performance. Chaque commentaire de colonne est une instruction DDL séparée. Sur un modèle avec plus de 100 colonnes, l’application des commentaires ajoute un temps notable à l’exécution. C’est généralement acceptable pour les modèles mart mais peut importer pour les exécutions incrémentales à haute fréquence.
• Les vues se comportent différemment. Sur certaines plateformes, les commentaires de colonnes sur les vues ne sont pas persistés ou sont perdus lors de la recréation de la vue. Les tables et les vues matérialisées sont plus fiables.