The semantic layer

A semantic layer is the place where business metrics get a single, shared definition. It sits between your raw tables and the people asking questions. When someone asks for revenue, the semantic layer says exactly which columns, filters, and rules make up revenue, so the agent does not have to guess.

Without it, every query reinvents the metric. One query counts refunds as revenue, the next one does not. Two reports about the same week disagree, and nobody can say which is right.

Why shared definitions matter

Revenue sounds simple until you write the SQL. Do you include tax? Refunds? Trial accounts? Internal test orders? Each choice changes the number. If the agent picks differently each time, you cannot trust any single answer.

A semantic layer settles these once. It defines a metric as a name plus the logic behind it.

• Revenue is paid orders, minus refunds, excluding internal accounts.
• Active user is an account with at least one session in the last 28 days.
• Churn is a paying account that did not renew within the grace window.

Now every answer that uses revenue uses the same revenue. The definition lives in one place, so when it changes you change it once.

How it stops the agent from inventing numbers

An analytics agent reaches for the easiest plausible query. Ask for revenue with no definition and it will write something that runs and returns a number. The number looks fine. It is just not your number.

The semantic layer removes that gap. The agent reads the metric definition and builds its query from your logic, not from a guess. This is the difference between an answer that matches the finance team’s spreadsheet and one that quietly does not.

In nao the semantic layer is part of the broader context the data team builds and governs. Metrics live alongside schemas, rules, and docs, all version controlled. The team defines a metric once and every agent answer inherits it. The next unit covers how to connect your warehouse and start building this layer.