Semantic models

Create a model, add tables and relationships, explore and secure it, check its health, publish it and bring an earlier version back. Everything the model studio does, tab by tab.

A semantic model is one subject area, for example Sales or Production: the tables, relationships and formulas that every app, dashboard and Ask calculates from. The agreed figures in it are what dashboards show. Because everyone reads the same definition, "revenue" means the same thing in a dashboard, in an app and in an answer from Ask. For the idea behind it, see Semantic models.

You build and maintain a model in the model studio: a page with tabs. This page walks through all of them, in the order you meet them, and ends with publishing. The figures have their own page (Figures and certification), and so do the nightly checks (Model checks) and the documents (Documents and sources).

Who can do this

Builders (people with a Studio seat). The person who creates a model becomes its first owner. Changing and publishing a model is for its owners (and admins). Everyone else sees the read-only Model guide (see below).

The list of models

Open Models in the Studio group of the left menu.

The list of models in Studio: one row per model with its owners, status, versions, what uses it and when it was last updated, plus the New model button and a search box.
Models: one row per subject area. The list itself carries no markers; the columns are described below.

Each row shows the model with its owners, its status (Draft or Published), its versions, what uses it (for example "3 apps · 2 dashboards") and when it was last updated. Use Search models to filter the list. All figures and All documents at the top open lists across all your models. The menu More ways to start: starter pack or import next to New model offers From a starter pack, Import from Power BI (see Import from Power BI), Import an envelope file and Import an OSI file.

How do I create a model?

Start a new model

Choose New model. The dialog is called "New semantic model".

Name it

Give it a Name, for example "Sales". Under More options you can add a Description ("What is this model for, and who uses it?"). The Model id is made from the name. It is used in links and cannot be changed later: 3 to 40 lowercase letters, digits or hyphens, starting with a letter and not ending in a hyphen.

Create it

Choose Create model. You become its first owner and land in the studio. If the id is already taken, the dialog says "That model id is already taken." Edit the name or the id.

What do I see when I open a model?

A model opens on its Overview. It is a short summary made of parts that each lead to a tab.

The Overview tab of the Factory model: a line about last night's checks, a strip with the published version, a card each for Figures, Model, Explore, Security and Documents, and a Next step bar.
The Overview of a model: the night's result, the state of the model, five parts and one next step.

From top to bottom the Overview shows:

  • The night's result, a one-line summary of the nightly checks such as "25 of 30 figures proven tonight · 1 differs · 8 to look at", with a link to the Checks tab. Only owners and builders see it.
  • The state strip: Published v3 (or "Not published yet"), "No unpublished changes" (or "3 unpublished changes", which opens the Publish tab), "v4 waits for approval" when an older version is still waiting, how many figures are right and certified, and "Used by 2 experiences".
  • Five parts, each a card that opens its tab: Figures (how many, and how many are right and certified), Model (the tables), Explore, Security and Documents.
  • Next step: one suggestion, such as Add your first table, Describe your first figure, Check and certify 21 figures, Publish the draft or "All figures are checked". Choose the button to go straight there.
The Overview of the model Cortex usage with 52 figures: a night line saying 26 of 60 figures proven tonight and 8 to look at, the strip with Published v9, the five part cards and a Next step bar.
A model that is already published: the night line is green because no figure differs. This is the platform's own usage model, shown only to illustrate a published model.

The tab bar of the studio reads Overview, Figures, Checks, Model, Explore, Security and Documents. The top bar also holds:

  • a status chip with what is left to do ("3 to fix") that opens Health (see Health: what to fix next),
  • the undo and redo arrows,
  • Ask, an assistant for the model ("Ask about your model…") whose changes you can Keep or Undo all,
  • Publish, and a ... menu with Includes, Export a version, Import a model and Settings.

Everything you change is saved in the draft of the model. Nothing reaches dashboards, apps or Ask until you publish.

The tabs at a glance

