Keeping metric definitions as code under review like any other change
Metric definitions as code means every measure lives in a version controlled file with a named owner and a changelog. A change to the rebooking window or the staff badge filter then arrives as a diff someone approved, with the before and after values recorded, instead of an unexplained movement in a published number.
The rebooking rate in the November board pack was 62.6 per cent. The same rate in the February pack, for the same edition, is 69.3 per cent. Nothing about the show changed. No contracts were backdated. Somebody moved the rebooking window from 90 days after close to 120 days, and did it inside a dashboard, in a field with no history.
Metric definitions as code is the practice that turns that into a diff. The definition of every measure lives in a file, the file lives in version control, and changing what rebooking means requires a commit with an author, a reviewer and a message explaining why. The change still happens. It stops being invisible.
The 90 to 120 day change, worked through
Put the arithmetic on the page, because the size of the effect is the point.
The edition closed with 580 exhibitors on the floor. Counting signed rebooking contracts received within 90 days of close gives 363 exhibitors, which is 62.6 per cent. Extending the window to 120 days picks up a further 39 contracts, for 402 exhibitors, which is 69.3 per cent.
The rate moved 6.7 percentage points on a definitional change alone. Both figures are correct measurements of something. Only one of them was the number in the November pack, and the difference between them is larger than the year-on-year movement most shows are trying to detect, which is what makes an unlogged definitional change so corrosive. A 6.7 point swing that came from the data would be the most important thing in the pack. A 6.7 point swing that came from a window setting looks identical on the chart.
The commit that makes this survivable is small. One line in a YAML file changes from 90 to 120. The message says who asked for it, why 120 is the better window, and what the rate becomes on the last closed edition under both definitions. Six months later, when somebody asks why the rate jumped, the answer takes one command instead of one week.
What does keeping metrics as code actually require?
Not much, and the requirements are worth stating precisely because tools get bought to satisfy a list that only has four items on it.
The dbt documentation, current in 2026, states the file rule directly for its own metric layer: "Define metrics in YAML files within your dbt project, and not in a config block on a model." The same documentation names five metric types, simple, cumulative, derived, ratio and conversion, which is a useful reminder that a rebooking rate is a ratio metric with a numerator and a denominator that each need their own definition.
The Cube documentation, also current in 2026, describes the surrounding pattern as centralising "metric definitions, joins, access rules, and caching upstream of every BI tool, application, and AI agent that queries the data." The tool matters less than the four properties any of them give you.
- A text file. Diffable, greppable, reviewable in the same interface as the transformations.
- A history. Every change has an author, a timestamp and a message.
- A named owner in the file itself. Not in a wiki, not in a spreadsheet somebody maintains.
- One place the consumers read from. A definition in version control that a dashboard ignores is documentation, and documentation drifts.
Notice that none of the four says anything about when the number gets computed. A definition held as code can be materialised into an aggregate table overnight or resolved on every dashboard load, and that choice is orthogonal to whether it is reviewable, which is the subject of transform time versus query time metrics.
What does a metric review actually check?
A metric pull request is a different review from a code pull request, and reviewers who treat it as one miss most of what matters. The SQL is usually fine. The question is whether the meaning changed and whether anyone was told.
The five things worth checking on every metric change:
- Did the population change? Adding a filter for badge type changes who is counted, which is a bigger change than it looks in a diff of two lines.
- Did the time boundary change? Windows, cut-offs, and whether a period is inclusive at both ends.
- Did the denominator change? Ratio metrics break quietly here. Exhibitors on the floor, exhibitors contracted, and exhibitors invoiced are three different denominators for rebooking and they differ by more than most people assume.
- What is the before and after on a closed edition? The author should paste both numbers into the pull request. If they have not computed them, they do not know what they are changing.
- Who has already published the old number? A change to a metric that appears in a board pack has a communication step attached to it.
That fourth item is the one with real teeth. Requiring the author to state the effect on a closed edition, in the pull request, turns an abstract argument about definitions into a number people can react to. It also catches the changes that were supposed to be neutral and were not.
One more thing belongs in the diff and it is the cheapest of all: the query that produced the before and after figures. A reviewer holding the query can check the claim in thirty seconds against the warehouse. A reviewer holding only two numbers is being asked to trust them, and a review that runs on trust is a formality with a green tick on it.
Comparing every published measure across every edition, rather than one measure on one edition, is the heavier version of the same instinct, and it belongs to regression testing a warehouse refactor.
Who owns a metric?
Two people, and the second one is the one organisations skip.
The technical owner maintains the definition, keeps the SQL correct and answers questions about how it computes. Usually the analytics engineer who wrote it.
The business owner rules on what it should mean. When exhibitor relations wants rebooking measured at 120 days and finance wants 90, the business owner decides, and their name is in the file so that the next person to raise the question knows where to take it. On an event portfolio the business owner for rebooking is normally the exhibition sales director, and for verified attendance it is normally whoever signs the audit submission.
Ownership by a team is ownership by nobody. A metric owned by "Data" gets changed by whoever is nearest the keyboard, which is exactly the state the practice is meant to end.
Versioning without breaking last year's report
Once definitions have history, you can do something better than argue about which version is right. You can keep both, deliberately.
Three patterns cover almost everything.
Restate. The new definition is simply better, so history is recomputed under it and every published figure that used the old one is reissued with a note. Honest, expensive, and correct when the old definition was wrong.
Fork the name. The old measure keeps its name and its definition, the new one gets a new name, and both are served. Rebooking rate at 90 days and rebooking rate at 120 days become two measures, which is the same conclusion the semantic layer reaches whenever two definitions are genuinely incompatible.
Date the change. The definition carries an effective date, editions before it use the old rule and editions after it use the new one, and any chart crossing the boundary carries a marker. Cheapest of the three and the most likely to be forgotten by whoever reads the chart in two years.
None of the three is free. Restating 40 editions under a new rebooking window means recomputing every published rate and telling everyone who has already quoted one, which for a portfolio with an annual report and eight post-show packs is a fortnight of coordination. Forking the name doubles the number of measures people have to choose between, and within two years somebody picks the wrong one for a board slide. Dating the change is cheap on the day and leaves a discontinuity in every trend line that crosses it, which somebody will have to explain repeatedly for as long as the chart exists.
Whichever you pick, the changelog entry is the artefact that survives. Date, owner, old definition, new definition, effect on the most recent closed edition, and the decision about history. Five fields, one row per change, and after two years it is the most valuable file in the repository.
Where this stops
Version control records what changed. It does not make anyone read it.
A repository full of immaculate metric definitions with a changelog nobody opens produces the same February surprise as no repository at all, one step further from the person holding the board pack. The practice only works if the changelog is surfaced where the numbers are consumed, which means the report itself carries the definition version it was built from and the date that version took effect.
There is also a boundary the code cannot police. A definition can be reviewed, approved and wrong, because reviewers check consistency and rarely check whether the measure describes the world. Nothing in a pull request catches the fact that counting badge scans in a hall with two broken readers understates attendance. Definitional rigour and measurement validity are separate problems, and having solved the first one thoroughly makes it easy to believe you have solved the second.
Start with one file. Take the metric that caused the last argument in your organisation, write its definition down in the data platform repository with the owner's name at the top, and put the current value on the last closed edition underneath it. The next time it changes, you will have something to diff against, which is the entire trick.
Questions people ask about metric definitions as code
- What does it mean to keep metric definitions as code?
- The definition of each measure lives in a text file in the same repository as the transformations, so it has a commit history, an author, a reviewer and a diff. Changing what a metric means becomes a pull request rather than an edit inside a dashboard that leaves no trace anyone can find later.
- Who should own a metric definition?
- A named business owner who can rule on what the measure should mean, paired with a named technical owner who maintains the code. Ownership by a team is ownership by nobody. The owner's name belongs in the definition file itself, so anyone reading the metric can see who to ask without searching a wiki.
- How do you change a metric without breaking last year's reports?
- Record the change with its effective date and the before and after values on the same closed edition, then decide deliberately whether history is restated or the old definition is kept under its own name. What breaks trust is a definition that changes silently, so a published figure moves and nobody can say when or why.
Related reading
- A semantic layer for event metrics so verified attendance means one thing
- Transform time versus query time metrics for a portfolio reporting stack