"Revenue" is on the executive dashboard. Someone asks whether it is gross or net, whether refunds are in it, and who decided. In most organisations that question is answered by finding the person who built the tile. In InsightCompose it is answered by an ⓘ on the tile, and this is about what has to be true underneath for that ⓘ to be honest.

Three things that need to be the same thing

A governed number has three lives. It is a word the business uses — a glossary term with a definition in prose. It is a rule — a metric with an expression, the grain it is valid at, the filters it always carries, and the ways it is computed wrong here. And it is a value — the thing on the tile, produced by a query against the warehouse. BI tools keep those in three different places, and the links between them live in people's heads.

flowchart LR
  T["Glossary term
revenue
'sum of the transaction total, before refunds'"] -- "defines" --> M["Metric
total_revenue
expression · grain · filters · traps
accepted by a person"]
  M -- "computed with" --> R["Every generated query
records which definitions
and which vocabulary it used"]
  M -- "shown on" --> D["Dashboard tile
pinned to the metric,
or inferred from its query"]
  D -. "ⓘ" .-> M
  M -. "ⓘ" .-> T
  style T fill:#fdf6ec,stroke:#e6c79c
  style M fill:#e6f7f2,stroke:#9fd8c9
Term ↔ metric, run ↔ metric, tile ↔ metric. Each link is a field, not a convention.

1. The term and the metric

A metric carries the glossary term it defines. It is set by a person on the Metrics tab, matched automatically when a metric's name or synonym equals a term's name, or created the other way round: when a glossary term's description reads like a formula ("revenue divided by the number of transactions"), alignment opens it as a proposed metric with the definition already filled in and the expression left for someone to write and smoke-test. The term's own page shows the metric that defines it, the columns it is bound to, and the dashboards it appears on.

Glossary → a term's sheet
A glossary term's details sheet with a Governance section: the accepted metric that defines it and its expression, the warehouse columns the word is bound to with their status, how many generated queries used it, and the dashboard it is shown on.
The word's side of the link: what defines it, what enforces it, where it is shown.

2. The run and the metric

When the engine writes a query it is told the agreed definitions the question invokes — only those, so a large metric layer costs nothing per question — and the confirmed vocabulary that applies. Every run now records which ones it used. That sounds like bookkeeping. It is the thing that makes the next section possible, and it is what lets a reviewer ask "which answers depended on the old definition of revenue?" and get a list rather than a shrug.

SQL Engine → Metrics
The Metrics tab: an accepted definition of total revenue with its expression and three traps, the glossary term it defines, and its usage — one generated query computed with it, shown on the Store performance dashboard. Below, two definitions proposed from the glossary, awaiting an expression.
The rule's side: expression, traps, the term it defines, and where it has been used.

3. The tile and the metric

A dashboard panel names the metric it shows. Where nobody pinned one, it is inferred: the panel's Data API is a saved query, and if that query's SQL contains an accepted metric's expression, the link is drawn and marked inferred so a reader knows the difference. Either way the ⓘ on the tile opens the whole chain — definition, expression, grain, filters, traps, the glossary term, and the Data API with its owner and version.

A dashboard tile, ⓘ
A revenue KPI tile on a store performance dashboard with its information popover open: the accepted metric total revenue, its definition, the SQL expression, grain and unit, three traps in amber, the glossary term it defines, and the Data API behind the tile with its owner.
The value's side. Nothing here is typed into the dashboard; it is read from the links.

Why the cache is now a governance feature

The engine remembers good answers. A question close enough to one it has answered before reuses that SQL — validated and executed again, but not regenerated — which is how a recurring question comes back in three or four seconds with no model call. The obvious objection is that a remembered answer is only as current as the knowledge it was written with.

Because runs record their lineage, that objection has a mechanical answer. When a person accepts a metric, the cached answers written without it are retired. When a curator confirms or rejects a term, the cached answers that embody the other reading are retired. And a stored query is never reused for a question that invokes a definition the query predates. The cache is not a shortcut around governance; it is bound by the same links as everything else.

What it does not do, yet

The chain covers questions, saved queries, dashboards and metrics. A Data API written by hand has no generation run behind it, so its metric is inferred from its SQL only. Discovered insights and notebooks are not on the chain yet. And the engine trusts a metric's expression as written — the run records that the definition was offered; the verifier checks the numbers; nothing yet re-parses the SQL to prove the formula was used verbatim. We would rather say that than imply otherwise.

The principle

A number you cannot trace is a number you cannot defend. Make the term, the rule and the value point at each other as data — then a dashboard can explain itself, and so can the cache.

Read next

Teaching the engine your vocabulary — how the glossaries you already wrote become the rules the engine enforces, and what a machine is never allowed to decide alone.