What is a semantic layer?

A semantic layer is a shared set of definitions that translates business words like "revenue" or "active customer" into the exact columns, filters, and joins your database needs. It is how the same question gets the same answer, whether your CFO asks it or Claude writes the SQL for your ops lead.

Your database stores facts. An orders table knows that order 1002 had an amount of $85 and a status of refunded. It has no idea whether your company counts that $85 as revenue. That decision lives in someone's head, or in a Slack thread from last year.

For a long time this was a problem for dashboard builders. Now anyone on the team can connect Claude or ChatGPT to the warehouse and ask a question directly, which means the AI has to make those decisions on every query. Without a semantic layer, it guesses.

What goes into one

Most of a semantic layer is plain decisions, written down once. They tend to fall into four groups.

None of this requires special syntax. Looker writes it in LookML, dbt and Cube write it in YAML, and a solo founder can write it in a markdown file. The format matters less than having one agreed version that every query reads before it runs.

The same question, asked two ways

Say your schema has orders (one row per order, with amount, status, and an is_test flag) and order_items (one row per product in an order). Someone asks Claude: "What was revenue last month?"

With only the raw schema to go on, a reasonable-looking query comes back:

SELECT SUM(o.amount) AS revenue
FROM orders o
JOIN order_items i ON i.order_id = o.id
WHERE o.created_at >= '2026-08-01'
  AND o.created_at < '2026-09-01';

It runs without an error and returns a plausible number. It is also wrong twice over. The join repeats each order's amount once per line item, so a three-item order is counted three times. And nothing filters on status, so refunds and test orders are in the total.

With the definition available, the same question produces this:

SELECT SUM(amount) AS revenue
FROM orders
WHERE status = 'completed'
  AND is_test = false
  AND created_at >= '2026-08-01'
  AND created_at < '2026-09-01';

No join, because revenue lives on the order. A status filter, because the business decided refunds are not revenue. The model did not get smarter between the two queries. It was told what the words mean.

Do you need one?

Probably not yet if you are the only person querying and you read every query before trusting the number. A markdown file of definitions you hand to Claude will do the job, and you can build that version in about 20 minutes.

The picture changes when the answers start travelling. A second person asks the same question and gets a different number, right before it goes into an investor update. Or someone who should not see salary data connects to the same warehouse. At that point the definitions need to live somewhere shared and apply to every person and every AI tool, including the ones you did not set up yourself. Someone also has to keep them current as the schema changes, which is usually the first thing to slip.

If your real question is whether an AI can write useful SQL without any of this, that is a separate argument, covered in Does text-to-SQL need a semantic layer?

How Contextflo handles this

Contextflo generates the semantic context underneath and serves it to the AI your team already uses, so Claude or ChatGPT answer from your definitions instead of guessing from column names. Nobody has to write YAML or model the warehouse first.

When you connect a database, Contextflo reads the schema, and any source code and docs you connect, then drafts table descriptions, column meanings, relationships, and metric definitions. You review the draft and fix what is off. From then on, when someone asks a question in Claude or ChatGPT, the AI looks up the relevant definitions over MCP before it writes SQL, and each query runs under the asking person's table-level permissions. The five-minute setup walkthrough shows the steps.

The practical effect is that a team can hand much of its analytics workload to the AI, from the recurring "what was X last month" questions to the number someone needs ten minutes before a meeting.

It has two limits. The generated draft is only as good as what the schema, code, and docs reveal, so a rule that exists only in someone's head ("orders before the 2024 migration use different statuses") still needs a person to write it down. And we enforce access per table, not per row, so if you need one region's sales rep to see only their region's orders, that has to happen in the warehouse.

Every company already has a semantic layer. At most small teams it lives in a few people's heads, and the AI cannot read those.

Frequently asked questions

Is a semantic layer the same as a data model?

They overlap but are not the same. A data model describes how tables are structured and related. A semantic layer sits on top of it and records what the business means by its terms, such as which orders count as revenue or what makes a customer active, so that every query uses the same interpretation.

Can an AI build a semantic layer for me?

It can draft one. An AI can read table names, column types, foreign keys, and source code, then propose descriptions and metric definitions. It cannot know business decisions that were never written down, such as whether test orders count as sales, so a person who knows the data still has to review and correct the draft.

Does a semantic layer control who can see what data?

Many do. Access rules are part of the job once several people query the same data through AI tools. What matters is where the rule is enforced. A rule that only lives in the prompt can be ignored, while a rule checked when the query runs cannot.