Skip to main content

The semantic layer

Synced from 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
PartWhat it isChapter
DatasetOne table or query in your warehouse, with a time axisDatasets
FieldOne column or scalar expression of a datasetFields
RelationshipA to-one link from one dataset to another, which lets a query reach the other's fieldsRelationships
MetricA governed number: one aggregation, or arithmetic over other metricsMetrics
DomainA use case: the datasets, fields and relationships it exposes, and the metrics it ownsDomains

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_models and query_describe_model list the domains you can query, with their metrics, fields and time axis.
  • query_describe_metric shows one metric's definition, what it can be broken down by, and how it re-totals.
  • model_inspect reads 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_change changes 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​

ChapterRead it to
Datasetsunderstand sources, time axes and partitions
Fieldswrite a field expression, pick a datatype, reference a field
Relationshipslink datasets, and reach a field two ways or through a self link
Filterswrite a metric's filters
Metricsdefine a number and know how it re-totals
Cachingmake a metric answer from a cube, and control what happens when it cannot
Domainschoose what a use case exposes, its time zone and defaults
Semantic SQLwrite a query
Fields and paths in SQLname a field of a linked dataset in a query
Timewrite a window, bucket by day or hour, and work in a time zone
Composing queriescompare periods, rank, and compute shares
Answersread what comes back, and preview an unsaved metric
Names and changesrename, delete, and keep saved queries working
Errorslook up any error code and what to write instead