Metric Definitions and the Semantic Layer

In an illustrative scenario, two teams present revenue for the same quarter and the numbers differ by four percent. Both queries are correct. One counts orders when placed and the other when shipped, one excludes internal test accounts and the other does not, and one nets refunds while the other reports gross. Nobody made a mistake, because nobody had written down which of those choices was the company’s answer.

Disagreement about definitions erodes trust: once two credible numbers exist, every subsequent number is provisional until someone reconciles it.

What a definition has to pin down

A name and a formula are not a metric definition. Five things have to be settled, and each one is where two teams diverge in practice.

Element	The question	How it goes wrong
Numerator	What exactly is being counted or summed?	Gross versus net, before or after discounts, which currency and at which exchange rate
Denominator	Counted against what population?	Active users, all registered users, or users who reached the page. Different populations answer different questions
Time	Which timestamp, in which timezone, and over what window?	Order date versus ship date versus recognition date; a “month” that runs on a fiscal calendar
Grain	One row per what?	Per order, per line item, per user, per session — see data grain
Inclusion rules	What is deliberately excluded?	Test accounts, internal orders, canceled transactions, one particular partner’s backfill

Tools encode roughly this shape. In dbt’s metric specification a metric requires a name and a type — one of “conversion, cumulative, derived, ratio, or simple” — and inclusion rules are expressed as a filter “applying filters to dimensions, entities, time dimensions, or other metrics during metric computation. Consider it as your WHERE clause.” The dbt and Cube references below describe the product models used here.

The inclusion rules deserve particular care because they are the part that decays. An exclusion added for a good reason two years ago — a partner whose data was broken that quarter — stays in the definition long after the reason is gone, and it is invisible to everyone reading the number.

Ratios break in a way sums do not

A ratio metric — conversion rate, margin percentage, error rate — carries a problem absolute counts do not have: it cannot be aggregated by adding. dbt’s specification reflects the structure by requiring two components, since ratio metrics “involve a numerator metric and a denominator metric,” and that is exactly the point: the ratio is derived, and what you store and transport are the components.

With one condition attached, because the components are not always additive either. Summing them across a dimension and dividing works when both are plain counts or sums over that dimension. It fails whenever either side counts distinct things: two users who both visit on Monday and Tuesday, a different one buying each day, give daily buyers and users of 1/2 and 1/2, which summed and divided reads 2/4 = 50% — while the period conversion rate over unique users is 2/2 = 100%. Balances behave the same way; they add across accounts and not across days. So the rule is to re-derive distinct counts over the whole period rather than adding daily ones, or to carry a mergeable state that supports union, and to fix a point-in-time rule for balances.

Averaging daily conversion rates weights days equally; dividing monthly converting sessions by monthly sessions weights each day by its session count. These answer different questions and can give different values. The gap depends on how both traffic and rates vary: if every day converts at 10%, even very uneven traffic gives 10% by either calculation. Choose the aggregation that matches the stated question.

The rule that avoids it is to store and transport the components, deriving the ratio at the moment of display at whatever grouping is being shown. That is a special case of a more general property worth knowing: which measures survive summation across dimensions and which do not. The two cases that break are a semi-additive fact, which adds across some dimensions but not others — a balance adds across accounts and not across time — and a non-additive fact, which a ratio is an instance of.

Three layers, and why separating them matters

Most metric confusion comes from collapsing three different jobs into whichever tool the analyst happened to open.

• Definition. The business meaning, with a named owner and version: population, counted unit, time basis, and inclusion rules. This specifies the question the implementation must answer.
• Calculation. The queries, joins, and aggregations that implement the approved definition at the requested grain. Reusable or generated queries reduce duplication, but their assumptions still need validation.
• Presentation. Labels and formatting can vary while the underlying result stays the same. Choosing a different grouping or filter changes the query context: the calculation layer must recompute the approved metric at that grain, rather than adding displayed ratios or distinct counts.

When the three collapse, the definition ends up duplicated inside every dashboard that uses it — seventeen copies of a filter, each maintained by whoever last touched that dashboard. A change then requires finding all seventeen, and the ones nobody finds become the second number.

dbt keeps metric definitions in project YAML and provides a separate display label for downstream tools. Cube views expose a consumer-facing abstraction over the underlying model. These mechanisms help separate reusable calculations from presentation, provided changes in grouping or filters still use the appropriate calculation.

What a semantic layer does, and what it does not

A semantic layer is the implementation of the definition and calculation layers: business concepts and metrics declared once, and queries generated from them for whatever tool asks. Cube states the goal as building “a reusable semantic layer that provides the shared context for AI agents, BI dashboards, and embedded analytics.”

