Check, document and trace a model

Use the tabs of a semantic model to find problems before they reach a report, to explain the model to its readers, and to see who changed what and which reports depend on it. Checking and changing a model needs edit access to that model.

Check a model's health

The Model health panel lists the problems it finds in a model's measures, BI tables and relationships.

1. Open DataPrism from the sidebar and open the semantic model.
2. Click Health. The check runs when the tab opens; while it works the panel reads Checking the semantic model, and a Semantic model checked message appears when it finishes.
3. Read the findings. They are listed worst first and grouped by Errors, Warnings and Info, with a count on each group, for example 2 errors. If the check cannot load, the panel shows the error with a Retry button.
4. Click a family chip to hide or show its findings. The families are Structure, Static, Data, Usage and Hygiene; they cover how the model is put together, the SQL inside its measures, checks that run queries, how measures are used, and housekeeping such as missing descriptions and documentation.
5. To check only part of the model, open the scope button, which reads Whole model. The popover lists Measures and BI tables; use the search box, which reads Search measures and BI tables, to find them. Tick the ones you want and click Check selected. The button then reads Selected (2), and the note in the popover reads At most 500 measures and 500 BI tables per check. Clearing every tick and applying takes the scope back to Whole model.
6. To include data checks, turn on Include data checks. It is off by default, and its tooltip reads Runs queries against the warehouse without row-level security, up to 30 seconds. When data checks are included, the findings carry the note Data checks run without row-level security.
7. After you change the model, click Re-run; it stays disabled while a check runs. Findings do not refresh by themselves.

The toolbar also carries Run all tests, which runs the model's measure tests and shows progress while it works, for example Running tests 3 / 12; it is disabled while the tests run. See Measure tests for running tests in detail. A Checked line shows the time of the last check. When the check finds nothing, the list reads No findings.

Each finding shows its family, the object it applies to, a message and, where one exists, a suggested fix. Some findings have a link or a button:

• Open docs opens the Docs tab. It appears on the finding that says the model has no documentation.
• Open Type and version columns opens the settings for a Type or version column that no longer exists.
• Ask Model AI sends the finding to Model AI as a request. Model AI proposes any change, and you approve it there. See Model AI.
• A finding about a relationship can be clicked to reveal the source BI table behind it.

Common findings include:

• The model has no fact table, so no measure can run.
• A measure is broken after a change such as a table replacement; the wording names the measure and the reason, and the fix points to Measures.
• A measure that uses SQL that is no longer allowed. It still runs, but saving its SQL is refused until it is rewritten.
• A measure that adds up rows of every Type value, so a chart mixes them (for example actual and budget).
• A measure that divides by count() without a guard; the suggested fix wraps the divisor, for example / nullIf(count(), 0).
• A BI table that has no relationship path to the fact table; charts that use it with measures fail with cannot be joined.
• A measure that has no description, or columns that have no description and no DWH comment.

Document a model

Documentation tells readers what the model is for, where its data comes from and how to read it.

1. Open the semantic model and click Docs.
2. In Description, write one or two sentences about what the model is for; the field's hint reads What this model is for, in a sentence or two.
3. In the editor below, write the documentation; the hint reads Document this model: sources, grain, definitions, caveats.
4. Click Save. Save and Discard stay greyed out until there is something to save, and Ctrl+S saves while you edit.

While you have unsaved changes the panel shows Unsaved changes, and the tab reads Loading documentation while it opens. From 180,000 characters a counter appears and counts up as you type, reading n / 200000. If a save goes over the limit, the message reads The docs of a semantic model may not exceed 200000 characters.

If someone else saved the model while you edit, Save opens the reload-or-overwrite dialog, the same one other model edits use.

Readers who can open the model see the same tab read-only. An empty description reads No description, and if the model has no documentation, they see No documentation yet.

Links in the documentation work only for web addresses and email addresses (http, https and mailto), and images render only when they are inline data images or come from the same site.

Review the change history

History lists changes to a model's tables, measures, relationships and row-level security, newest first.

1. Open the semantic model and click History. The list reloads when you open it, and the header shows the number of changes.
2. Click a change to open its details.
3. Read Changed by and the values before and after the change. If the change rewrote other measures, Dependent measures rewritten lists them.

Not every edit is recorded as an event: description and documentation edits, column curation, and format or hidden changes do not appear.

When the warehouse table behind a BI table is dropped, or stops being visible to the model's owner role, the model removes that BI table and the removal appears here with the reason.

The tab also carries an AI changes section for what Model AI did, a Table replacements section for replaced sources, and an Imports list for updates from file (Model AI, Model files and replacing a table). For every kind of change and how its detail reads, see Change history.

See which reports depend on a model

The Dependencies tab shows the reports that use the semantic model. It is greyed out when no report uses the model yet.

1. Open the semantic model and click Dependencies.
2. Under Show, choose This model (the default) to see the model and its reports, or All models to see every model you can open and its reports.
3. Under View, choose Diagram (the default) or List.

The header carries the counts, such as 4 reports for this model or 4 reports · 6 models under All models. While the tab loads it reads Loading lineage; if the load fails it reads Could not load lineage. When there is nothing to list, it reads No dependent reports with Reports that use this semantic model will appear here. and an Add report button that creates a report on the model and opens it in edit mode. The current model is marked with an Open chip; the other cards open a model or one of its reports. Reports and models you cannot open are counted, not named.

