Skip to content

What is a semantic layer, and why every number should have one definition

The semantic layer explained with small-business examples: why dashboards, accounting spreadsheets and AI answers disagree, and how one versioned definition per metric fixes it.

By The DataxLand team· · 5 min read

Every weekly meeting has this moment: marketing says October revenue was 310 million, accounting says 270 million, and the owner's marketplace dashboard shows 330 million. Nobody is wrong. Each person uses a different definition of "revenue", and nobody wrote theirs down. The meeting turns into reconciling numbers instead of deciding anything.

A semantic layer solves this: one place that defines every business metric — which table it comes from, which column is added up, what is filtered, which dimensions it can be split by — and every tool that shows numbers goes through it. This post explains the idea with small-business examples; no SQL needed.

Three "revenues" in one company

PersonCalls it "revenue"What it actually isExample (illustrative)
OwnerThe big number on the marketplace dashboardGMV: price × quantity, before discounts330 million ₫
MarketingRevenue in the ad reportConversion value attributed by the ad platform310 million ₫
AccountingRevenue in the booksNet revenue: after discounts, vouchers, refunds270 million ₫

All three are correct by their own definition. The problem is that definitions live in people's heads, in each spreadsheet's formulas and in each tool's settings. Add an AI chatbot that reads raw tables and writes its own queries, and you get a fourth definition — guessed by the model, possibly different between two runs of the same question.

What a metric definition contains

PartExample for "profit after fees"
Name and synonymsProfit after marketplace fees and ads; synonyms: profit, net profit
FormulaContribution margin − allocated ad spend
ComponentsContribution margin = net revenue − COGS − platform fees − payment fees − shipping − return shipping
Source modelOrder-line profit model (orders joined with fees, cost of goods and ads)
Allowed dimensionsChannel, marketplace, product, category, date
Time grainsDay, ISO week (Monday start), month
Good directionUp
CompletenessReported with the share of revenue that has a cost
Version1.0.0 — a formula change bumps the version

When a dashboard needs "profit after fees by channel for October", it does not write its own query. It asks the semantic layer for this metric, this dimension, this period. The semantic layer builds the query from the definition, runs it, and returns the number with the definition version and the data-as-of date. Scheduled reports, alerts, Si and external agents over MCP ask the same way, so they get the same number.

Why it matters more once you add AI

A common way to "talk to your data with AI" is to give a language model the list of tables and columns and let it write SQL. It demos well, but has three problems with business numbers:

  1. It guesses definitions. The model cannot know whether your "revenue" is GMV or net revenue, whether refunds are subtracted, how order vouchers are split. It picks something reasonable — reasonable is not the same as right.
  2. It is not repeatable. Ask twice, get two queries, sometimes two numbers.
  3. It does not match the dashboard. The chatbot and the dashboard take different paths, so when they disagree you do not know which to trust.

DataxLand takes a different route: Si does not write SQL against business data. Si can only call semantic-layer tools — pick a metric, dimensions, filters, period, comparison — and the DataxLand engine builds the query from the definition. Si's answers match the dashboard, and every answer ends with Sources: which metric, which version, which period, data as of which date. See Si.

Confirmation levels: standard, approved, unconfirmed

One definition per name does not mean nobody can add metrics:

LevelWhere the definition comes fromExample
StandardIndustry × department metric packs, with testsNet revenue, contribution margin, profit after fees, true ROAS
ApprovedWorkspace-defined metrics (ws.<name>), checked against real data and enabled by someone with permission"Profit after fees minus affiliate commission"
UnconfirmedExploratory measures when you ask something no metric covers yet"Units sold of the gift category by province"

Exploratory answers come back immediately, labelled "Unconfirmed". If useful, Si can propose turning one into a workspace metric — as a draft until someone approves it. Packs are a starting point, not a limit, and there are still never two definitions behind one name.

Versions: when a definition has to change

Definitions change — for example, the shop starts restocking returned goods and wants returned lines to get their cost back. Without a semantic layer someone edits a formula in a file and last month's numbers silently "change". With one:

  1. The new formula goes into the definition and the version is bumped (1.0.0 → 1.1.0).
  2. Before use, the new definition is checked against real data to see the difference. For workspace metrics, DataxLand requires this check before the metric can be enabled.
  3. Every answer afterwards carries the new version, so when you compare with an old report you know why the number differs.

When a small business needs one

You do not need a semantic layer if one person makes the numbers in one spreadsheet and nobody asks twice. You do when two or more of these are true:

  • More than one person or tool reports "revenue" or "profit".
  • Meetings spend time reconciling numbers instead of deciding.
  • You want to ask an AI about your numbers but are not sure it computes them correctly.
  • Reports to partners, investors or banks must explain every figure.
  • An outsourced accountant or agency needs to see the same numbers you do.

What a semantic layer is not

  • Not a warehouse. The warehouse stores data; the semantic layer defines how to read it as metrics.
  • Not a dashboard. A dashboard is one place to display numbers; the semantic layer serves all of them.
  • Not only for large companies. The concept is common in enterprise data tooling (for example the dbt Semantic Layer), but "three people, three numbers" starts the day a company has a second person making numbers.

DataxLand ships a semantic layer with standard metrics per industry and department — see the retail finance dashboard template — and lets you add your own, checked before use. Start with the DataxLand docs or read how external AI tools reach the same metrics in MCP for business metrics.

Related posts

Verified dashboards from your own data, this afternoon

Free plan with no time limit · No card required · Sample workspace ready in minutes