The semantic layer is the new API

For twenty years the API was the contract between a system and the people who built on it. Data never had one. It had tables, and tables are not a contract, they are a suggestion. The semantic layer is the first thing that behaves like an API for data, and it arrived just in time for the one consumer that cannot cope without it.

Question

What was revenue last month?

Waiting for an answer…

Four plausible answers. A model, or a new hire, will pick one with confidence. Values are made up; the pattern is not.

A simple question

What was revenue last month? Every executive asks it. Every warehouse can answer it. That is the problem.

Ask the tables

Four columns called revenue, each right for the person who made it. Finance nets refunds, sales counts bookings, billing stores cents. A model, or a new hire, will pick one with confidence.

Ask the metric layer

One name, one definition, one owner, one change history. The model maps the question to the metric, which it is good at, instead of guessing the schema, which it is bad at.

Try the other questions

Customers and churn go the same way. Switch questions and views. The values are made up; the pattern is not.

Tables are not an interface

Every warehouse has a revenue column in four places, and each one is right for the person who created it. Finance nets out refunds. Sales counts bookings. The billing sync stores cents. The orders table includes tax. None of them is wrong. All of them are wrong if you use them for the other person’s question.

Humans cope with this through folklore. You learn which table finance trusts by asking someone, once, and then you never think about it again. That folklore does not survive a new hire, a reorg, or a language model.

Why this matters more now

A model asked “what was revenue last month” will write correct SQL against the wrong column. It will pick a table, choose a filter, and return a number with the same confidence whether it landed on the right one or not. This is not a model quality problem. Bigger models pick the wrong column more fluently.

The fix is to stop letting the model touch tables. Give it a layer where “revenue” is a single, named thing with a definition, an owner, and a change history. Now the model’s job is to map the question to the metric, which it is very good at, instead of guessing the schema, which it is very bad at.

plausible answers to one question

from the tables in the demo above

answer through the metric layer

same question, one definition

guesses left for the model

mapping a question to a name is the easy part

What an API-grade semantic layer has

The tools vary. dbt’s metrics, Cube, LookML, and the warehouse-native versions all have different syntax. The properties that matter are the same:

Named metrics with a definition in code. Not a wiki page. The definition is the thing that runs.
Dimensions declared once. Time, region, plan, whatever you slice by. A metric knows which dimensions it supports.
An owner and a changelog. When net_revenue changes, someone approved it and everything downstream can see the diff.
A query interface. Something a BI tool, a script, or an agent can call with a metric name and a set of dimensions and get a number back. That is the API.
Permissions at the metric level. If an agent is answering questions in Slack, this is the layer that decides what it is allowed to say.

Miss any one of these and you have a glossary, not a layer.

The trap: building it for the dashboard

Most teams build the semantic layer to make the BI tool consistent. That is fine, but it leads to a layer shaped like a dashboard: a few dozen metrics, tuned to the charts that exist today.

Build it like an API instead. Assume the consumers you do not know about yet. An agent answering a founder in Slack, a monitoring job that fires when a metric drifts, a spreadsheet formula, a partner integration. Every one of them wants the same thing: call a name, get a number, trust it.

Where to start

Pick the five metrics that appear in your executive deck. Define them in code, one owner each.
Route one consumer through the layer end to end. A single dashboard is enough to find every place the definitions disagree.
Only then connect a model. It will be boringly correct, which is the point.

The warehouse consolidated the middle of the stack. The semantic layer is what makes the edges safe to automate. It is the API data never had, and the first consumer that really needs it is not a person.