TabWhat it is for
OverviewThe state of the model and the next step.
FiguresThe agreed numbers, their meaning and their proof. See Figures and certification.
ChecksWhat Cortex checks every night. See Model checks.
ModelThe tables and relationships as a map, and the model as code.
ExploreTry a question on the model, or run a SQL query.
SecurityWho sees which rows, tables and figures, and which apps and AI tools may use the model.
DocumentsThe manuals and procedures that Ask can quote. See Documents and sources.
Health (the status chip)One list of what to fix next.
Publish (the button)Make the draft live, and the version history.

The Model tab: tables and relationships

The Model tab shows the tables of the model as a map. This is where you add tables, relate them and describe what each table and field means.

The Model tab of the Factory model: on the left the list of fields per table, on the right the Subject areas, two cards with their facts, dimensions and figures, and above them the switch between Diagram and Code.
The Model tab: the fields on the left and the subject areas to open on the map. Pick an area to see its tables.

How do I add tables?

Pick a source table

Choose Add and then Add table, or use the Add table button on the Overview. The dialog says "Pick a source, open a schema and add a table to the draft." You can also open the Sources list and drag a table onto the canvas. A table that is already in the model says In model.

Describe it

Select the table. The Properties panel shows its display name, Description, Table type, Key fields and, per field, the type, whether it Contains personal data, Hide from pickers and Masking. A fact table holds events or lines such as orders or invoices; a dimension describes things such as customers or products; a bridge links two others. Grain (one row is one…) says what a single row stands for.

Look at the rows

The Data tab of the panel shows the first rows, either As the model sees it (after you published) or the Raw source. A column can be profiled: its distinct values, empty values, lowest and highest value and the most common values. Removing a table from the model never touches the source table.

A table selected on the map of the Model tab. The panel on the right has the tabs Properties, Data, Security and Used by; the Data tab is open with View as, As the model sees it and Raw source, and the first 50 rows.
One table selected: the panel on the right, here on its Data tab with the first rows.

The panel has four tabs when you select a table, a field or a figure: Properties, Data, Security (the rules that apply to it, owners only) and Used by (what else in the model uses it). Choose Open table page to see the table on its own page (see A table on its own page).

How do I tell the model that a field holds map codes?

Select the field and open Properties. For a text field (and for a whole-number field that holds a 2-digit postcode area) the panel has a Map role: Province (PV27), Municipality (GM0363), Postcode area, 2 digits (10) or Country, ISO code (NL). Choose the one that matches what the field holds. The values must be exactly those codes: PV27, not Utrecht, and GM0363, not 363. When the field lists sample values (a model that Cortex drafted records small lists of values), the model compares them with the codes when you save and warns when most of them are not codes of that role; the warning never blocks the save. A field without sample values is not checked: a code the map does not have is then listed under the map instead.

With a map role, a map tile can use the field and the layer follows from the role, and the dashboard assistant offers a map only on a field that has one. When Cortex drafts a model from your source, it proposes a map role only for a field whose name suggests a region and whose sample values are real codes; you confirm it like any other proposal. Choose None to take the role away again.

How do I relate two tables?

Drag from a field of one table to a field of another, or choose New relationship, pick the First field and the Second field and choose Review. Check the direction and the Cardinality (Many to one, One to many, One to one or Many to many) and choose Create relationship. A relationship joins two different tables: the studio refuses a relationship from a table to itself. Remove relationship takes it away again; the two tables stay.

Find your way on a large map

A model with many tables is easier to read through views. The map has filters (Kind, Source, Display folder, Certified only), a Detail control, Focus on a table with its Reach (1 link or 2 links), and Show all. Choose Save view to keep a selection of tables as a named View (New view, Update view, Delete view). A view made with filters is live: new tables that match appear in it by themselves. When you only look at a published model, Save as my view keeps a view that only you see.

See the model as code

The Model tab in code view: the definition of the model as JSON in an editor.
The same model as code: the definition (JSON), for people who prefer to read or edit it that way.

Switch the Model tab to its code view to read and edit the whole definition as Definition (JSON). Edits are checked as you type (Problems, with the line number). Choose Preview changes to see your edit next to the Current draft, Apply to put it in the draft or Reset to throw it away. Nothing is published until you publish. Right-click a table or figure on the map, or use Script this in the Properties panel, to jump to its JSON.