The products use related modeling concepts. Cube organizes measures and dimensions in cubes and exposes selected model elements through views. dbt semantic models declare entities for relationships, dimensions for grouping and filtering, and metrics for calculations. The details vary by product, but the relationship between measurements and descriptive context will be familiar from fact and dimension tables.

MetricFlow generates joins from the relationships declared in its semantic models, reducing repeated per-analyst decisions and avoiding unsupported fan-out paths. That protection relies on the data satisfying the declared relationships. Validate key uniqueness, required matches, and historical version selection, then reconcile comparable totals. A configuration that parses and generates executable SQL does not by itself prove these data properties.

MetricFlow accepts inputs ranging from raw to fully denormalized datasets. Its documentation recommends well-modeled inputs and warns about redundancy and restricted aggregation options; that is not a requirement that every semantic engine receive normalized tables. Assess whether the input retains the keys, rows, and attributes needed for the supported questions. A many-to-one flattening that preserves those details need not lose granularity; a summary replacing the detail or a join dropping unmatched rows can. These are different consequences of denormalization.

A semantic layer still needs decisions about ownership, adoption, and shared meaning:

• Which definition is right. The tool will faithfully serve whichever denominator you declared. Choosing it remains a business decision with a named owner.
• Consumers who bypass it. An independently maintained spreadsheet calculation can drift from the shared definition, although it can also agree. Track which consumers use the layer and how other approved implementations remain aligned.
• Dimensions that mean different things. If “region” is defined one way in sales and another in support, a shared metric grouped by region is still incoherent — the problem conformed dimensions exist to address.

Deciding how a changed definition applies to history

Definitions change as the business changes or measurement improves. When a query applies the new definition to historical inputs, past values may differ from previously reported ones. Stored extracts and version-pinned reports do not change automatically, and some periods may be unaffected: gross and net revenue coincide when there are no refunds. Compare affected periods and retain the old definition and published versions.

Metric change management keeps the transition visible by comparing versions, explaining the delta, and deciding how history will be published. The historical decision is especially easy to omit.

• Run both for a period. A new definition alongside the old, with the gap quantified, lets people see the size of the change before it becomes the only number.
• Announce with the delta, not the rationale alone. “Revenue will read about 3% lower from April because refunds are now netted” is actionable; “we improved the revenue definition” is not.
• Decide explicitly whether history is restated. Recomputing historical periods under one definition can support comparison and may replace earlier published values. Keeping earlier versions preserves what was reported, but comparisons across a definition change need a visible explanation. Assess the affected periods and deltas, decide which publication is authoritative, and retain the old version. A new definition does not automatically invalidate a report correctly produced under the old one.

Keeping definitions in version-controlled configuration makes changes easy to compare and review. A required pull request, approval checks, and controlled deployment make that review effective; code alone does not require it. Record which definition version was deployed and when. Reproducing a past number also requires its input and reference-data versions and query context. Consumer commitments belong in a data contract alongside the schema.

A related trap is worth naming: some definitions depend on attributes that themselves change over time — a customer’s tier, a product’s category. Recomputing a historical metric with today’s attribute values quietly restates the past even when the metric definition never changed, which is what slowly changing dimensions exist to make an explicit choice rather than an accident.

Central definitions, local freedom

Total centralization produces a backlog and a queue of teams waiting for a metric; total autonomy produces the four-percent disagreement. The workable boundary is not a percentage of control but a distinction between two kinds of metric.

	Company metric	Team metric
Test	Reported outside the team, or used in a decision that spans teams	Used by one team to run its own work
Examples	Revenue, active users, gross margin, churn	Time in a particular queue, cache hit rate for one service, drafts per editor
Change process	Owner plus review, announced with the delta, transition period	The team owns changes, records them, and checks affected trends, thresholds, and automation
Where it lives	The shared semantic layer, with a definition anyone can read	Anywhere the team likes, as long as it does not claim to be the company metric

Keep the company list short. Fifteen governed metrics that everyone trusts beat three hundred in a catalog nobody maintains, and the bar for adding one is that two teams would otherwise define it differently. The business glossary is where the human-readable version of those definitions lives, and it is worth keeping in sync with the semantic layer rather than as a parallel document that drifts.

Track how long a new analyst takes to produce the approved revenue figure and how often comparable reports disagree. These diagnose different problems; neither proves the cause of the other. Before investigating a discrepancy, align the definition version, input version or as-of boundary, population, filters, and access context. Then inspect the implementation and caches as well as the definition.

References

• dbt Documentation, About MetricFlow
• dbt Documentation, Creating metrics
• Cube Documentation, Data modeling overview
• dbt, Semantic Layer validations
• dbt, Data tests