RAG pour la documentation dbt

Les outils de documentation IA pour dbt décrivent ce que le SQL fait, pas ce que les données signifient pour le métier. Les LLMs génériques sans ancrage produisent des descriptions qui peuvent mal représenter la logique métier. Une étude de Chelli et al. (2024) a constaté que GPT-3.5 hallucinait 39,6 % des références dans les revues de littérature médicale, avec GPT-4 à 28,6 %. Sans ancrage dans le contexte métier, les descriptions dbt générées par IA tendent à reformuler les noms de colonnes plutôt qu’à expliquer la signification métier.

Les vraies définitions vivent dispersées dans les fils Slack, les tickets Jira, les PRDs et les têtes des gens. Que signifie « actif » pour votre entreprise ? Le champ amount est-il net ou brut ? Le champ status inclut-il les enregistrements à l’état brouillon ? Un commentateur de Data Engineering Weekly a bien résumé la chose pour les environnements SAP : « Un champ comme PRCTR se comporte différemment selon les codes société. Certains types de documents dans ACDOCA doivent être exclus pour des scénarios de reporting spécifiques. Cette connaissance est tacite. »

Le RAG (Retrieval-Augmented Generation) est l’approche la plus prometteuse pour combler ce fossé.

La différence que fait le contexte métier

Sans contexte métier :

columns:
  - name: customer__segment
    description: "Le segment du client"

Avec RAG puisant dans les bases de connaissances internes :

columns:
  - name: customer__segment
    description: >
      Catégorisation basée sur la logique Marketing Tier 2024
      définie dans le PRD-102, distinguant les comptes
      self-serve des comptes enterprise-managés.

La première description ne dit rien. La deuxième indique d’où vient la logique, quelle version elle suit, et ce que les segments représentent. C’est le type de documentation qui aide à la fois les humains et les agents IA à comprendre vos données. Et le cycle compte : une meilleure documentation rend les outils IA plus efficaces quand ils lisent vos descriptions de schéma pour générer ou réviser du code. De mauvaises descriptions conduisent à des références de colonnes hallucinées et à une logique métier mal comprise.

Une implémentation RAG pour dbt

Sravani Kakaraparthi a documenté une implémentation pratique en décembre 2025. L’approche comporte trois composants :

1. Un parseur qui parcourt le répertoire models/ et identifie les colonnes avec des descriptions manquantes ou placeholder
2. Un agent RAG limité aux bases de connaissances internes (PRDs, archives Slack, wikis, dictionnaires de données) qui récupère le contexte pertinent pour chaque colonne
3. Un injecteur qui écrit les descriptions générées dans les fichiers schema.yml

Dans son cas, l’agent RAG utilisait Glean (un outil de recherche enterprise), mais le principe compte plus que l’outil spécifique. Tout setup RAG capable d’interroger vos docs internes fonctionne : Glean, une base de données vectorielle personnalisée, Notion AI, ou même une collection organisée de fichiers Markdown indexés par votre modèle d’embedding préféré.

L’insight clé est le périmètre. Un LLM généraliste avec accès à internet hallucine parce qu’il génère des définitions plausibles à partir de ses données d’entraînement. Un agent RAG limité à vos bases de connaissances internes récupère des définitions réelles depuis les endroits où votre logique métier est documentée. Le LLM fait toujours l’écriture, mais il écrit à partir de votre contexte au lieu d’inventer du contexte.

L’alternative plus simple : le contexte métier dans CLAUDE.md

Si mettre en place un pipeline RAG complet semble prématuré — et pour la plupart des équipes en dessous de cent modèles, c’est le cas — une alternative plus simple vous emmène une partie du chemin.

Copiez les sections de PRD pertinentes, les entrées de dictionnaire de données ou les définitions de glossaire métier dans votre fichier CLAUDE.md. Claude Code lit ce fichier avant chaque interaction, donc les définitions métier que vous y incluez informeront la documentation qu’il génère.

Par exemple, ajouter ceci à votre CLAUDE.md :

## Business Definitions
- **Active customer**: Placed an order in the last 90 days. Does NOT include trial accounts.
- **LTV**: Net revenue (after refunds) over the customer's lifetime. Excludes shipping.
- **Customer segment**: Based on 2024 Marketing Tier logic (PRD-102). Self-serve vs enterprise-managed.
- **Amount fields**: Always net of tax unless column name includes `_gross`.

Ce n’est pas automatisé. Vous organisez manuellement le contexte métier. Mais c’est efficace pour les équipes où :

• Le nombre de modèles est gérable (moins de 100)
• Les définitions métier ne changent pas fréquemment
• Vous n’avez pas d’outillage de recherche enterprise comme Glean en place
• Vous voulez commencer à créer de la valeur maintenant, pas après qu’un pipeline RAG soit construit

Le compromis est clair : l’approche CLAUDE.md ne passe pas à l’échelle, et les définitions peuvent devenir obsolètes si personne ne les maintient. Mais « organisé manuellement et généralement exact » est dramatiquement mieux que « pas de contexte métier du tout ».

Le profilage des données comme contexte supplémentaire

Au-delà des définitions métier, alimenter les outils IA avec des résultats de profilage des données améliore la précision des descriptions. Les statistiques de colonnes — min, max, comptages de valeurs distinctes, distributions — donnent à l’IA des informations concrètes sur ce à quoi les données ressemblent réellement.

Une colonne avec seulement trois valeurs distinctes est probablement catégorielle, et la description devrait le dire. Une colonne numérique où chaque valeur est comprise entre 0 et 1 est probablement un taux ou un pourcentage. Une colonne d’ID avec 50 000 valeurs distinctes sur 50 000 lignes est probablement une clé primaire.

Ancrez l’IA dans vos données en plus du SQL. Vous pouvez le faire manuellement (exécuter une requête de profilage et coller les résultats dans votre prompt) ou l’automatiser dans votre pipeline de documentation. Dans les deux cas, les résultats de profilage réduisent les hallucinations parce que l’IA décrit ce qu’elle peut voir plutôt que ce qu’elle imagine.

Quand passer à un RAG complet

L’approche CLAUDE.md est un point de départ. Envisagez de construire un vrai pipeline RAG quand :

• Votre projet dépasse 100 modèles et l’organisation manuelle ne peut pas suivre
• Les définitions métier changent fréquemment (réorgs trimestriels, catégories de produits en évolution)
• Plusieurs équipes contribuent à la documentation et ont besoin d’un contexte métier cohérent
• Vous disposez déjà d’outillage de recherche ou de gestion des connaissances enterprise pouvant servir de backend de récupération
• La qualité de la documentation affecte directement les workflows IA en aval (génération de code, analyse de données) et le coût des descriptions hallucinées est élevé

Le chemin de montée en puissance est incrémental. Commencez avec CLAUDE.md pour les définitions les plus critiques. Ajoutez le profilage des données à vos prompts de documentation. Quand l’approche manuelle commence à sembler insoutenable, construisez le pipeline de récupération. Vous n’avez pas besoin de résoudre le problème RAG complet dès le premier jour — vous avez besoin du contexte métier sous la forme qui est soutenable pour votre équipe aujourd’hui.