The semantic layer
Source: docs/guide/00-overview.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
The semantic layer holds a model of your warehouse, made of datasets, fields, relationships and
metrics, and answers questions asked in that model's own words. You ask for MEASURE(revenue) by
orders.region over a time window. The layer works out the joins, filters and aggregation, runs
the query on your warehouse or on a cache, and tells you how the number was made.
This guide is for anyone who reads a model, fixes it or queries it, whether a person or a coding agent. It describes what the layer does today.
The parts of a model
domain commerce ← what a query names in FROM; owns the metrics
├─ metric revenue ← sum of orders.amount, completed orders only
├─ metric conversion_rate ← order_count / session_count
└─ selects datasets:
orders ──orders_to_customers──▶ customers
├─ field region
├─ field amount
└─ field completed_at ← the time axis
sessions
| Part | What it is | Chapter |
|---|---|---|
| Dataset | One table or query in your warehouse, with a time axis | Datasets |
| Field | One column or scalar expression of a dataset | Fields |
| Relationship | A to-one link from one dataset to another, which lets a query reach the other's fields | Relationships |
| Metric | A governed number: one aggregation, or arithmetic over other metrics | Metrics |
| Domain | A use case: the datasets, fields and relationships it exposes, and the metrics it owns | Domains |
Every part has a name, a lowercase snake_case identifier, and that is what a query spells.
Dataset and domain names are unique in the tenant. Field and relationship names are unique in
their dataset, and metric names in their domain. A display_name is free text for people. It is
shown in answers but never spelled in a query.
Where a model comes from
Most models are written by sync. Each of your use cases becomes a domain, its event and entity types become datasets, and its KPIs become metrics. A sync matches each object to the one it wrote before, so names stay put when upstream titles change (Names and changes). A person can then add to it: a field, a time axis, a metric of their own. A sync keeps what a person added, but overwrites a person's edit to something the sync wrote.
Reading and fixing a model
From Bicycle Studio over MCP:
query_list_modelsandquery_describe_modellist the domains you can query, with their metrics, fields and time axis.query_describe_metricshows one metric's definition, what it can be broken down by, and how it re-totals.model_inspectreads the stored model: each dataset with its source table and dialect, each field's expression and datatype, and whether a sync or a person added it.model_changechanges it. You validate the change, look at the sample it returns, then apply it.
Every write runs checks before it is saved. The warehouse proves the table and every field exist and that each field returns the type it declares, and the layer proves the SQL it would generate compiles. A failed check refuses the whole write, and the error says why.
Asking a question
A question is one semantic SQL statement:
SELECT orders.region,
DATE_TRUNC('week', time) AS week,
MEASURE(revenue) AS revenue
FROM commerce
WHERE time >= :since AND time < :until
GROUP BY ALL
You can plan it, which checks and prices it and runs nothing, or execute it, which returns
rows. Over MCP that is query_compile or query_run. The answer always says where it came from,
which window and time zone it used, and what each column is (Answers).
Chapters
| Chapter | Read it to |
|---|---|
| Datasets | understand sources, time axes and partitions |
| Fields | write a field expression, pick a datatype, reference a field |
| Relationships | link datasets, and reach a field two ways or through a self link |
| Filters | write a metric's filters |
| Metrics | define a number and know how it re-totals |
| Caching | make a metric answer from a cube, and control what happens when it cannot |
| Domains | choose what a use case exposes, its time zone and defaults |
| Semantic SQL | write a query |
| Fields and paths in SQL | name a field of a linked dataset in a query |
| Time | write a window, bucket by day or hour, and work in a time zone |
| Composing queries | compare periods, rank, and compute shares |
| Answers | read what comes back, and preview an unsaved metric |
| Names and changes | rename, delete, and keep saved queries working |
| Errors | look up any error code and what to write instead |