A table on its own page

Every table also has its own page, reached with Open table page. It opens on a breadcrumb (Models, the model, Tables, the table) and has the buttons Try a question and Add documents.

The page of the table Order results in the Factory model with the tabs Overview, Records, Figures, Links, Documents, Sources and Used by.
A table page: the tabs hold what the model knows about this one table.
The page of another table of the same model, on its Overview tab.
Another table of the same model: the Overview shows the fields, the figures defined on it and, where it has one, its hierarchy.
TabWhat it shows
OverviewThe description, the Fields (with the key), the Figures on this type and the Hierarchy (for example plant, line, machine).
RecordsThe records of the table, with their key.
FiguresThe figures defined on this table, with their unit and whether they are Certified.
LinksThe relationships: points to and points here from, the Kind and the Other end.
DocumentsThe documents filed on the table or on one of its records (see Documents and sources).
SourcesThe source the table is bound to (Primary) and any Enrichment.
Used byWhat uses the figures of this table. It asks you to publish the model first when that has not happened yet.

Explore: try a question on the model

The Explore tab is where you check that the model gives the answers you expect, before anyone else relies on it. Owners explore the draft; everyone else explores the published model.

The Explore tab of the Factory model: the switch between Ask the model and SQL, View as, a query tab, the list of figures to tick, the Run button, Describe it instead, Refine and the buttons under Save this query.
Explore: build a question from figures and fields, run it and look at the result.

The tab has two modes, Ask the model and SQL.

Build the question

In Ask the model pick one or more Figures, what to Break down by (a field, or Break down over time), Add a condition (Only rows where) and a Time window (All the data, The last…, A named period such as Year to date or Last 12 months, or From … to …). Choose Run. Use the plus button for a second Query in a new tab.

Read the result

The result is a table and a Quick chart. Next to a number, Check opens "Check this number": the statements the model ran for it, which you can run yourself, and the rows behind it (at most 100). It says whether the SQL gives the same number as the certified figure.

Refine it or describe it

Describe it instead lets you write the question in words. Refine shows the question as text that you can edit or Copy as request.

Keep it

Save this query offers As a dashboard tile, For use in my app, As a test query (kept in this browser, per model) and As a verified question. A verified question is checked every night once the model is published.

The SQL mode takes one SELECT statement over the tables of the model (press Ctrl+Enter to run it). The result is labelled "Exploration — not certified", is limited to 1,000 rows and keeps a History. Nothing you run here changes the model or the source.

Security: who may see and use what

The Security tab answers "who and what may use this model?". Rules are draft changes: they are saved in the draft and go live when you publish ("Saved in the draft, live when you publish."). The tenant Admin sees hidden tables and unmasked fields, but row rules and figure rules apply to the Admin too.

The Security tab of the Factory model: Who can read this model with the choices Everyone with access and Only these audiences, the block Who sees what with its buttons, and the Rules lists for rows, tables and fields.
Security: who can read the model, who sees what, and the rules behind it. Test as a person and the audiences are further down the page.

From top to bottom the page holds:

  • Who sees what: a matrix of what each kind of reader gets (the Admin, everyone else, a named person, Ask and AI). Choose Show the rule on a cell to jump to the rule behind it, or View as to look at the model as that reader.
  • Rules: four lists. Rows (row rules: "show rows where field = the person's attribute"; with none, everyone sees all rows), Tables (Hide a table: hidden from everyone except the audiences or roles you name under Visible to; with no audience only the Admin sees it), Fields (Mask a field, with a mask kind, and who still sees the real value) and Figures (Restrict a figure: Who can use this figure).
  • Test as a person: pick You (Admin), A person or An audience, the figures to try and a Reason (kept in the audit log), and choose Run test. It is read-only and audited, and masks stay masked.
  • Audiences: groups of people you name with New audience. Add members with Add person, Add group or Add app role (everyone who holds that role in Cortex Control is in the audience). A rule refers to an audience by its exact name, so an audience that a published rule uses cannot be renamed or deleted.

