A practical guide to the semantic layer

The semantic layer is one of those concepts that sounds abstract until you need it — and by then, you’re usually trying to retrofit it into an existing platform under pressure. Here’s what it is, why it matters, and how to approach building one without overengineering it.

What it actually is

A semantic layer is a mapping between the physical structure of your data and the business concepts your organization cares about. It defines what “revenue” means, how “active user” is calculated, which table and column represent “customer region,” and how these concepts relate to each other.

It sits between the data warehouse and the consumption layer — dashboards, AI tools, notebooks, APIs — and provides a single, governed source of truth for business definitions.

Why it matters now more than ever

The semantic layer has always been important, but two trends have made it urgent. First, the proliferation of BI tools and data consumers means the same metric is being defined independently in multiple places, leading to conflicting numbers and eroded trust. Second, AI tools need unambiguous definitions to generate correct queries — they can’t resolve the kind of ambiguity that a human analyst navigates intuitively.

Start small

The most common mistake is trying to model your entire business in the semantic layer before anyone uses it. Start with a single domain — revenue metrics, or product usage, or marketing attribution — and get it into production. Learn what works, what breaks, and what your stakeholders actually need. Then expand.

A semantic layer that covers 20% of your metrics and is actually used is infinitely more valuable than one that covers 100% and sits in a pull request.

-- Example: a simple metric definition
SELECT
  date_trunc('month', order_date) AS month,
  SUM(amount) AS revenue
FROM orders
WHERE status = 'completed'
GROUP BY 1

The code above is trivial. The hard part is getting the organization to agree that this is how revenue is defined — and then enforcing that definition consistently.