Same metric, asked from a chat window, a dashboard tile and an API call. Same number three times.
On Tuesday we mapped the semantic layers every major platform now ships, and ended on an uncomfortable point: a definition that is consistent inside one platform is still only consistent inside that platform. Three governed numbers that disagree with each other aren’t governance. They are a more confident version of the old problem.
This post is the practical answer: how to build a single source of truth for metrics that people, dashboards and AI agents all share. We’ll take one metric, ask for it three different ways in Equative Insights OS, and show what happens underneath. Then we’ll change the definition once and watch all three follow.
One metric, one definition: win rate
We picked a win rate because every commercial team has one and very few agree on it. Sales may count every opportunity that reached proposal. Finance may only count deals that turned into booked revenue. Operations may want duplicates and test records out. Each version is defensible. Running all three at once is how a pipeline review turns into an argument about arithmetic.
In Equative Insights OS the definition is written down exactly once: closed-won opportunities divided by all closed opportunities in the period, excluding records flagged as duplicates or internal tests. In MetricFlow, the open-source engine behind our semantic layer, that becomes a ratio metric in a reviewed YAML file:
Three ways to ask, one answer
-
1. A question in Client IQ A relationship lead types: "What was our win rate for mid-market clients last quarter?
" The model reads the intent (segment: mid-market; period: last full quarter, Q3 2026) and picks win_rate from the metric catalogue. It does not write SQL. MetricFlow compiles the request, the warehouse runs it, and the answer comes back as 34.2% (illustrative), with the trace naming the metric and the definition it came from. -
2. A dashboard tile
The Head of MI's quarterly pipeline dashboard has a tile for win rate by segment. The tile holds no formula of its own. It asks the semantic layer for win_rate, grouped by segment, for Q3 2026. The mid-market row reads 34.2%. -
3. An API request from another system
A planning tool, or an agent running on your CRM, requests the same metric by name: win_rate, filtered to mid-market, for the last full quarter. It gets back 34.2%, plus a reference to the definition that produced it.
| Surface | Who Is Asking | What It Sends | What Runs | Result |
|---|---|---|---|---|
| Client IQ | A person, in plain English | Metric win_rate, chosen by the model from the catalogue |
SQL compiled by MetricFlow | 34.2% |
| Dashboard | A person, looking | Metric win_rate by segment |
The same compiled SQL | 34.2% |
| API | Software or an agent | Metric win_rate by name |
The same compiled SQL | 34.2% |
The point isn’t that the numbers match. It’s that nobody had to check whether they would. There is no reconciliation step because there is nothing to reconcile: three surfaces, one request shape, one statement, one number.
Change it once, and everything follows
Now the realistic part. Someone in finance notices that opportunities which were reopened and closed again are being counted twice in the denominator. The definition is wrong, and it is understating win rate.
In most organisations, fixing this means finding every place win rate is calculated: a calculated field in the BI tool, a saved query behind the board pack, and whatever an assistant or agent worked out for itself. Fix one and the other two now disagree with it by exactly the size of the fix. That is the worst kind of discrepancy, because each number looks right on its own.
In Equative Insights OS, the fix is a pull request against one file. Finance and the data owner review it. It is merged with a name, a date and a reason. On the next query, the chat answer, the dashboard tile and the API response all return the corrected figure, 36.0% (illustrative). Nobody rebuilt a dashboard, rewrote a prompt or emailed the teams consuming the API. The trace now shows the new definition version and who approved it.
What this means if you never open a YAML file
Most people who rely on these numbers will never read the definition file, and they shouldn’t need to. What changes for them is simpler:
- One argument per metric, not one per report. When win rate is disputed, the discussion happens once, about the definition, and the outcome applies everywhere.
- Every change has a record. "Who changed this number?" has an answer with a name and a date attached.
- Agents get the same answer people do. As more of your metric requests come from software rather than analysts, each agent asks for the governed definition instead of inventing its own at machine speed.
What it doesn't do
A semantic layer doesn’t make a bad definition good. It makes it visible, so the people who know the business can fix it once. It doesn’t remove the need for sales and finance to agree; it gives that agreement one place to live. And getting the same definitions into tools outside Equative depends on how widely the emerging open standard, Apache Ossie, is adopted. That is next Tuesday’s subject.
Define once. Answer anywhere. Change it in one place, with a name on the change.
Frequently asked questions
-
What is a single source of truth for metrics?
It is one place where each business metric is defined, so every dashboard, report, AI assistant and API returns the same number for the same question. In Equative Insights OS that place is a MetricFlow semantic layer, versioned in git and reviewed like code. -
How does a semantic layer keep AI answers consistent?
The AI chooses a defined metric by name instead of writing its own SQL. The semantic layer compiles the query from the governed definition, so the answer matches every other surface that asks for the same metric. -
What happens when a metric definition changes?
The change is made once, in a pull request that finance and data owners review. Every surface uses the new definition on its next query, and the change is recorded with a name and a date. -
Do we need to replace our BI tool or CRM?
No. Dashboards, CRM agents and other systems keep running. They request metrics from the semantic layer instead of each holding its own copy of the calculation.
