What the semantic layer is
The semantic layer describes your connected data in business terms. You name the things your business tracks, such as orders, stores, and customers, say which table holds each one and how they connect, and define the numbers you measure on them. Metrics, the Assistant, and other AI features in Qubit read these definitions, so a number means the same thing wherever it appears.
Opening it
In the sidebar, open Data Catalog and click Semantic model at the top of the page. This opens the Semantic Layer page. Create metric on the Metrics page opens the same page.
What it contains
The model is a single YAML document with these parts:
sources: a short name for each data connection the model uses.entities, shown as business objects in the editor: each one is a table that holds one row per real thing, such as one row per order, with its primary key, a description, and the dimensions you want to split numbers by.relationships, shown as joins: written inside a business object, each one says which column links it to another object. The two objects can be in different databases.metrics: the official numbers built on those objects.
You edit the document in Build, a form over your real tables and columns, or in Code, the YAML itself. Both change the same document.
What it changes
- Metrics defined here appear on the Metrics page. Editing a definition here updates the metric everywhere it is used.
- A metric can be split by a dimension of a joined object, such as orders by store region, because the join is declared once.
- The Assistant receives your business objects and joins, and is instructed to join tables on the keys you declared instead of guessing from column names. See How it shapes AI answers.
Do you need one?
The Assistant can answer questions without a model. It reads your schema and writes its own SQL. A model gives it declared joins and official definitions to follow, and it is where you define metrics.
Who can edit it
Anyone in the workspace can open the page and run Check. Saving changes and Find joins need the workspace's update permission, which Owners and Admins have.