Comment fonctionnent les requêtes, et leurs erreurs
Comprendre le pipeline de requête rend chaque message d'erreur évident — et la plupart évitables par la curation.
Du composant au SQL
Aucun utilisateur ni IA n'écrit de SQL directement contre votre entrepôt. Chaque demande — une configuration de graphique, un tableau, une question à Axi — passe par le même pipeline :
- Résolution sémantique — les champs demandés sont résolus sur les modèles sémantiques de la connexion : dimensions, mesures, métriques et leurs sources (colonnes ou expressions).
- Résolution du chemin de jointure — si les champs couvrent plusieurs modèles, le moteur parcourt les clés déclarées pour trouver le chemin. Il doit en exister exactement un ; zéro ou plusieurs est une erreur, pas une supposition.
- Garde-fous — le plan est validé : pas de démultiplication qui compterait une mesure en double, grains présents où il faut, valeurs de filtres du bon type.
- Compilation SQL — le plan validé compile dans le dialecte SQL de l'entrepôt et s'exécute côté serveur, avec des identifiants tirés de Secret Manager. Les résultats reviennent au composant ; le SQL reste visible via le bouton SQL des éditeurs de graphique et de carte.
Deux propriétés en découlent : les requêtes sont en lecture seule par construction, et un résultat faux est traité comme pire qu'aucun résultat — quand la justesse ne peut pas être garantie, la requête est refusée avec une explication.
Référence des erreurs
Ce que voient les utilisateurs (en langage clair, avec le champ en cause nommé), la cause technique, et la correction durable :
| Message (abrégé) | Cause technique | Correction durable |
|---|---|---|
| Ce total serait compté plusieurs fois | La jointure inverse démultiplierait une mesure additive | Repenser la jointure inverse, ou utiliser une mesure sûre sous cette traversée |
| Ces tables ne sont pas reliées | Aucun chemin de jointure entre les modèles | Déclarer la clé manquante |
| Plusieurs façons de relier ces tables | Chemin de jointure ambigu | Faire préciser la relation par le composant ; envisager de masquer une clé redondante |
| Ce champ ne peut pas être relié aux données de votre métrique | Dimension inatteignable depuis le modèle de la métrique | Choisir un champ apparenté, ou ajouter la clé qui le rend atteignable |
| Pour combiner des métriques de sources différentes, groupez par des champs partagés | Requête multi-faits avec dimensions non partagées | Ne grouper que par des dimensions communes à tous les faits |
| Ce graphique combine trop de sources | Trop de modèles de faits dans une requête | Découper en composants séparés |
| Pas de champ de date pour tracer dans le temps | Le modèle n'a pas de dimension temporelle | Déclarer une dimension temporelle ; définir un axe temporel principal |
| Ce champ temporel a besoin d'un niveau de groupement | Grain requis pour une dimension temporelle | Choisir un grain (jour, mois, année…) |
| Un total cumulé / une comparaison de période a besoin d'un groupement de date | Métrique cumulative ou à décalage sans groupement temporel | Ajouter un champ temporel au composant |
| Vient de données imbriquées impossibles à résumer ainsi | Traversée inverse dans un tableau imbriqué | Aplatir le tableau en modèle virtuel |
| Cette métrique / ce champ / cette table n'existe plus | Élément renommé ou supprimé après la construction du composant | Restaurer ou re-pointer ; traquer les éléments orphelins après les rafraîchissements de schéma |
| Un filtre a le mauvais nombre de valeurs / le mauvais type | Arité ou type de filtre incorrect | Corriger le filtre |
| Cette formule personnalisée n'a pas pu être comprise | Expression ad hoc non analysable | Corriger la formule ; promouvoir les récurrentes en métriques organisées |
Lire les erreurs comme des signaux de curation
Les erreurs récurrentes dessinent la carte de ce qu'il faut organiser ensuite :
- Beaucoup de « tables non reliées » → des clés manquent.
- Beaucoup de « compté plusieurs fois » → une jointure inverse activée là où il ne fallait pas, ou une mesure qui réclame une fenêtre semi-additive.
- Des erreurs de formule répétées dans la même équipe → une métrique demande à exister.
Le tableau d'utilisation montre les taux d'erreur des exécutions IA par membre — un pic est presque toujours l'un des motifs ci-dessus, pas un problème de plateforme.