Faut-il une couche sémantique pour vos agents IA ? Du Text-to-SQL au Context Engineering
Agentic AI, Text-to-SQL, Context Engineering, Model Context Protocol, MCP, Semantic Layer, dbt, DuckDB, Spider 2.0, BIRD Benchmark, Data Engineering, LLMOps
Face aux échecs répétés du Text-to-SQL direct, le réflexe immédiat de l’écosystème a été de proclamer l’urgence d’une « couche sémantique » universelle (MetricFlow, Cube). Mais a-t-on vraiment besoin d’un projet d’infrastructure pharaonique et rigide pour permettre à des agents d’interroger nos données de façon juste et fiable ?
Dans cet article, j’analyse les limites structurelles du Text-to-SQL à la lumière des benchmarks récents (BIRD, Spider 2.0), puis je montre comment une démarche pragmatique de Context Engineering, articulée autour de tables marts dbt bien découpées, d’un serveur FastMCP et d’un moteur vectorisé in-process DuckDB, permet d’obtenir un système déterministe, sub-seconde et sécurisé, sans le coût ni la rigidité d’une couche sémantique lourde.
1 L’illusion du “Text-to-SQL” magique
Quand l’engouement autour des modèles de langage a explosé, la promesse semblait limpide : donnez le schéma DDL de votre base de données à GPT-4, posez votre question en français ou en anglais, et laissez le modèle rédiger la requête SQL parfaite.
Dans les démos commerciales et sur des bases de données d’école, tout fonctionne à merveille. Mais dès qu’on déploie cette approche sur un entrepôt de données d’entreprise avec ses tables historiques, ses règles d’attribution subtiles et ses données parfois bruitées, le système s’effondre.
Le problème n’est pas que le modèle ne sait pas écrire du SQL : il génère presque toujours une requête syntaxiquement valide. Le problème, c’est que le résultat numérique retourné est faux, sans qu’aucun message d’erreur ne vienne vous alerter.
Avant d’explorer comment nous avons résolu ce défi, il est instructif de regarder ce que la littérature scientifique a documenté ces dernières années.
2 Ce que la recherche nous apprend : de Spider à BIRD et Spider 2.0
2.1 Le mirage des premiers benchmarks académiques (Spider)
Pendant plusieurs années, le benchmark de référence pour évaluer la génération SQL était Spider (1). Avec plus de 10 000 questions et 200 bases de données, il paraissait exhaustif.
Pourtant, Spider reposait sur des hypothèses très éloignées de notre quotidien d’ingénieur de données :
- Des bases SQLite miniatures : des tables ne comptant que quelques dizaines à centaines de lignes propres et synthétiques.
- Une normalisation d’école (3NF) : relations évidentes, clés primaires et étrangères parfaitement alignées, aucun champ composite ou dénormalisé.
- Zéro ambiguïté métier : chaque question correspondait mot à mot aux colonnes de la table. Si la question parlait du “nom de l’étudiant”, il y avait une colonne
student_name.
Sur ce terrain de jeu balisé, les modèles récents atteignaient plus de 85 % de précision d’exécution. Beaucoup ont conclu un peu vite que le problème du Text-to-SQL était résolu. C’était oublier que la réalité d’une entreprise ne ressemble en rien à une base SQLite d’étudiants.
2.2 Le réveil brutal : le benchmark BIRD
En 2023, l’équipe du benchmark BIRD (Big Information Retrieval and Database) (2) a posé la vraie question : un LLM peut-il servir d’interface fiable pour de la Business Intelligence ?
BIRD a confronté les modèles à de vraies bases volumineuses (jusqu’à 33 Go), sales, avec des valeurs textuelles non standardisées, des calculs de formules métier non explicites et des volumétries substantielles.
| Ce que mesurait Spider (2018) | Ce que mesure BIRD (2023) | Ce qu’on vit en production |
|---|---|---|
| Bases jouets (< 1 Mo) | Données d’entreprise (jusqu’à 33 Go) | Entrepôts massifs (Go à Po) |
| Schémas normalisés parfaits | Valeurs sales, formats mixtes, nuls | Données vivantes, cas particuliers |
| Schéma auto-suffisant | Formules métier indispensables | Glossaires, contrats et règles tacites |
| Précision modèle > 85 % | Chute à ~54 % (GPT-4) | Souvent < 30 % sans garde-fous |
| Efficacité de calcul ignorée | Mesure du coût machine (VES) | Risque de saturation de cluster DWH |
BIRD a démontré deux faits majeurs :
- L’écart critique entre syntaxe et sémantique : le modèle produit du code sans bug d’exécution, mais se trompe de prédicat métier.
- Le massacre de l’optimisation : livrés à eux-mêmes, les LLMs produisent des requêtes aux jointures hasardeuses qui mettent les bases à genoux.
2.3 Spider 2.0 (2024–2025) : La fin des illusions
Fin 2024, les auteurs de Spider ont publié Spider 2.0 (3). Cette fois, finis les bacs à sable : l’évaluation est branchée directement sur de vrais entrepôts cloud (Snowflake, BigQuery), avec des schémas d’entreprise de centaines de colonnes et des workflows combinant SQL, Python et documentation.
Le résultat est sans appel : même les modèles les plus avancés (Claude 3.5 Sonnet, GPT-4o) chutent sous la barre des 25 % de succès.
Pourquoi ? Parce qu’un agent ne peut pas deviner l’implicite. Pour être fiable, un agent doit disposer d’un outillage contraint et d’un guidage contextuel progressif.
3 Les quatre limites structurelles du Text-to-SQL en production
Sur le plan de l’architecture data, quatre problèmes majeurs expliquent pourquoi le Text-to-SQL direct est inadapté à un usage décisionnel en production :
3.1 Le piège silencieux du “fan-out” et des jointures combinatoires
Prenez une question classique pour un service SaaS ou mobile : “Quel est le chiffre d’affaires généré par les utilisateurs actifs ce mois-ci ?”.
Si le LLM écrit une requête reliant la table des utilisateurs, celle des abonnements et celle des logs d’activité, il risque à chaque étape de provoquer un produit cartésien partiel (fan-out). Si un utilisateur a réalisé 15 activités dans le mois et possède 2 abonnements historiques, une jointure naïve multiplie ses lignes d’achats par 30. Un SUM(amount) exécuté là-dessus gonfle artificiellement le chiffre d’affaires d’un facteur d’échelle délirant, sans jamais lever d’erreur SQL.
3.2 Le casse-tête des métriques semi-additives et des snapshots
Tout ce qui est dans une base ne s’additionne pas simplement :
- Le MRR (Monthly Recurring Revenue) ou les stocks sont des grandeurs d’état (snapshots). Faire
SUM(mrr)sur une table de suivi journalier n’a aucun sens mathématique : cela revient à sommer 30 fois la même valeur récurrente sur le mois. Pour un total mensuel, il faut soit calculer une moyenne journalière, soit isoler la date de clôture de fin de période (End of Period). - Les utilisateurs actifs (DAU / MAU) : additionner les utilisateurs uniques de chaque jour d’un mois ne donne pas le nombre d’utilisateurs uniques du mois, car un même utilisateur revient plusieurs fois.
Attendre d’un modèle qu’il déduise ces subtilités à partir du seul type DECIMAL ou INTEGER d’une colonne relève du vœu pieux.
3.3 La latence réseau qui asphyxie les boucles agentiques
Un agent autonome fonctionne par itérations successives selon le paradigme ReAct (4) : formuler une hypothèse, observer la réponse, corriger, puis conclure. Une analyse demande couramment entre 3 et 6 allers-retours.
Si chaque requête est envoyée à un entrepôt de données cloud classique (BigQuery, Snowflake), chaque étape subit le temps de négociation TLS, l’attribution du cluster (cold-start) et le démarrage du job (5 à 12 secondes). Votre boucle agentique met 45 secondes à une minute rien que pour attendre l’infrastructure. C’est inutilisable au quotidien.
3.4 Les failles de sécurité et la consommation de tokens
Laisser un agent générer du SQL direct sur une base, c’est s’exposer à deux risques majeurs :
- L’injection indirecte : des données sales ou malicieuses peuvent contenir du texte trompeur détournant les consignes du modèle.
- La saturation de contexte : lui injecter un catalogue DDL exhaustif de 80 tables consomme des dizaines de milliers de tokens à chaque tour, augmentant les coûts d’API et provoquant des hallucinations par noyade informationnelle (lost in the middle).
4 Faut-il une couche sémantique lourde ? Le virage du Context Engineering
Face aux écueils répétés du Text-to-SQL non contraint, le réflexe immédiat de l’écosystème a d’abord été de préconiser le déploiement d’une couche sémantique formelle (Semantic Layer / MetricFlow (5), Cube.dev). L’idée directrice paraît séduisante sur le papier : interdire au modèle d’écrire du SQL et le restreindre à formuler des requêtes abstraites (metric='mrr', by=['country']).
Pourtant, en pratique, ériger une couche sémantique lourde en préalable absolu à l’IA agentique s’avère souvent être un piège d’ingénierie :
- Un coût d’adoption et de maintenance disproportionné : modéliser l’intégralité des dimensions, hiérarchies et métriques d’un business dans un DSL spécifique (fichiers YAML complexes) exige des mois d’efforts et crée un goulot d’étranglement permanent pour les équipes data.
- Une perte d’expressivité analytique : dès qu’une question métier requiert des calculs de fenêtrage (window functions), des segmentations sur des cohortes fines ou des logiques conditionnelles non prévues par le compilateur sémantique, le système bloque ou génère des requêtes inadaptées.
- Une redondance avec le travail existant : la plupart des organisations disposent déjà d’une modélisation soignée dans leur entrepôt via dbt (tables dénormalisées
mart_*, testées chaque matin et documentées). Rajouter une usine à gaz sémantique par-dessus ce travail existant apporte souvent plus de rigidité que de valeur.
C’est la prise de hauteur salutaire défendue par plusieurs praticiens du domaine (notamment Christophe Blefari et Claire Gouze au micro du podcast The Data Hustle (6), qui ont matérialisé cette vision en fondant le framework open source nao (7), incubé chez Y Combinator) : on n’a pas forcément besoin d’une couche sémantique lourde pour construire des agents analytiques fiables et exploitables.
Plutôt que d’enfermer l’analytique dans un DSL rigide, cette démarche formalise le contexte directement dans des artefacts de code versionnés (fichiers de règles métier RULES.md, référentiel dbt, métadonnées compilées) et privilégie l’évaluation continue des requêtes générées par rapport à des vérités terrain.
Le vrai levier s’appelle le Context Engineering :
- Partir de Data Marts dbt éprouvés (1 mart = 1 grain strict) : des tables analytiques dénormalisées où les jointures complexes et les ambiguïtés d’attribution ont déjà été purgées en amont. Attention toutefois au piège des tables fourre-tout (One Big Tables) : mélanger plusieurs grains dans une même table (ex. un total journalier répété sur des centaines de lignes ventilées par fonctionnalité) induit inévitablement le LLM en erreur de fan-out (sommer 500 fois la même valeur quotidienne). La parade la plus robuste consiste à projeter des marts légers à grain unique strict (
kimball_grain: strict), rendant la mauvaise requête physiquement impossible à formuler. - Fournir le bon contexte au bon moment : guider le modèle à travers une découverte progressive (règles métier dans un glossaire compact, aiguillage par grain et tableau de bord, métadonnées issues du manifest dbt, exemples de requêtes certifiées).
- Encadrer le SQL par des garde-fous déterministes : laisser au LLM la pleine richesse d’expression du SQL ANSI, mais l’exécuter dans un bac à sable in-process sous surveillance statique stricte.
5 Notre architecture : le Context Engineering par la preuve
Plutôt que d’empiler un compilateur sémantique supplémentaire ou de laisser l’agent improviser du SQL sur l’entrepôt brut, nous avons conçu une couche d’intermédiation étanche articulée autour de trois piliers :
- La modélisation dbt comme socle de données : les grains, les règles d’additivité et les descriptions des tables marts sont définis et testés dans le code dbt.
- Le standard Model Context Protocol (MCP) (8) : protocole ouvert structurant les échanges de l’agent en outils exécutables (Tools), ressources documentaires (Resources) et gabarits de cadrage (Prompts).
- Le moteur vectorisé in-process DuckDB (9) : exécution locale ultrarapide sur des tables marts certifiées, ramenant la latence à quelques millisecondes sans frais d’infrastructure par requête.
6 Dans les coulisses de l’implémentation
Voici concrètement comment nous avons structuré le code au sein de notre dépôt data-warehouse.
6.1 Découverte progressive en 5 niveaux (adieu le dump DDL massif)
Pour éviter d’asphyxier la fenêtre de contexte de l’agent, le serveur FastMCP impose une trajectoire de découverte progressive en cinq étapes, de la plus légère à la plus verbeuse :
glossary://kpis: un glossaire métier ultra-compact (~1 500 tokens) rappelant les définitions officielles du chiffre d’affaires, du MRR et les règles strictes d’additivité.search_marts: un outil de recherche par mots-clés interrogeant un index précompilé (MART_INDEX). L’agent y découvre le grain de la table, son cas d’usage recommandé (use_when) et son rattachement aux dashboards officiels (Superset).describe_table: l’agent ne charge que la fiche technique de la table qu’il a sélectionnée. Nous fusionnons la structure introspectée dans DuckDB avec les descriptions dbt extraites dumanifest.json, et y ajoutons un exemple de requête SQL certifié (golden query).recipes://sql_golden_queries: des modèles de requêtes multi-tables vérifiées manuellement pour les cas complexes.docs://catalog: le catalogue complet du DAG. Les consignes système interdisent formellement à l’agent de le charger en premier appel.
6.2 Le garde-fou SQL : sql_guard.py
L’outil d’exécution execute_duckdb_query ne fait jamais aveuglément confiance au modèle. Avant de transmettre la requête à DuckDB, celle-ci passe par un module de validation stricte :
# Extrait de tools/mcp/sql_guard.py
def validate_sql_query(query: str) -> str:
clean_query = query.strip()
if not clean_query:
raise ValueError("La requête SQL ne peut pas être vide.")
# 1. Pas de requêtes chaînées
query_without_trailing = clean_query.rstrip(";").strip()
if ";" in query_without_trailing:
raise ValueError("Sécurité : Les requêtes multi-statements sont interdites.")
# 2. Lecture seule absolue
first_word = query_without_trailing.lstrip().split()[0].upper()
if first_word not in {"SELECT", "WITH"}:
raise ValueError("Sécurité : Seules les requêtes SELECT et WITH sont permises.")
# 3. Neutralisation des fonctions système DuckDB
match = DANGEROUS_DUCKDB_PATTERNS.search(clean_query)
if match:
raise ValueError(f"Sécurité : L'élément '{match.group(0)}' est strictement interdit.")
# 4. Allowlist stricte sur les tables accessibles
cte_allowed = _cte_names(query_without_trailing)
for raw_rel in _referenced_relations(query_without_trailing):
rel = raw_rel.strip().strip('"').split(".")[-1].lower()
if rel in cte_allowed or rel in {"information_schema", "tables", "columns"}:
continue
if rel.startswith(("raw_", "stg_", "cln_")) or rel == "user":
raise ValueError(f"Sécurité : la table '{rel}' est hors périmètre analytics.")
if not is_allowed_table_name(rel):
raise ValueError(f"Sécurité : table '{rel}' non autorisée (mart_*, fact_*, dim_* uniquement).")
# 5. Pas de SELECT * sur les tables analytiques
_reject_select_star_on_analytics_tables(query_without_trailing, cte_allowed)
return query_without_trailingCe filtre garantit cinq invariants techniques :
- Pas de point-virgule : impossible d’injecter une seconde instruction malveillante en douce.
- Lecture seule stricte : seuls
SELECTetWITHsont autorisés. Aucune mutation (INSERT,UPDATE,DROP,ALTER) n’est possible. - Blocage du système de fichiers : interdiction des primitives DuckDB comme
read_parquet,read_csv,copyouwrite_parquet. - Périmètre réservé aux marts certifiés : seules les tables préfixées par
mart_*,fact_*etdim_*sont accessibles. Les données brutes (raw_*), intermédiaires (stg_*) et les tables d’utilisateurs nominatives sont rejetées d’office. - Interdiction formelle du
SELECT *: l’agent est obligé de nommer précisément les colonnes dont il a besoin. Cela évite d’extraire des gigaoctets de données inutiles et de saturer le buffer de contexte.
Enfin, pour parer à toute mauvaise surprise de volumétrie, le serveur encapsule la requête dans un sous-select borné avec une clause de limitation stricte :
SELECT * FROM (
-- Requête validée de l'agent
) AS _mcp_bounded LIMIT 50;6.3 Donner des yeux à l’agent : profile_column
Pour éviter que l’agent n’invente des filtres WHERE sur des colonnes dont il ignore la teneur réelle, nous avons ajouté un outil de profilage unitaire :
# Extrait du calcul dans tools/mcp/server.py
stats_sql = f"""
SELECT
COUNT(*) as total_rows,
COUNT("{clean_col}") as non_null_count,
ROUND((COUNT(*) - COUNT("{clean_col}")) * 100.0 / COUNT(*), 2) as null_pct,
COUNT(DISTINCT "{clean_col}") as distinct_count,
MIN("{clean_col}")::VARCHAR as min_val,
MAX("{clean_col}")::VARCHAR as max_val
FROM "{clean_tbl}"
"""Avant de formuler une hypothèse, l’agent peut appeler profile_column("dim_user_description", "subscription_status"). En retour, il reçoit le taux de valeurs nulles, la cardinalité exacte et les 5 modalités les plus fréquentes avec leur part en pourcentage. Il n’a plus besoin de “deviner” si le statut s’écrit 'active', 'ACTIVE' ou 'subscribed'.
6.4 L’auditabilité intégrale : audit.py
Chaque interaction est consignée dans un journal d’audit en JSON Lines. Nous y enregistrons :
- Le hash SHA-256 de la requête (
qhash). - La question d’origine posée par l’utilisateur.
- Le temps d’exécution en millisecondes.
- Le nombre de lignes retournées et le token de l’utilisateur.
En cas de contestation d’un chiffre par une équipe métier, nous pouvons rejouer la trajectoire exacte de l’agent étape par étape, éliminant l’effet “boîte noire”.
7 Les garanties concrètes apportées par cette architecture
En écartant le Text-to-SQL libre au profit de cette interface MCP sur DuckDB, on verrouille le système sur quatre plans fondamentaux :
- Déterminisme d’exécution : les erreurs de fan-out et d’additivité sont éliminées à la racine. L’agent interroge des marts déjà modélisés, documentés et validés par nos tests dbt quotidiens.
- Latence in-process : l’exécution des requêtes sur DuckDB en local ne prend que quelques dizaines de millisecondes, sans file d’attente ni coût de scan facturé à la requête.
- Frugalité de contexte : l’aiguillage en entonnoir (
glossary→search_marts→describe_table) évite d’injecter des dizaines de schémas DDL dans le prompt. L’agent ne charge que les métadonnées de la table dont il a besoin pour répondre. - Sécurité et lecture seule stricte : le code de
sql_guard.pyrend impossibles les injections destructrices, les lectures sur le système de fichiers hôte ou l’accès aux tables brutes et nominatives.
8 Ce qu’il faut garder en tête
Cette architecture n’est évidemment pas magique. Elle impose une discipline d’ingénierie que beaucoup d’équipes hésitent encore à fournir :
- La qualité de l’agent dépend de la qualité de votre modélisation dbt : si vos descriptions de colonnes sont vides et vos marts mal découpés, l’agent continuera d’hésiter. L’IA ne remplace pas l’Analytics Engineering : elle en devient la première cliente.
- Le cycle de vie du manifest dbt : chaque modification de modèle en production nécessite de recompiler le
manifest.jsonet de rafraîchir l’index du serveur MCP. C’est un maillon de votre chaîne CI/CD à ne surtout pas négliger. - Vers une écriture contrôlée : aujourd’hui, nos agents opèrent en lecture seule. L’étape suivante consistera à leur permettre de proposer des transformations de données, non pas en exécutant du SQL en direct, mais en créant des Pull Requests dbt validées automatiquement par nos tests d’intégration.
9 Recommandations de l’état de l’art (SOTA) pour vos projets Agent-Data
Pour les équipes qui souhaitent brancher des agents autonomes sur leurs données d’entreprise sans tomber dans le piège du Text-to-SQL naïf, voici les quatre piliers méthodologiques recommandés par l’état de l’art actuel :
9.1 Du Semantic Layer lourd au Context Engineering pragmatique
- Capitaliser sur vos Data Marts dbt : Plutôt que de vous enliser dans le déploiement d’une couche sémantique lourde et d’un DSL de métriques abstrait, appuyez-vous sur des tables marts dénormalisées et testées. Ce sont les données elles-mêmes, associées à des descriptions de colonnes rigoureuses, qui portent la sémantique.
- Pratiquer le Context Engineering : Injectez à l’agent un contexte hiérarchisé (glossaire de calculs, métadonnées compilées, requêtes d’exemples étalonnées) pour lui permettre d’exploiter la flexibilité du SQL sans halluciner sur les règles métier.
- Systématiser l’évaluation continue (Golden Baseline) : À l’instar d’outils comme
nao test(7) ou de suites dbt/pytest d’assertions de réconciliation, figez un jeu de questions métiers et leurs requêtes SQL canoniques. Évaluez systématiquement votre agent en CI/CD pour mesurer son taux de succès exact avant tout déploiement en production. - Appliquer des contrats de données stricts : En CI/CD, imposez la validation de contrats de schéma (
contract: enforced: truedans dbt) et exigez 100 % de descriptions sur les colonnes exposées à l’agent. Ce qu’un ingénieur data ne documente pas pour ses pairs reste indéchiffrable pour un agent.
9.2 Standardiser l’interface via MCP et ordonner le contexte
- Adopter le Model Context Protocol (MCP) : Évitez les connecteurs ad-hoc ou les frameworks d’agents propriétaires. Le protocole MCP (8) fournit un standard ouvert (JSON-RPC) éprouvé pour découpler les outils exécutables (Tools), les contextes passifs (Resources) et les consignes (Prompts).
- Imposer la découverte progressive : N’injectez jamais un schéma complet dans le contexte initial. Suivez une hiérarchie stricte en entonnoir : glossaire métier synthétique \(\to\) index de routage par grain et cas d’usage \(\to\) fiche descriptive unitaire de la table retenue \(\to\) catalogue exhaustif en dernier recours.
9.3 Rapprocher le calcul de l’agent (In-Process OLAP & Arrow IPC)
- Découpler l’exploration agentique de l’entrepôt cloud : Les boucles itératives (ReAct (4), Reflexion) ne tolèrent pas les temps d’orchestration de 5 à 15 secondes des entrepôts distribués.
- Privilégier les moteurs vectorisés locaux : Pour l’analyse décisionnelle sur des tables marts certifiées, utilisez des moteurs in-process comme DuckDB (9) ou Apache DataFusion alimentés par des fichiers Parquet partitionnés. Le transit des données en mémoire via Apache Arrow (10) (zéro-copie) assure des temps de réponse sous les 50 ms sans coût de scan facturé à la requête.
9.4 Verrouiller la sécurité par analyse statique de code (AST Parsing & Guardrails)
- Ne jamais exécuter de SQL brut sans filtrage statique : Même avec un prompt rigide, un modèle peut dériver. Utilisez un parseur syntaxique (comme
sqlglotou des règles regex strictes) pour analyser l’arbre syntaxique abstrait (AST) de chaque requête. - Appliquer les invariants de production : Interdiction absolue des instructions multi-statements (pas de point-virgule), lecture seule stricte (
SELECT/WITH), blocage des primitives système accédant aux fichiers, allowlist impérative sur les tables autorisées, rejet duSELECT *et injection serveur d’un plafondLIMITnon négociable. - Journaliser systématiquement pour auditer : Enregistrez pour chaque interaction l’empreinte cryptographique de la requête (
qhash), la question posée en langage naturel, la latence et les identifiants d’accès afin de garantir une traçabilité totale en cas de litige sur un chiffre.
10 En conclusion
L’intégration de l’intelligence artificielle dans l’analytique d’entreprise n’exige ni de confier aveuglément les clés de la base de données à un modèle probabiliste, ni d’ériger en préalable une infrastructure de couche sémantique pharaonique.
En combinant une modélisation analytique soignée (dbt), une stratégie d’ingénierie de contexte progressive (MCP) et un moteur in-process local (DuckDB), on permet aux agents d’exploiter la flexibilité du SQL tout en garantissant des réponses sub-secondes, mathématiquement exactes et auditables.