Votre agent BigQuery ne se trompe pas de SQL, il se trompe de sens

Un agent qui interroge l’export GA4 sans contexte devine. Il devine que event_params contient ce que son nom suggère, que events_* est la seule source, que « conversion » veut dire purchase. Parfois il tombe juste. Ce n’est pas rassurant.

Ma position tient en une phrase : le gain se joue dans la couche sémantique, pas dans le choix du modèle. Je n’ai trouvé aucun chiffre public fiable à vous vendre. Je vous donne donc un protocole pour le mesurer chez vous.

Ce que l’agent ne peut pas deviner dans l’export GA4

Il y a trois angles morts.

Le premier, ce sont les paramètres custom. L’ensemble des paramètres stockés dans event_params est propre à chaque implémentation, d’après l’aide GA4. Votre step_id ou votre content_group n’existe dans aucun corpus d’entraînement.

Le deuxième, c’est la table qui fait foi. Une table events_YYYYMMDD est créée chaque jour. Avec le streaming s’ajoute events_intraday_YYYYMMDD, supprimée en fin de journée une fois la table du jour complète. Un agent qui additionne les deux compte deux fois.

Le troisième, c’est le grain. Une ligne, c’est un événement, ni une session ni un utilisateur. Compter des lignes en croyant compter des sessions reste l’erreur la plus fréquente.

Knowledge Catalog : ce qui a changé de nom, ce qui n’a pas bougé

Knowledge Catalog est l’ancien Dataplex Universal Catalog. Les release notes de Google indiquent que le renommage date du 10 avril 2026. La page de transition précise que les noms d’API, de bibliothèque client, de CLI et d’IAM restent inchangés. Vos scripts Terraform ou gcloud existants ne cassent donc pas. Google présente aussi le produit comme un graphe de contexte actif plutôt qu’un registre passif. C’est un positionnement commercial, pas une mesure.

Le point utile pour vous se trouve dans la documentation des data agents. Les termes de glossaire définis dans Knowledge Catalog s’appliquent globalement aux ressources BigQuery. Les termes créés localement dans un agent restent dans BigQuery et n’apparaissent pas dans le catalogue. Définissez donc « session engagée » une seule fois, côté catalogue, et tous vos agents en héritent.

Google affirme que la fiabilité de ses agents conversationnels vient de ce contexte : glossaires, profile scans, requêtes vérifiées et instructions personnalisées. C’est l’affirmation de l’éditeur. Je n’ai pas vu de benchmark indépendant, et ces fonctions évoluent vite, alors relisez la documentation avant de bâtir dessus.

Que documenter, dans quel ordre

Commencez par une table dérivée plutôt que par l’export brut. La doc parle de tables, vues ou UDF comme sources de connaissance. Je n’ai pas trouvé de confirmation qu’un wildcard events_* s’y comporte proprement. C’est donc un choix de prudence de ma part, pas une exigence documentée.

Aplatissez les paramètres que vous utilisez vraiment, un par colonne, en date partitionnée. Décrivez chaque colonne avec son unité, sa valeur type et son piège. Gemini propose des descriptions automatiquement, mais relisez-les : il ne sait pas ce que votre équipe a mis dans ctype.

Écrivez ensuite le glossaire (utilisateur actif, conversion, session engagée), puis deux ou trois requêtes vérifiées pour les questions du lundi. Ces requêtes, anciennement « golden queries », servent de référence à l’agent. C’est aussi là que vous encodez les jointures.

Voici le flux que je vise.

export GA4 (events_YYYYMMDD, intraday exclu)
   ↓ requête planifiée
table aplatie, partitionnée par date, 1 ligne = 1 événement
   ↓
Knowledge Catalog : descriptions de colonnes + glossaire métier
   ↓
agent de données : instructions + requêtes vérifiées
   ↓
SQL visible + sources de contexte citées

La dernière ligne compte. Google documente que l’agent affiche son raisonnement, le SQL généré et les sources de contexte utilisées. C’est votre outil de débogage.

Comment mesurer le gain sur dix questions

Prenez dix questions que votre direction pose vraiment : sessions par canal sur sept jours, taux de conversion du checkout, utilisateurs porteurs d’une user property donnée, revenu par campagne. Écrivez vous-même le SQL de référence et figez le résultat attendu.

Lancez d’abord l’agent nu, avec la seule table et sans description. Relancez chaque question trois fois, car la génération n’est pas déterministe. Puis recommencez après avoir documenté. Notez pour chaque réponse si le chiffre égale la référence, et relevez les octets scannés.

Mon hypothèse, que ce protocole doit valider ou infirmer : les écarts se concentrent sur les paramètres custom et sur la table qui fait foi, beaucoup moins sur la syntaxe SQL.

Quand « le dernier jour » coûte toute la table

Demandez à un agent « les chiffres d’hier ». Il peut écrire WHERE _TABLE_SUFFIX = (SELECT MAX(...) ...). Le résultat est juste, mais la facture couvre tout l’historique. La documentation BigQuery est claire : les filtres sur _TABLE_SUFFIX qui n’utilisent pas d’expression constante ne limitent pas le nombre de tables scannées. Elle donne d’ailleurs un exemple avec une sous-requête sur INFORMATION_SCHEMA.

-- scanne tout : le filtre dépend d'une sous-requête
WHERE _TABLE_SUFFIX = (SELECT MAX(...) FROM ...)

-- n'ouvre que ces sept tables
WHERE _TABLE_SUFFIX BETWEEN '20261101' AND '20261107'

Imposez des bornes littérales, ou calculées à partir de CURRENT_DATE(). Cette dernière forme est très répandue, mais la doc ne l’illustre pas dans l’extrait que j’ai lu, donc confirmez-la par un dry run. Inscrivez la règle dans les instructions de l’agent. Si votre table dérivée est partitionnée, activez l’option « require partition filter », que Google documente : elle oblige les requêtes à inclure un filtre de partition. L’agent ne pourra plus scanner sans filtre, même s’il essaie.

À faire ce soir

Écrivez le SQL de référence de vos dix questions et lancez l’agent nu. Le score vous dira quelle colonne documenter en premier. Quel paramètre custom de votre export serait le premier à piéger un collègue qui arrive demain ?