Semantic Layer for SQL.An answer, not a hallucination.

Hand a language model your information_schema and ask it for "monthly revenue". It will find a column called amount, or amt, or maybe amt_cents_v2_final, and it will write a query that sums it. The query will run. It will return a number. The number will be wrong in a way nobody on the call notices until the finance lead opens the dashboard the next morning.

The model had no way to know:

• that refunded_amount_cents has to be subtracted
• that one-time charges are excluded from MRR by agreement with finance
• that the amount column on the legacy table is in dollars, not cents
• that a JOIN against invoice_line_items multiplies the customer count
• that "active" means status equals active AND current_period_end is in the future

None of that lives in the schema. It lives in your team's heads, in Notion pages nobody re-reads, and in the queries one senior analyst wrote two years ago. That gap, between what the schema says and what the business actually means, is the gap a semantic layer for SQL exists to close.

Here is what one team's sql business logic layer looks like for the six terms that show up in nearly every revenue question. Click a row to see the verified rule the SQL generator will pull on the next prompt.

status = 'active' AND current_period_end >= now()

Six rows. Six unambiguous definitions. Any prompt mentioning these terms now resolves to the same SQL, because the layer is the source — not the prompt, not the model, not whoever happens to be on call.

The trick is what happens before the SQL generator runs. With a semantic layer in place, the pipeline does not hand the prompt straight to the model. It first resolves every business term in the prompt against the layer.

SUM(amount)
FROM invoice_line_items
GROUP BY plan_id

SUM(amount_cents)/100.0
FROM billing.invoice_line_items
WHERE status = 'paid'
  AND product_type = 'subscription'
GROUP BY plan_id, month

The model is still in the loop. It still does the shape of the query, the joins, the time-bucketing. What it no longer gets to invent is the meaning of MRR, the meaning of active, the meaning of revenue.

The category named headless BI (Cube, dbt Semantic Layer, MetricFlow, AtScale) is sometimes pitched as the same thing as a semantic layer. They are related but not identical, and the distinction matters when you are evaluating an AI analyst.

A headless BI product is a semantic layer plus a runtime: it owns the definitions and also serves the queries via a metrics API. The dashboard talks to that API instead of writing SQL itself. That shape is excellent for pre-modeled dashboards. It is awkward for ad hoc questions, because every new business term needs to be defined in the headless-BI YAML before any tool can ask about it.

A semantic layer in Chion's sense is the metadata only. It does not intercept your queries; it informs them. The SQL generator reads the layer, resolves the business terms in the prompt, and emits a query that runs directly against your warehouse. New terms can be added without redeploying anything. The trade-off: you do not get a metrics API for other tools to call — for that, headless BI and a semantic layer are complementary, not competitive.

Short version: headless BI = semantic layer + a serving runtime. Chion = the semantic layer that an AI analyst reads, persisted next to a real Postgres warehouse.

On first connect, Chion profiles every column on a read only role, then a second pass — the semantic analyzer — proposes the layer fields from section two: business_name, semantic_type, is_additive, grain hints, persisted in ai_semantic_attributes with categorical sample values so prompts like "lane A vs lane B" resolve to the actual codes. The full connect-discover-ask product flow is walked through in how Chion builds the layer.

That gets you started. The layer becomes real when the data team uses it. Every time someone runs a question in chat, refines the SQL, and promotes the verified query, the filter expression on that query is added to the layer. The mapping row for "active customer" stops being a guess and becomes the exact expression your senior analyst signed off on.

The persistence model matters: the layer lives in structured database rows, not a Markdown doc. That is what lets the SQL generator, the chart renderer, and the verified-query exporter all read the same source. It is also what makes the layer survive a schema change — when a column is renamed, only the column_profiles row moves; the business_name and verified_rule that point at it travel with it.

When the team is ready to ship the layer outside Chion, it compiles into the same CHION.md bundle the rest of the platform produces — every verified rule travels with the query that uses it. The SQL AI analyst page covers how that bundle is consumed at runtime, and the AI analyst overview covers the role context. For the upstream generation step see text-to-SQL explained, and for the read-only execution guarantees see verified SQL agents. This page stays on the layer itself.

• A semantic layer for SQL is a deterministic map from business term to table, column, grain, and filter.
• A sql business logic layer stores definitions as structured rows, not saved queries or prose.
• Six fields do the work: business_name, semantic_type, is_additive, grain, value_samples, verified_rule.
• Without it, an LLM guesses column meaning. With it, every prompt resolves the same SQL.
• The conversion from hallucinated to verified happens before SQL generation, not after.
• Chion builds the layer by column profiling plus a semantic analyzer, and persists it in ai_semantic_attributes and column_value_samples.
• Every promoted verified query writes its filter expression back into the layer, so the layer hardens over time.