Metric Change Management

Metric change management is the practice of altering a metric definition without destroying the ability to compare against what was reported before. It exists because of a property most people never think about: metrics are usually computed on demand, so editing the definition silently changes every historical figure it produces.

A semantic layer makes this concrete. MetricFlow is “a SQL query generation tool” — the number is produced when asked, from the current definition. Change the definition on Tuesday and Monday’s figure changes too, with nothing on the chart to say so. Someone’s quarterly deck stops reproducing and they assume they misremembered. Product descriptions here follow the dbt and Cube documentation, checked in September 2026.

Three decisions

• Run both definitions for a period. Publish the new one alongside the old with the gap quantified, so people see the size of the change while the old number is still on the page. This is the step that turns “the number moved” into “the definition moved, by this much.”
• Announce with the delta, not the rationale alone. “Revenue will read about 3% lower from April because refunds are now netted” is usable. “We improved the revenue definition” tells nobody whether their target, forecast, or commission is affected.
• Settle whether history is restated. Recomputing the past makes the trend comparable and invalidates every figure already published. Leaving it creates a visible break that someone will read as a business event. Either is defensible; silence is not. Marking the break on the chart costs nothing and prevents the wrong story.

The third decision is the one that gets skipped, usually because whoever makes the change is thinking about correctness rather than about the twenty documents that quote the old number. A useful default: restate history for internal trend analysis, and never restate a figure that has been reported externally without saying so explicitly.

Why definitions as code helps

When a definition lives in a dashboard, a change is an edit someone made and nobody reviewed. When it lives in version-controlled configuration — dbt is explicit that you should “Define metrics in YAML files within your dbt project, and not in a config block on a model” — a change is a diff with an author, a date, and a reviewer.

That gives three things change management needs: the history of what the definition was on any past date, a place to require review for company-level metrics, and a natural separation between meaning and appearance. Renaming a metric for display changes label, “the display value in downstream tools,” and cannot move the number — which is worth knowing, because “we just renamed it” is otherwise a claim nobody can check.

Where consumers are other teams or systems, the promise about what may change and with how much notice belongs in a data contract alongside the schema guarantees. A consumer-facing abstraction helps too: Cube’s views provide “a layer of abstraction that makes it easier to manage changes to the underlying data model,” letting the physical tables be reshaped without a change reaching every report.

History can change without you touching the definition

Two paths produce the same symptom — the past moved — with no metric change to point at, and both surprise people who thought change management was about definitions only.

• Dimension attributes changed. A metric grouped by customer tier or product category depends on attributes that themselves change. Recomputing last year’s revenue by tier with today’s tiers restates the past silently — the choice between current and historical attribute values is what slowly changing dimensions exist to make explicit.
• Source data was reloaded. A backfill, a late-arriving correction, or a fixed pipeline bug changes the inputs. The definition is identical and the number is not.

Both argue for the same operational habit: record what changed and when, in one place people can consult when a number they remember no longer matches. A dated changelog per metric — what changed, the measured delta, who decided, whether history was restated — answers in seconds the question that otherwise consumes an afternoon of investigation.

How much process is enough

Scale the ceremony to the metric, not to the organization. A metric one team uses to run its own work should change whenever that team finds it useful, with no announcement. A metric reported outside the team needs a named owner, a review, and the three decisions above.

The test for which category a metric is in is not its importance but its audience: does anyone outside the team make a decision with it? Applying heavyweight process to every metric produces a queue and drives people to compute their own numbers outside the layer — which recreates the disagreement the governance was meant to end.

Keeping the human-readable version of each definition current matters as much as the code. A business glossary that still describes last year’s definition is worse than none, because it is the artefact non-technical readers trust.

How change management fits with definitions, the semantic layer, and the boundary between central and team metrics is worked through in Whose Revenue Number Is Right?.

References: dbt Documentation, Creating metrics; dbt Documentation, About MetricFlow; Cube Documentation, Data modeling overview.