The ... menu at the top right of the page opens two more sections.

The Apps and actions section of the Security tab of the model hubspot-objects: Data access for this model, with a reason field and, per dataset, the environments Development and Production, each marked Approved.
Apps and actions: the read and write access the model needs, per environment.

Apps and actions lists the links to datasets (read) and the actions (write) of the model, per environment (Development, Production). The owner requests access here with Request, with a reason that IT sees, and IT approves it in Approvals; IT can revoke it at any time.

The AI approval section of the Factory model: Approved for AI, the switch Ask and MCP see only figures I approved, the count 145 of 145 approved and the figures with a tick box each.
AI approval: decide with which figures Ask and AI tools may answer.

AI approval (Approved for AI) decides with which figures Ask and AI tools (MCP) may answer. Switch Ask and MCP see only figures I approved on and approve figures one by one, or use Approve all described figures. The Hub and dashboards are not affected. Switch to editing first if you only look at the model.

See Access and security for the idea behind these rules.

Documents

The Documents tab is the document library of the model: manuals, procedures and scans that Ask can quote. Adding, filing, searching and erasing documents are covered on Documents and sources.

Health: what to fix next

The status chip in the top bar ("3 to fix", or "Checking… (2 of 9)" while the checks still run) opens Health. It is one list of what to fix next, whatever the source, each row tagged with where it comes from.

The Health view of the Factory model: a readiness ring at 75 percent, What to fix next, the filters All, Readiness, Questions nobody could answer, Suggestions and Checks, and a list of things to fix with a Fix button each.
Health: the ring shows how ready the model is for Ask and AI tools; below it, one list of what to fix.

The ring reads "n% ready for AI". Narrow the list with Show: All, Readiness, Questions nobody could answer, Suggestions or Checks.

SourceWhat a row meansWhat you can do
ReadinessSomething that makes the model harder for Ask to use: a missing description, a figure without synonyms, an uncertified figure.Fix opens the spot. Fix with the AI asks the assistant.
Question nobody could answerSomething people asked that the model could not answer ("asked 4 times and not answered"). The type tells why: Unanswered, Refused, Thumbs down, Requested, Failed test, Unknown name.Draft a fix, Resolved or Dismiss.
SuggestionA change a colleague proposed ("Suggested by …").Add to draft or Dismiss. You cannot add your own suggestion: another owner has to.
CheckA nightly check that fails (see Model checks).Open it for the detail.
ProblemA problem in the draft itself.Fix.

When there is nothing to do, Health says "Nothing to fix here. The model is in good shape."

How do I publish a model?

Choose Publish in the top bar. It opens the Publish tab.

The Publish tab: the live version, Changes since the published version (none here), the list of Checks and below it the field What changed? for a note.
Publish: the live version, what changes, the checks and a note for the version history.

Read what changes

On the left are the Changes since the published version (each marked Added, Changed or Removed), the Risks for what uses this model and Affected: which apps, dashboards and assistants use what you changed. At the top it says which version is live ("Live: version 3") and who the Owners are. Next to the section switch, "n of m figures certified" has a link Open the next one to certify.

Fix what blocks

On the right are the Checks of the draft. A failing check marked Blocking stops publishing: "Fix the failing checks first." While the checks run, the button waits: "Checking… (2 of 9). Publish opens when the checks are done." A model that reads an app's test data shows a warning, which you can still publish through.

Write a note and publish

Write what changed under "What changed? A note for the version history" (the assistant can fill it in for you; read it first) and choose Publish. Publishing makes this version live at once for every app and dashboard that uses the model, and for Ask. Only an owner of the model can publish; for everyone else the tab says so. With no changes the button stays off ("No changes to publish").

A version that was proposed before publishing became one step can still be waiting. The tab then says "Version 3 was waiting from before" and offers Make it live or Discard.

Versions: go back to an earlier state

The Versions section of the Publish tab (the switch at the top) keeps every published version.

The Versions section of the Publish tab: every published version with its status, name, who decided and when, and the buttons Export and Restore to draft.
Versions: the history of the model.

