Versioned metric definitions: the governance that makes self-service analytics safe

Self-service analytics has a predictable failure. Three teams ask the same question, get three numbers, and the meeting is about which number is right rather than what to do. The cause is never the tool. It is that revenue meant three different things. This guide sets out the governance that fixes it: one definition per metric, versioned, applied in code, with scope in the data layer and an audit trail on every answer.

One definition, in code

A metric definition is a formula over the underlying columns, with filters, grain and owner:

The definition is applied by a function, and every screen and every assistant answer calls that function. Nobody recomputes revenue in a spreadsheet, because there is nowhere for a second definition to live.

Versioning

When finance changes net revenue to exclude a new category of credit, v5 takes effect on a date. From that date, every answer uses v5 and says so. Answers given before it used v4 and say so. The question "why is last quarter's number different in this deck" has an answer: the definition changed, here is what changed, here is the number under each.

The registry keeps every version. Nothing is overwritten.

Scope in the data layer

A rep asks "what is my coverage". The system resolves "my" to the rep's account identifiers before any row is read, in the data layer, from the directory. The coverage function receives only those rows. The model that phrased the answer never saw the other reps' accounts and cannot leak them, because there is nothing to leak.

The alternative, telling a model "only answer about this rep's accounts" while giving it all the rows, is a permission the model can misread. The difference matters to compliance and it matters in a bank.

The audit trail

Every answer records:

• who asked, and when
• the question as asked
• which tools ran, with their inputs
• which definition version each tool used
• which rows the tools read, or a reference to them
• the answer as given

That trail is exportable, and it is what turns "the assistant said" into "the coverage function, v2, on these 214 rows, said". Finance can check it; a regulator can read it.

A worked example

Two answers to "what was net revenue in Q2", one asked in June, one in August.

The two numbers differ by the credits v5 excludes. Both are right under their definition. The registry says which is which, and the August answer can note that the June figure was computed under v4.

Where it goes wrong

Definitions in a wiki. A definition that is documented but not executed is a suggestion. The function is the definition.

Versions without effective dates. A change with no date cannot be applied to history. Every version has one.

Scope in the prompt. See above. It is the difference between a guarantee and a hope.

Trail without rows. An audit trail that records the question and the answer but not the rows cannot be rerun. Record the rows, or a stable reference to them.

Governed, then open

Once the registry exists and scope is in the data layer, self-service can be opened to every team, because every answer agrees with finance and every answer can be traced. Covirage runs on this model. The metrics governance page describes it.