Use these tools to move a semantic model through a .semanticModel file, bring an updated model back in, or change the table behind one BI table without rebuilding the model. An update from a file and a table replacement each show a review before they run, and you can revert either one afterwards.
Export a semantic model to a file
Right-click the model in the tree and choose Export .semanticModel.... You can also open the model, click More actions and choose Export .semanticModel.
Your browser downloads a .semanticModel file named after the model. The toast reads Exported followed by the file name, with the notice "The file contains row-level security members and conditions."
The file is one JSON document with the model's own objects: its BI tables and columns, relationships, measures, measure tests, folders, field parameters, the diagram and the row-level security rules. It records format version 1, or version 2 when the model uses Type and version columns (Check, document and trace a model). Both versions import. It does not carry reports, data or history.
Warning
The file contains who can see what. It includes the row-level security groups and members of the model. Store and share it with the same care as the access it describes (Row-level security and View as).
Import a file as a new model
On the DataPrism home page, click New semantic model in the header, or click New > New semantic model in the workspaces panel.
Under Import from file, click Choose a .semanticModel file and select the file. The button reads Reading the file… while it loads, and the file can be removed again before you import.
Check the settings. The file fills in what it can:
Setting
What it does
Filled in from the file
Name
The name of the new model.
Only if you have not typed a name
Owner role
The role whose Lake and Warehouse tables the queries run against. Cannot be changed after creation.
Only if it is a role you can create models for. Otherwise empty
Data mode
Clear Values reads original values, PII columns included. Tokenized PII reads tokenized stand-ins for PII columns. Cannot be changed after creation.
Clear Values or Tokenized PII only
Choose the Workspace, then click Import semantic model. The toast Semantic model imported confirms it, or Imported with issues offers Open model.
The dialog hint reads: "BI tables are matched by core table name in the owner role you pick; anything not found is skipped and listed." Without a file, the same dialog creates a model and its button reads Create (Semantic models and BI tables).
Update a model from a file
Open the model, click More actions and choose Update from file....
Select the file. A preview dialog opens, titled Update "<model name>" from <file name>, and reads Building the preview while it builds.
Read the summary: a chip per object type counts what is added, changed and removed, and how many entries are unchanged. Changes are grouped by BI tables, Columns, Relationships, Row-level security, Measures, Tests, Folders, Field parameters, Diagram and Model, each marked add, change or remove. A rename shows the old and the new name, and a long list shows its first 50 entries with a Show all {n} link.
Leave Delete what is not in the file off to keep objects the file does not contain, such as measures you added after the export. Tick it to remove them.
Click Apply.
Worth knowing before you apply:
Removals are listed either way: with the checkbox off they read kept, with it on will be deleted, and a removal that cannot be undone says so. A BI table that is the fact table, is targeted by row-level security, is referenced by measures or is used by charts is kept, with the reason shown. Other BI table removals cannot be undone; a removed measure can be restored by a revert.
A file never rebinds a BI table to a different source: when the file carries another core table for it, the preview keeps the current binding, applies the rest and points you to Replace table with....
Anything the import cannot match or use appears under Will be skipped with its reason. When nothing differs, the dialog says "The model already matches the file."
An update keeps the model's name, owner role and data mode. When the file carries a different name, the preview warns that the name in the file was not applied, and a different owner role or data mode is called out as something that cannot be changed.
When the file carries different row-level security, it replaces the model's as a whole: groups the file does not contain are removed even when Delete what is not in the file is off. The panel says Row-level security will be turned on, will be turned off or will be replaced by the file's, and warns that until the import finishes, only admins see rows of this model. If the file's row-level security cannot be applied, Apply stays disabled and the preview gives the reason.
Apply the update and read the report
After Apply, the report dialog is titled Import applied, or Import applied with issues when something was skipped or failed. You cannot close the dialog while the update is applying.
Read the row-level security line and the per-object list. When the file carried rules, the dialog shows Row-level security: followed by the outcome. Each object shows Applied, Skipped, Kept, Failed or Not attempted; failed and kept items come first, then skipped, not attempted and applied, and an item that cannot be undone says cannot be undone. An item can add a Because line naming what its failure followed from. A very long list is cut with the note "Only the first 10000 items are listed; failed, kept, skipped and not attempted items come first."
An import is applied object by object, not as one transaction. If it runs out of time, what it applied stays and the note reads "The import ran out of time; objects it did not reach were not attempted."
Click Revert import to undo the update now, or Close to keep it.
Row-level security statuses read Not in the file, Unchanged, Applied, Failed, model closed, Failed, previous kept or Not attempted. Failed, model closed means the file's rules could not be applied and the model is closed: nobody except admins sees any rows until a model editor fixes it.
Undo an import
Right after Apply, click Revert import in the report.
Later, open the model, go to History and click Revert under Imports.
Imports lists each update with its file (or Imported file), who ran it (or Someone), a summary and its state, with View report and Revert; a reverted import names who reverted it and when. Hover an Interrupted or Revert interrupted state to see what to do, and run Revert again to finish an interrupted revert. Only one revert runs at a time. The list is covered on Change history.
The confirmation Revert this import? explains: "Every change it made is undone, except objects someone changed since (they are skipped) and deleted BI tables (they cannot come back)." The result reads Import reverted, or Revert did not complete when something could not be undone, and counts the reverted, skipped, failed and irreversible steps, listing each step that was not reverted with its reason.
If a revert is refused, you see "This import was already reverted.", "This import is being reverted.", or "This import is still being applied, or it stopped less than 15 minutes ago. Try again later."
Replace the table behind a BI table
Right-click the BI table in the tree and choose Replace table with.... You can also use Replace table on the diagram's table toolbar, or Replace in the BI table popup.
Pick the new Lake or Warehouse table and click Review. The check reads Checking the measures against the new table..., and applying reads Replacing... the measures are checked again.
Read the review. It shows Columns, Measures and Relationships; sections that apply only sometimes include Reports with charts on deleted columns, Field parameters on deleted columns, Sort-by pairings removed, Row-level security groups checked and Warnings. If the replace is blocked, the banner This replace is refused gives the reasons and Replace stays disabled.
Click Replace, then Done. If some measures could not be checked, the dialog offers to re-check them ("Re-check the measure that was not checked", or the plural form when more than one), up to 500 measures.
The BI table keeps its name, id, measures and relationships. Columns are matched by name. "Measures are never deleted: a measure that no longer works turns red until you fix it by hand or with the AI" (Measures, Model AI).
If someone changes the model while you review, the dialog shows "The model changed since this preview. Review the new preview." and rebuilds the review.
To undo a replacement, click Revert in Done and confirm the warning. You can also open Table replacements in the model's History and click Revert on a row; only one revert runs at a time. The old table reads again: columns the replacement removed come back with their settings, relationships it removed are recreated, and columns it added are removed. Settings you changed since stay. The result confirms the table reads the old table again, lists anything kept or not restored with its reason, and says how many measures are still red if any are.
Note
Replace is not offered for a BI table opened from a report. In the model editor it stays disabled while the popup has unsaved changes: "Save or discard your changes first."
Export .semanticModel, Update from file... and Replace table with... need Edit DataPrism Semantic Model, and the model's More actions menu appears only for users who can edit the model.
Creating a model from a file needs Add DataPrism Semantic Model and Edit DataPrism Semantic Model: the file field appears only for users who can edit, and the import creates a new model.
The Imports and Table replacements lists in the model's History need edit access to the model.
A file can be up to 32 MB. A larger file is refused with "The file is larger than 32 MB."
A file that is not valid JSON, is not a .semanticModel file, uses an unsupported format version or has no model name is refused before anything changes. Deeper checks are answered with a sentence that begins invalid .semanticModel file:.
One import or revert runs on a model at a time; a second is refused with "An import or a revert is already running on this semantic model." When too many imports run at once, you see "Too many imports are running right now. Try again in a minute."
An import runs for up to nine minutes. If a request times out, check before retrying: "The import is still running on the server. Check the model (or its History) before retrying." A preview that takes too long changes nothing: "The preview took too long on the server. Nothing was changed; try again."
If the members named in row-level security cannot be looked up, the action stops with "The user directory is not available right now. Try again in a minute."
Two sections can be too large to store and are skipped with a warning in the report: field parameters over 1 MiB and diagram positions over 256 KiB.
A file over an object cap is refused with a sentence naming it, for example "the file has 301 BI tables; at most 300 can be imported." The capacities a model can hold are on Limits and capacities.
Questions, answered
What does a .semanticModel file contain?
One JSON document with the model's BI tables and columns, relationships, measures, measure tests, folders, field parameters, the diagram and its row-level security rules. It records format version 1, or version 2 when the model uses Type and version columns, and both versions import. It does not carry reports, data or history, and it includes the row-level security members, so store it carefully.
Why were some BI tables skipped on import?
BI tables are matched to core tables by name in the model's owner role. A table that role cannot reach is skipped and listed; a new model matches in the owner role you pick in the dialog.
Why were the field parameters or the diagram not imported?
If the field parameters pass 1 MiB or the diagram positions pass 256 KiB, the model cannot store them and the import skips them with a note in the report. Slim the field parameters, or re-arrange the diagram and export again.
Will updating from a file remove measures I added?
Only if you tick Delete what is not in the file before Apply. Leave it off to keep anything the file does not contain. With the checkbox on, a removed measure can be restored by a revert.
Can I undo an import?
Yes. Click Revert import right after Apply, or later click Revert under Imports in History. Objects someone changed since are skipped, and deleted BI tables cannot come back.
Why does the import report list objects as "Not attempted"?
The import reached its time limit before those objects, and they were left unchanged. Check them and update from the file again.
Why is Apply disabled in the update preview?
Apply needs a usable preview. It stays disabled until the preview is ready, and also when the file's row-level security cannot be applied; the preview explains why. Fix what it describes, then update from the file again.
Why can nobody see rows while an import is running?
When the file turns row-level security on, the model is closed first: the rules are on with no groups until the import finishes, so only admins see rows in the meantime. The preview warns about this window before you apply.
Why does the import say the model changed since the preview?
Someone changed the model after you opened the preview. The dialog rebuilds it and says "The model changed since the preview. Review the updated preview." Review it, then click Apply again.
Where do I see a model's earlier imports?
Open the model and click History. The Imports section lists every update from a file, with View report and Revert on each row, and a reverted import names who reverted it and when (Change history).