← Back to all posts The Semantic Layer define revenue once governed tables correct, fresh, tested the definition net_revenue owned, reviewed, versioned EVERY CONSUMER, ONE ANSWER BI dashboards notebooks & models AI agents asking questions without this box, each consumer on the right writes its own SQL and the numbers drift

The Semantic Layer: Where Metric Definitions Should Live

Aug 2026 · Data Governance

Finance says last month's revenue was one number. Sales ops says it was another. The pipeline is fresh, the tests pass, and both teams can defend their query line by line. They can both be right, because they're computing two different things and calling both of them revenue.

A gap like that almost always comes from one of five places.

Where definitions splitWhat the disagreement looks like
Filter scopeOne definition excludes cancellations, refunds, internal orders, or test accounts. The other doesn't, or excludes a different set.
Time attributionOrder date versus ship date versus recognition date. Each is a valid business view, but they never agree at a month boundary.
Grain and joinsA join to a dimension with more than one matching row multiplies the measure. The total is inflated and no error shows up.
ConversionsCurrency applied at transaction rate in one place and month-end rate in another, or timezone boundaries shifting rows between periods.
Aggregation rulesA ratio averaged across groups when it should be recomputed from its parts. Each row is correct, but every rollup comes out wrong.

Settling it usually takes someone a day. They trace both queries, find the difference and write an email. Next quarter a different pair of reports disagrees, because the email explained the gap but the definition still lives in two places.

Give the definition an owner

I treat a metric definition the way I'd treat a table. It needs an owner, a written meaning, a version history, and a list of the consumers who break when it changes. Most companies keep it somewhere with none of that. It's a saved calculation in a BI tool, a CASE statement in a shared query, or a spreadsheet formula that became official because people kept copying it.

A semantic layer keeps the definition in one place, and every tool asks for the metric by name. Once net_revenue lives in version control with an owner and a test, changing it means opening a pull request with a diff. Today the same change is an edit inside a dashboard that leaves no record and sends no notice.

People can look it up, too. "What do we mean by active customer?" gets an answer with a name attached.

And every tool gets the same number, from notebooks and embedded analytics to reverse ETL and AI agents. Agents worry me most here. An agent that answers business questions straight from warehouse tables writes its own revenue query, and nothing in its answer tells you which of the five splits above it picked. So I'd pair a metrics layer with limits on what agents can read. The read limits control which tables an agent touches, and the metrics layer controls how it computes revenue from them.

Lineage stops at the BI tool

A lineage graph traces columns up to the point where a BI tool takes over. Calculations inside the tool don't show up, and in most companies that's the biggest blind spot the graph has. I went through the other blind spots in my lineage post.

Say a column change shows two downstream models. Fourteen dashboard calculations might also use that column, and the graph gives no hint of them. Quality checks can be green on every table underneath while the number on screen is wrong, because the mistake happened after the last governed step.

Moving the definitions into a semantic layer makes each metric its own node in the graph, with its upstream columns attached. A schema change can then list the metrics it affects, and a quality alert can name the metrics now showing suspect data. That helps even at a company where nobody argues about revenue.

Who decides what revenue means

The modeling is ordinary engineering with a clear finish line. Projects stall on the people side.

Finance, sales ops and analytics have each been computing their own version, often correctly for their own purpose. A semantic layer makes someone pick one or name several on purpose. Teams that treat it as a modeling task tend to find out a few months in that nobody will sign off on the main entries.

Naming several works. If finance and operations need different revenue treatments, define net_revenue_finance and net_revenue_ops, write down how they differ, and give each its own owner. The argument changes from "your number is wrong" to "you used the other metric," and that one's quick to settle. Forcing a single definition when two are valid sends one team back to its spreadsheets, and the official metric ends up trusted on paper and ignored by half the company.

I'd move the metric that has needed reconciling more than once first. Define it, point every report that shows it at the layer, and delete the local copies. One metric moved all the way is worth more to me than forty defined in the layer with the old copies still in use. It also raises the ownership question at a size where someone can answer it.

How it goes wrong

Most BI tools let local calculations sit next to governed metrics. If the migration doesn't remove the old ones, you get both, and a mismatch gets harder to chase because a chart might be reading either. Deleting the old dashboard formulas is part of the job.

The other risk is a slow change process. If a new metric takes a pull request, a review and a deploy, analysts on a deadline will skip it, and I'd do the same in their place. Govern the long-lived metrics that several teams share and leave one-off exploration open.

Do you need one at all?

Look for one thing: a reconciliation between teams that has happened more than once. If you can name two times two teams spent a day lining up their numbers for the same metric, that metric is your first candidate, and the case for the layer is already made.

Signs you can skip it for now:

Data & AI governance, from the field

Notes on data governance that works in practice, plus my free RFP & TCO scorecard when you sign up.

No spam, unsubscribe anytime · Privacy

More in Data & AI Governance →