Cas data : rendre les métriques, tables et dashboards lisibles par les agents

Pourquoi les équipes data sont un cas naturel pour OKF ?

Les équipes data travaillent déjà avec des artefacts structurés: schémas, tables, modèles, jobs, métriques, notebooks, dashboards, catalogues, tests et contrats. Elles savent que la donnée brute ne suffit pas: il faut du contexte pour comprendre le grain, la formule, les exclusions, les propriétaires et les limites.

OKF s'insère naturellement dans cette culture. Il ne demande pas de remplacer BigQuery, Snowflake, dbt, Looker, Metabase ou un data catalog. Il permet de représenter la connaissance qui entoure ces outils dans un format lisible par les humains et consommable par des agents.

La promesse concrète n'est pas de refaire la stack data. C'est de rendre les questions data plus fiables: quelle table fait foi ? comment calcule-t-on cette métrique ? quel dashboard est officiel ? quelle décision métier a changé la définition ? quelle source peut être citée ?

Le problème : les chiffres existent, mais le contexte manque

Dans beaucoup d'entreprises, les chiffres existent déjà. Le problème est que leur contexte est éclaté: une formule vit dans un modèle dbt, une exception dans un ticket Slack, un owner dans un catalog, une explication dans un dashboard, une décision dans une réunion et une règle qualité dans un runbook.

Un agent peut retrouver une table ou un passage de documentation, mais cela ne garantit pas qu'il comprenne le grain, les exclusions, la fraîcheur, la source officielle ou le niveau de confiance. C'est exactement là qu'un bundle data OKF devient utile.

Le but est de créer une couche qui relie les assets techniques au sens métier: tables, métriques, dashboards, notebooks, décisions, owners, sources et règles qualité.

Ce qu'un bundle data OKF doit représenter

Un bundle data ne doit pas recopier tout le warehouse. Il doit documenter les objets data qui créent le plus d'ambiguïté ou de valeur. Une bonne V1 commence souvent par une famille de métriques ou un domaine analytique: revenue, activation, churn, support, acquisition ou qualité produit.

Les concepts de base sont assez stables: datasets, tables, métriques, dashboards, notebooks, modèles, décisions, owners, sources et playbooks qualité. Chacun doit répondre à une question pratique pour un humain ou un agent.

Par exemple, `metrics/monthly_recurring_revenue.md` explique une métrique, `tables/orders.md` décrit son grain, `dashboards/revenue-dashboard.md` pointe vers la vue officielle, et `decisions/pricing-v2.md` explique pourquoi certaines exclusions ont changé.

Tables et datasets : documenter le grain, les colonnes et les jointures

Pour un agent, une table n'est pas seulement un schéma. Il doit savoir ce que représente une ligne, quelles colonnes sont fiables, quelles clés permettent les jointures, quelles limites existent et quelle ressource technique fait foi.

Un concept comme `tables/orders.md` peut décrire le grain de commande, les colonnes critiques, les relations avec `customers` ou `subscriptions`, les pièges connus, les règles de fraîcheur et les métriques qui dépendent de cette table.

Le fichier OKF ne remplace pas la documentation technique du warehouse. Il pointe vers elle avec le champ `resource` et ajoute le contexte métier que les agents doivent lire avant d'analyser.

Métriques : rendre les définitions calculables et discutables

Les métriques sont souvent le meilleur point de départ. Une métrique mal définie crée des écarts entre finance, sales, produit et data. Un agent qui explique mal le MRR, l'activation ou le churn peut produire une réponse convaincante mais fausse.

Un concept `Metric` doit préciser la définition, la formule, le grain, les exclusions, la source officielle, les tables concernées, les dashboards associés et les décisions qui ont modifié la règle.

L'objectif n'est pas seulement que l'agent retrouve la métrique. Il doit pouvoir expliquer pourquoi elle est calculée ainsi, quelles limites appliquer et quelles sources citer en cas de désaccord.

Dashboards : relier les vues aux sources et aux décisions

Un dashboard est souvent traité comme une source de vérité, mais il ne dit pas toujours quelle table l'alimente, quelle métrique il expose, quelles décisions ont changé la définition ou à quelle fréquence il est rafraîchi.

Un fichier `dashboards/revenue-dashboard.md` peut indiquer les métriques affichées, les filtres par défaut, les audiences prévues, les limites d'interprétation, le lien vers l'outil BI et les concepts liés.

