Alternatives au site dbt docs par défaut

Quand la personnalisation et les optimisations d’hébergement ne peuvent pas adresser les limitations fondamentales du frontend dbt docs par défaut — performance à grande échelle, lignage au niveau des colonnes ou adoption de l’interface — remplacer le frontend est une option. Cette note couvre les principales alternatives.

Le “Supercharged dbt Docs” de Dagster

Le frontend de remplacement de Dagster est l’échange le plus direct. Il réécrit la SPA AngularJS en utilisant Next.js avec génération de site statique. La différence de performance est dramatique :

Le remplacement compile en site statique, donc il fonctionne comme un substitut direct de l’interface par défaut. Vous exécutez toujours dbt docs generate pour produire les artefacts manifest et catalog. Le frontend Dagster consomme ces mêmes fichiers JSON mais les rend en utilisant la génération de site statique moderne au lieu du parsing côté client.

C’est la meilleure option si votre problème principal est la performance et que vous souhaitez conserver le même workflow de documentation. Pas de nouvelle infrastructure de données. Pas d’ingestion de métadonnées supplémentaire. Juste un frontend plus rapide et plus léger pour le même contenu.

dbterd : diagrammes entité-relation

dbterd prend un angle différent. Au lieu de remplacer tout le site de documentation, il génère des diagrammes entité-relation depuis vos artefacts dbt. Les formats de sortie incluent :

• Mermaid
• DBML
• PlantUML
• GraphViz
• D2
• DrawDB

Si votre équipe trouve la visualisation du DAG plus confuse qu’utile — et beaucoup d’utilisateurs métier la trouvent ainsi — les ERDs peuvent être un moyen plus clair de communiquer les relations entre les modèles. Le DAG montre le flux de transformation (quel modèle alimente quel autre). Les ERDs montrent les relations de données (quelles tables partagent des clés). Des audiences différentes ont besoin de vues différentes.

Vous pouvez intégrer des diagrammes générés par dbterd dans vos doc blocks sous forme d’images, ajoutant un contexte visuel au site de documentation existant sans le remplacer. Ou générez-les comme artefacts de documentation autonomes pour les parties prenantes qui ne visitent jamais le site de documentation.

Catalogues de données

Des outils comme DataHub et Elementary ingèrent les manifestes dbt et présentent la documentation des modèles aux côtés des métadonnées d’autres parties de votre stack. Ils résolvent une limitation que le site de documentation par défaut ne peut pas adresser : dbt docs ne montre que les assets dbt.

Si votre plateforme de données inclut des sources Fivetran, des DAGs Airflow, des dashboards Looker et des modèles dbt, le site de documentation par défaut ne montre que la couche dbt. Un catalogue de données tire les métadonnées de tout cela, donnant aux utilisateurs une vue unifiée du flux des données de la source au dashboard.

Le compromis est l’investissement. Les catalogues de données nécessitent :

• La configuration de l’ingestion des métadonnées pour chaque source
• La maintenance continue des connecteurs au fur et à mesure que les outils évoluent
• La formation des utilisateurs sur une nouvelle interface
• Les coûts d’hébergement et d’exploitation (ou les frais SaaS)

Pour les équipes avec 3 à 5 outils de données dans leur stack, un catalogue de données commence à avoir du sens. Pour les équipes dont toute la plateforme de données est « dbt + un warehouse + un outil BI », le site de documentation par défaut (ou le remplacement Dagster) couvre le besoin.

dbt Cloud Catalog

Anciennement appelé Explorer, dbt Cloud Catalog est l’alternative managée pour les équipes déjà sur dbt Cloud. Il fournit :

• Lignage au niveau des colonnes (plan Enterprise uniquement) — voir quelles colonnes transitent par quelles transformations, pas seulement quels modèles se connectent
• Mises à jour automatiques après chaque run de production — pas de pipeline CI/CD à maintenir
• DAG amélioré avec des lentilles de métadonnées — filtrer par fraîcheur, couverture de tests, type de matérialisation
• Recommandations de projet qui font remonter les lacunes de documentation et de couverture de tests

Si vous êtes déjà sur dbt Cloud, c’est la voie de moindre résistance. Pas d’infrastructure à gérer, pas de frontend à héberger, pas de CI/CD à configurer. La documentation se met à jour automatiquement.

Si vous êtes sur dbt Core, Cloud Catalog devient un facteur dans la décision Core-versus-Cloud. C’est une amélioration significative de la qualité de vie, mais probablement pas le facteur décisif à lui seul. Le lignage au niveau des colonnes est la fonctionnalité la plus convaincante qui n’a pas d’équivalent dans l’écosystème open source.

Cadre de décision

Le frontend par défaut est-il trop lent ?
├── Oui → Essayez d'abord le remplacement Dagster (effort minimal)
│   └── Toujours insuffisant ? → Évaluez les catalogues de données
├── Non, mais j'ai besoin du lignage au niveau des colonnes
│   ├── Sur dbt Cloud → Utilisez Cloud Catalog
│   └── Sur dbt Core → Évaluez DataHub ou envisagez la migration vers Cloud
├── Non, mais les utilisateurs métier n'utilisent pas le site de documentation
│   ├── Ils utilisent Notion → Essayez dbt-docs-to-notion
│   ├── Ils ont besoin d'ERDs → Essayez dbterd
│   └── Ils ont besoin de contexte non-dbt → Évaluez les catalogues de données
└── Non, le site par défaut fonctionne bien
    └── Concentrez-vous sur la qualité du contenu plutôt que sur l'outillage

L’erreur la plus courante est de sauter vers un catalogue de données quand le vrai problème est la qualité du contenu. Si les descriptions de vos modèles disent « l’identifiant du client », aucun frontend ne rendra cela utile. Corrigez d’abord le contenu (doc blocks, personnalisation, de bonnes descriptions), puis améliorez le mécanisme de diffusion si les limitations du site par défaut deviennent le goulot d’étranglement.