To see where a model's data comes from and where it goes, use Explore and trace lineage.

Set the Type and version columns

Use these columns when a model holds different kinds of rows in one table, such as actual and budget rows. Model health then checks that each measure picks the rows it should.

1. Open the semantic model and choose More actions > Type and version columns. You can also open the dialog from the Type chip beside the model name, or from the Open Type and version columns link on a finding.
2. Under Type column, pick a BI table and then a Text column. The column field reads Pick a BI table first until a table is chosen, and a table with no text columns reads No text columns in this table. Choose No Type column to remove it.
3. Under Version flags, click Add version flag. Pick a Flag column (a boolean or whole-number column); a table with none reads No boolean or whole-number columns in this table. Then type each Type value the flag versions, for example Budget, and press Enter or comma after each one. The value field's placeholder reads Add a value, e.g. Budget; once a flag holds its 20 values, the field reads Limit reached and takes no more.
4. Click Save. The button is enabled once you change something, and reads Saving... while it saves. Save waits for every flag to name a BI table and a column; the message reads Pick a BI table and a column for every version flag.

When no Type column is set, the dialog explains what one is for: telling actual rows from budget rows (or orders from shipments), so model health can check that every measure picks one. A version flag marks the current version of plan rows, for the Type values it versions. The counter beside Version flags reads n/10.

Other users see a read-only summary with the headings Type column and Version flags; empty lines read No Type column and No version flags.

Who can do what

The Imports and Table replacements lists in History also need edit access to the model. For the full list of permissions, see Who can do what in DataPrism.

Limits and edge cases

• Check selected takes up to 500 measures and 500 BI tables per check.
• A check lists its findings worst first and shows 200 findings at a time. Click Load more to see the next page. If a check finds more than 2000 findings, the page shows More than 2000 findings; narrow the scope. Narrow the scope and check again.
• Data checks share a 30-second limit. A data check that runs out of time is listed under Not checked (N). Expand it to read each entry; it names the check, the object and the reason, such as time budget exhausted. Data checks cover the first 25 relationships and 25 measures of the scope, so narrow the scope on a large model.
• Findings are built on each run and are not kept. The check runs when you open Health and when you click Re-run.
• History keeps the newest 200 changes, and its Imports and Table replacements lists keep the newest 20 entries each.
• The description takes up to 10,000 characters. The documentation takes up to 200,000 characters.
• The Type column must be a text column. A version flag must be a boolean or whole-number column. You can add up to 10 version flags. Each flag takes up to 20 Type values, and each Type value can be up to 100 characters long.
• A column can be a version flag only once, and a version flag cannot be the Type column.
• With a Type column or a version flag set, the model file is written as format version 2; clearing them writes version 1 again. See Model files and replacing a table.
• If someone else saves the model while you edit it, you see This semantic model was changed by someone else. Click Reload to see their version, or Overwrite to save yours.
• If you see This DataPrism service does not store Type and version columns yet., the dialog stays read-only and you cannot save these columns.

Questions, answered

Why do data checks find rows I cannot see in reports?

Data checks run without row-level security, so they read every row. A finding can describe rows that a viewer's row-level security would hide. To see what a particular viewer gets, use View as.

Who changed this measure yesterday?

Open History and click the change. The details show Changed by and the values before and after the change.

Which reports use this model?

Open Dependencies, set Show to This model and set View to List. The list shows the reports that use the model. It does not show which of them will break after a change, so check them after you change the model.

Why is the Dependencies tab greyed out?

No report uses the model yet, so there is nothing to trace. Once a report uses the model, the tab opens; if its list is empty it reads No dependent reports and offers Add report.

Why can I not see Health, Row-level security or History?

Those tabs appear only to people who can edit the model. Ask someone who manages access to give you edit access. For the permissions involved, see Who can do what in DataPrism.

Our fact table mixes actual and budget rows. How do I stop wrong totals?

Set a Type column in More actions > Type and version columns. Model health then warns about each measure that adds up rows without picking a Type, and about measures that ignore version flags. Change those measures in Measures so that each one picks the rows it needs.

Can AI help with a finding?

Yes, if you have edit access to the model and the Use DataPrism AI permission. Click Ask Model AI on the finding; it is sent to the Model AI chat as a request. Model AI reads the model's checks and documentation before it proposes a change, and you approve that change before anything is saved. See Model AI.

Why are Save and Discard greyed out in Documentation?

They activate only when there is something to save. Until you change the description or the documentation, and while a save is running, both stay disabled. Discard drops your changes without saving; Ctrl+S saves the same as Save.

Why did my chart refresh?

A change by someone else is sent to the reports that are open on the model. Charts that a measure change affects refresh together, about once a second; table, column and relationship changes refresh the diagram, and deleting a model refreshes the lists it appeared in. A tab you left refreshes when you return to it. If your connection drops, everything reloads once it is back.

Are check results kept after I leave the tab?

No. Findings are built when the check runs and are not stored. The check runs when you open Health and when you click Re-run; editing the model does not refresh the findings.

Does checking a model run queries?

Only the data checks do, and only while Include data checks is on. The other findings come from the model itself. Data checks run queries against the warehouse, without row-level security, inside a 30-second budget. See Row-level security and View as.

A BI table disappeared from my model. Why?

When the warehouse table behind a BI table is dropped, or stops being visible to the model's owner role, the model removes that BI table. History shows the removal with the reason. If the table is available again, add it to the model; see Semantic models and BI tables.