Each version shows its note, who published it ("by Sam de Vries") and, for an admin override, Admin override. Restore to draft brings that version back as your draft, ready to publish again. Export saves it as a Cortex envelope (JSON), an OSI document (YAML) or a Power BI model (TMDL, zip).

How do I see the model as someone who does not own it?

Next to the model an app or dashboard is built on you see Model guide. For people who do not own the model it opens the published model, read-only, exactly as it is for them: a hidden table or a restricted figure is absent. A banner says "Model guide: this is the published model as it is for you." They can save their own views with Save as my view. They do not have the Checks, Health, Publish or the Security rules. Owners and admins see the full studio.

How do I add owners, include another model or archive a model?

Open ... and then Settings (Model settings). Add an owner (for now it asks for the person's Entra object id) or remove one; a model needs at least one owner. Archive model removes it from the list; what already uses its published version is not touched. Includes lets a model include another model's tables and figures; a part that comes from an included model is read-only here, so change it in that model. Export a version and Import a model move a model between installs as a file.

How do I start the company model, and what about names?

On an install that still has separate models, an Admin sees Start the company model at the top of Models. It opens a window that lists what happens before anything changes: which models become sections (ready-made packs are marked; they are managed by the platform from then on), what has to be fixed first (a model that still includes another model), which models stay as they are (a model that uses a name an earlier model already holds is left out of the company model and stays a plain model, with the names and the reason listed; it does not block the start), and what moves (the saved questions of dashboards and apps, the row-access values, the cached results). Owners, readers, drafts, access grants and document libraries stay on their own section, and the old model ids keep working. Nothing is deleted. The start also makes an empty Core section (the shared customers, items and dates), owned by the Admins until the data owner assigns someone. Choose Start the company model and the page turns into the company home. Starting twice changes nothing.

All sections share one name space: a table, figure or relationship name exists once in the whole company model. Names are not secret. When you pick a name that is already taken, the message may tell you that, even if the section that holds it is one you cannot read. Only the fact that the name exists is shown, never its data, its definition or the section it belongs to.

The company model page and its section filter

Once the company model is started, Company model in the Studio group opens one page for the whole company model, at /company-model. Its bar has the tabs Overview, Figures, Checks, Model, Explore, Security and Documents, a Health chip and the Publish button. The Overview is the company home (tables, Sources, Sections, waiting items) with a card for each tab (Figures, Checks, Model, ...); a card opens that tab.

Pick a section in the Sections panel to filter the page to it: a chip Section: <name> appears under the bar and the address gets ?tab=<tab>&in=<section>. The small x on the chip shows all sections again. Next to the chip, Tables and Get data opens that section's tables page, where you get a table from a source. You see it only where you may work on that section's tables: an Admin; an owner of that section who has a Studio seat; or a Builder, unless the section is a ready-made pack. Everyone else does not get the link. Until each tab has its own company screen, a tab lists the sections you may open that tab in, one row per section; sections you may not open there are counted in one line, never named. Publish · N counts the sections you may publish and opens that list (or, with a section filter, that section's Publish tab).

Example: a new product line at Brightwater

Sam de Vries at Brightwater Foods owns the Sales model. The company starts selling a range of oat drinks and wants revenue per product line in dashboards.

  1. Sam opens Models, opens the Sales model and chooses Add and Add table. Sam picks the product-line table of the sales system. It says In model afterwards.
  2. On the Model tab Sam drags from the product field of the invoice lines to the key of the new table and chooses Create relationship with cardinality Many to one.
  3. On the Figures tab Sam describes "revenue per product line" in words, checks the number on Explore and certifies it (see Figures and certification).
  4. The status chip reads "2 to fix": the new table has no description. Fix opens it; Sam adds one.
  5. On Publish Sam reads the changes (one table added, one relationship added, one figure added), sees that two dashboards are affected, writes "Product line added" and chooses Publish.

The same evening the checks run on the published version, and the next morning the Overview says "31 of 31 figures proven tonight".

Questions and troubleshooting

On this page