Semantic layer: one metric definition in every tool
A semantic layer is where a company defines its business metrics once, so that all reporting tools and AI assistants use the same definition. The article explains how a semantic layer works, shows a worked example of a metric discrepancy, and describes the metric specification and implementation mistakes.
Amounts and values in the examples are illustrative and show how the calculation works. In projects, we use the client's data.
Dominik Dębski · Lemur Media · · reading time: 4 min
Reviewed by Dominik Dębski, 1 November 2026
What is a semantic layer?
A semantic layer is a layer between data and analytics tools that holds the definitions of business metrics, dimensions and relationships between tables. A reporting tool or AI assistant takes a ready-made metric from the semantic layer and does not store its own calculation logic. One example is the dbt Semantic Layer, built on MetricFlow: metrics such as revenue are defined in the dbt project, and a change to a definition applies everywhere the metric is used. The dbt documentation also notes that AI assistants can query the semantic layer and use approved metrics instead of raw tables.
Where do metric discrepancies come from?
Discrepancies arise when each tool or department writes down a metric's logic separately. An example of monthly revenue in a distribution company:
| Who calculates it | Definition | Calculation | Result |
|---|---|---|---|
| Sales (CRM) | Sales before discounts and returns | 11,2 | PLN 11.2m |
| Marketing (BI tool) | Sales after discounts | 11,2 − 0,6 | PLN 10.6m |
| Finance (ERP) | Sales after discounts and returns | 11,2 − 0,6 − 0,4 | PLN 10.2m |
The difference between the highest and lowest values is PLN 1.0m, or 9.8% of revenue according to finance (1.0 ÷ 10.2). At board meetings, time goes into reconciling figures, and each department is right within its own definition. The problem grows when the same data feed into forecasts, bonuses and settlements with partners. The semantic layer holds one definition of net revenue and, where needed, explicitly named supporting metrics, e.g. sales before discounts.
Where does the semantic layer sit in the data architecture?
The semantic layer sits between the data warehouse and the tools that use the data: BI reports, spreadsheets, applications and AI assistants. Below the semantic layer, data are extracted from sources, cleaned and modelled into tables. The semantic layer adds business meaning to them: metric names, formulas, permitted dimensions and relationships between tables.
| Tier | Contents | Who is responsible |
|---|---|---|
| Sources | ERP, CRM, online shop, payment system | System owners |
| Data warehouse | Data extracted from sources, cleaned and modelled | Data team |
| Semantic layer | Metric definitions, dimensions, relationships, permissions | Data team with metric owners |
| Consumption | Reports, dashboards, spreadsheets, AI assistants | Business users |
The importance of the semantic layer grows with the use of AI assistants. A language model that generates queries directly against tables may interpret the term "revenue" differently each time. Querying approved metrics limits this risk, because the definition is fixed in advance and permissions control access to the data.
What does a metric specification contain?
| Field | Example for net revenue |
|---|---|
| Name and business description | Net revenue: sales after discounts and returns, excluding VAT |
| Formula | sum of invoice values − discounts − return adjustments |
| Data source and grain | invoice lines from ERP, day |
| Filters | excluding intra-group sales |
| Permitted dimensions | month, region, channel, product category |
| Owner | CFO |
| Version and change date | v2, change approved by the owner |
The specification is both an entry in the metric glossary for business users and the basis for the technical definition in the semantic layer. Both must carry the same version number.
How do you implement a semantic layer?
- A list of 15–25 metrics from the management report and the most frequently used dashboards.
- Agreeing definitions with metric owners and recording them in the metric glossary.
- Moving the definitions to the semantic layer and running comparison tests against existing reports.
- Switching the management report to metrics from the semantic layer and switching off local calculations.
- Change process: every change to a definition has a requester, owner approval and an effective date.
The first stage, covering the management report metrics, usually takes six to twelve weeks. Most of the time goes into agreeing definitions between departments, less into the implementation itself. Comparison tests are run for several closed months: every difference between the new metric and the existing report is explained and documented. After the management report is switched over, further dashboards are migrated gradually, starting with the most frequently used. Dashboards that nobody uses are best switched off at that point.
What are the common mistakes?
- Implementing a tool without agreeing definitions: the discrepancies carry over into the semantic layer.
- Leaving local calculations in BI tools alongside metrics from the semantic layer.
- No business owner for each metric.
- Too many metrics at the start, instead of those on which the board report is based.