Cette documentation aide les agents à éviter une erreur fréquente: citer un chiffre sans savoir s'il vient d'un dashboard officiel, d'une vue exploratoire ou d'une requête temporaire.

Notebooks, modèles dbt et jobs : garder le raisonnement proche du code

Les notebooks, modèles dbt et jobs contiennent souvent une partie du raisonnement analytique. Ils montrent comment une donnée est transformée, testée ou explorée. Mais ils ne sont pas toujours lisibles par une personne métier ou par un agent non spécialisé.

OKF peut référencer ces artefacts sans les dupliquer. Un concept `models/fct_orders.md` peut pointer vers le modèle dbt, expliquer son rôle métier, lister ses dépendances, citer les tests importants et relier les métriques qui l'utilisent.

La logique est la même pour un notebook: `notebooks/churn-analysis.md` peut expliquer l'objectif de l'analyse, les hypothèses, les sources, les résultats réutilisables et les limites à ne pas oublier.

Ownership et qualité : éviter le contexte sans responsable

Un contexte data sans owner devient vite dangereux. Si une métrique change, si un dashboard est obsolète ou si une table cesse d'être fiable, il faut savoir qui peut valider la correction.

Un bundle data OKF doit donc documenter les propriétaires, les règles de fraîcheur, les tests qualité et les playbooks d'alerte. Des fichiers comme `owners/revenue-analytics.md` ou `playbooks/freshness-alert.md` rendent ces responsabilités plus explicites.

Cette couche ne remplace pas les contrôles techniques. Elle rend les règles lisibles et actionnables pour les humains et les agents qui doivent travailler avec les données.

Exemple concret : bundle revenue analytics

Un premier bundle data peut viser un domaine très concret: le reporting revenue. Le problème typique est simple: plusieurs équipes parlent de revenu, mais elles ne s'appuient pas toujours sur la même formule, le même dashboard ou les mêmes exclusions.

La V1 peut contenir `datasets/sales.md`, `tables/orders.md`, `metrics/monthly_recurring_revenue.md`, `dashboards/revenue-dashboard.md`, `models/fct_orders.md`, `notebooks/churn-analysis.md`, `decisions/pricing-v2.md`, `owners/revenue-analytics.md` et `playbooks/freshness-alert.md`.

Le test agent consiste à répondre à une question réaliste: explique le MRR de ce mois, cite la source officielle, liste les exclusions, indique la table utilisée et signale les limites de fraîcheur ou de qualité.

OKF, data catalog et semantic layer : qui fait quoi ?

OKF ne remplace pas un data catalog. Un catalog mature gère l'inventaire, la gouvernance, les owners, les permissions, le lineage, la classification et parfois les workflows de certification. OKF peut référencer ces informations et les rendre plus faciles à consommer dans un bundle.

OKF ne remplace pas non plus un semantic layer. Le semantic layer sert à définir et exposer des métriques cohérentes aux outils downstream. OKF peut documenter la métrique, ses usages, ses décisions associées et les preuves qui permettent à un agent de l'expliquer.

La bonne architecture est complémentaire: le warehouse stocke les données, dbt transforme, le semantic layer standardise les métriques, le dashboard expose les vues, le data catalog gouverne, et OKF rend le contexte portable pour les agents et les humains.

Checklist d'un premier bundle data

Un premier bundle data doit rester petit. Choisissez une métrique ou un domaine analytique, puis vérifiez que les informations essentielles sont assez explicites pour être consommées par un agent.

Erreurs fréquentes à éviter

La première erreur consiste à documenter le schéma sans documenter le grain. Un agent peut lire des colonnes mais mal comprendre ce que représente une ligne.

La deuxième erreur consiste à définir une métrique sans exclusions. C'est souvent dans les exclusions que se cachent les désaccords entre finance, sales, produit et data.

La troisième erreur consiste à oublier les décisions métier. Une formule change rarement par hasard: pricing, packaging, politique commerciale ou segmentation peuvent modifier la métrique.

La quatrième erreur consiste à présenter OKF comme un remplacement du data catalog ou de dbt. OKF est plus crédible comme couche portable de contexte, pas comme nouveau système de gouvernance data complet.

Lire ensuite

Après le cas data, vous pouvez approfondir les exemples de fichiers, vérifier les règles de conformité ou comparer OKF avec le RAG pour comprendre comment indexer ce contexte.

Sources officielles et lectures utiles