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

Tables

The business objects: customers, orders, machines, invoices.

Relationships

How tables connect: an order belongs to a customer.

Figures

Named numbers with a definition: revenue, on-time delivery.

Rules

Who sees which rows, tables, fields and figures.

The four building blocks of a model. Verified questions and documents sit next to them.

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 blockIn the Sales modelWhat it gives people
TablesCustomers, Orders, Invoice lines, ProductsThe business objects, each pointing to the ERP
RelationshipsAn order belongs to a customer. An invoice line belongs to an order and a productRevenue per customer, per product or per region
FiguresRevenue: 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 dayOne number each, the same everywhere
RulesA regional sales manager sees only the rows of their own regionDifferent answers for different people, from the same question
Verified question"What was the revenue this year?" with its known right answerA 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.

On this page