Metric model (JSON)
Query (JSON)
Generated SQL
Catalog (what consumers can ask for)
Domain samples
What the layer buys you
- One definition, many consumers. "Revenue" is one expression — used by the executive dashboard, the BI tool, and the LLM agent. Nobody is off-by-a-join from someone else.
- Naive text-to-SQL fails on business rules. "How much revenue last month?" needs to know that
amountexcludes refunds, the month boundary is your fiscal one, andstatus = 'paid'is implicit. The semantic layer encodes that once. - Dimensions live with the metric. Consumers can only group by what's been blessed. No "let's join on this random column and see what happens."
- Engines this resembles: dbt MetricFlow, Cube.dev, Snowflake Semantic Views, Databricks Metric Views. The semantic-layer pattern itself is older than the data-platform race; what's new is treating it as infrastructure rather than a BI plugin.
This playground is a teaching toy — single-source metrics, no joins, no time-grain expansion, no access control. Real engines do all of those. The point here is the seam: one definition file, many query consumers, one SQL compiler in the middle.