Semantic models
What a semantic model is, what it contains, who owns it and why Cortex answers from it, with a worked example from Brightwater Foods.
A semantic model is the agreed meaning of your data. It sits between your data sources and everything people use, and it answers the question: what do we mean when we say "revenue", "open orders" or "scrap rate"? Without it, every report answers that question in its own way. With it, the answer is written down once, and Ask, dashboards, apps and workflows all read it.
In the Hub's Studio section, models are listed under Models. This page explains the idea. To build or change one, see Semantic models in the Studio guide.
Who can do this
Everyone benefits from models, because every figure they see comes from one. Builders with a Studio seat create and change models, and the owners of a model publish it and certify its figures. Other people can look at the published model read-only, in the Model guide.
What a model contains
The business objects: customers, orders, machines, invoices.
How tables connect: an order belongs to a customer.
Named numbers with a definition: revenue, on-time delivery.
Who sees which rows, tables, fields and figures.
Tables. The business objects the data is about, such as customers, orders, machines or invoices. Each table points to a source: a table in an ERP, a warehouse or an app. A model can combine several sources.
Relationships. How tables connect: an order belongs to a customer, an invoice belongs to an order. Relationships let Cortex combine data from several tables correctly, for example revenue per customer region.
Figures. The named numbers people care about. A figure has a definition: which table it comes from, how it is calculated (a sum, a count, a ratio of two other figures) and any conditions, such as "only orders that are not cancelled". The Hub and Studio call these figures; in Dutch they are called kengetallen. In technical conversations you may also hear the word measure for the same thing. A figure can also have other names ("Also called"), which Ask uses to recognise what you mean, and a unit, and whether higher or lower is better.
Rules. Who may see which data. A rule can limit the rows a person sees, mask a field, restrict a figure, or hide a whole table for people who are not in a given audience. See Access and security.
Models can also carry verified questions, examples of questions with a known right answer, and documents such as manuals and procedures that belong to the model. A question that matches a verified question can be answered without any AI call. See Ask and AI and Documents and sources.
One definition, used everywhere
Dashboards, Ask, apps and workflows read their numbers from the model. They do not calculate on their own. That has a few consequences:
- Two dashboards that show "revenue" show the same revenue.
- Ask gives the same answer as the dashboard.
- If a builder changes the definition of a figure, every dashboard and answer that uses it follows.
- A figure that is not in the model does not exist for Cortex. If you miss one, a builder can add it, or you can suggest it to the model's owners.
Example: the Sales model at Brightwater Foods
Brightwater Foods has a model called Sales. This is what is in it, in business words.
| Building block | In the Sales model | What it gives people |
|---|---|---|
| Tables | Customers, Orders, Invoice lines, Products | The business objects, each pointing to the ERP |
| Relationships | An order belongs to a customer. An invoice line belongs to an order and a product | Revenue per customer, per product or per region |
| Figures | Revenue: the sum of the invoice amount, for invoices that are not cancelled. Open orders: the count of orders not yet delivered. On-time delivery: the share of orders delivered by the promised day | One number each, the same everywhere |
| Rules | A regional sales manager sees only the rows of their own region | Different answers for different people, from the same question |
| Verified question | "What was the revenue this year?" with its known right answer | A fast, checked path for a question people ask often |
Now follow a question. Sam de Vries asks "What was the revenue this year?". Cortex finds that the Sales model has a figure Revenue, asks the model for it for 1 January until today, applies Sam's rules, and returns one number. The finance dashboard's Revenue tile asks the same model for the same figure. If Brightwater decides that credit notes should be subtracted, the owner changes the definition once, certifies it again, and Ask, the tile and a weekly digest all follow.
How the model answers a question
When a dashboard, an app or Ask needs a number, it sends the model a structured request: which figures, grouped by what, filtered how, for which period. The model works out how to get that from the sources, applies the rules for the person who is asking, and returns the figures. Nobody writes a free-form database query: not you, and not the AI.
Who builds and owns a model
Builders create models in Studio. They can describe a figure in a sentence and let Cortex fill in a first version, then check the number before anything goes live. Nothing is live until the model is published. Until then, changes live in a draft that only the builders see. A model keeps a version history, so an earlier version can be restored to the draft. A model can also include another model, so a figure can be shared instead of copied.
Every model has owners. Only an owner of a model can certify a figure in it, and an owner decides who may read the model at all: someone who may not read it does not see it. IT decides which data sources are available to models in the first place, and builders ask for datasets through Studio's Sources page. See Data sources.
What a model does not do
A model does not store a copy of your business. It describes data that stays in its sources, and reads it when asked. Changing the data is the job of your source systems and your apps, not of the model.
Keeping a model healthy
Models are checked: when a builder publishes, and again every night. The Health area of a model ("What to fix next") lists what to fix, including questions that people asked and the model could not answer. How the nightly checks protect the trust in your figures is explained in Certified figures and nightly checks, and the checks themselves in Model checks.
How Cortex works
The big picture: data sources, semantic models, trust and the experiences that read from them, followed by one figure from the ERP to Ask, a dashboard and a digest.
Certified figures and nightly checks
What the Certified badge means, how a figure earns it, why it can disappear overnight and when it comes back, with the story of one figure at Brightwater Foods.