Skip to main content

Managing your models

Managing your models in Omni can be done through the workbook layer or the development IDE. This is made possible by Omni's layered approach to maintaining your data and allowing users to promote those changes to the different layers, i.e. model layer and workbook layer. We also offer a dbt integration that allows you to access that layer as well.

Users can model and query in the workbook model layer and leave all the content they create isolated to that workbook. If users want to make the changes in that workbook reusable and accessible to other users, the changes need to be promoted to the Shared Model. This action pushes the workbook model changes to the model layer and new workbooks will include the changes that were pushed.

Shared Model Promotion​

info

Connection Admin or Modeler permissions are required to promote workbook changes to the shared model.

Shared model promotion is an important facet of model editing within the workbook model layer. Shared model promotion pushes changes made in the workbook layer into the model layer so the changes are reusable and available in all workbooks. Model promotion can be done a number of ways depending on your workflow preferences:

Promote all changes​

Promote all of your collective changes into the Shared Model any time from the workbook Model menu option, Promote to Shared.

Incrementally promote workbook changes​

Incrementally promote changes to the Shared Model by clicking on the branch icon to the left of the workbook. This is a handy feature for changes that are not quite ready to go live to the masses yet.

Note this option only works while making changes using Branch Mode. Learn more about Branch Mode.

Editing in the IDE​

Edits made directly in the develop model IDE will be "Promoted to the Shared Model" as soon as the file is saved. For more structured development processes, explore the branch mode and git integration options.

Branch Mode​

More structured than document drafts but less complex than the git integration, Branch Mode allows you to test changes to models and content before making them visible to your teammates.

By creating a separate space to experiment with updates, you can develop confidently without disrupting production data. This approach supports scalable and reliable workflows, reducing the need for reactive fixes while improving traceability and accountability in the development process.

Refer to the Using Branch Mode for collaboration guide for more information.

Validating models against content​

The Content Validator, accessible by clicking the (checked document icon) in the IDE's left navigation, helps you keep your content accurate and up-to-date as your data model evolves. If a field is renamed, a table is swapped, or a topic is removed, the validator makes it easy to spot where things broke and quickly fix them - either one by one or in bulk.

Additionally, the Content Validator is a powerful discovery tool: you can search for all the content that references a specific field, view, or topic to see how widely it’s used before making changes. This way, you can make updates with confidence and ensure nothing slips through the cracks. Refer to the Content Validator guide for more information.

Model editing​

tip

Check out the Common publishing workflows guide for example workflows that use best practices to develop Omni content and models.

Edit a Model in the Workbook Layer(Easy Mode)​

The workbook allows users to not only explore data but it also allows users to create new model content like topics, relationships (joins), new fields, SQL views and fields, as well as promote those all from the workbook model layer back into the model layer.

Create a Topic​

Topics curate the views that are joined together for exploring (querying) data in the workbook view.

  1. Starting from your Omni app's homepage, click on the ** + New** button in the top left corner of your Omni app's homepage.
  2. Select the database connection you want to use. Now we have two options:
Create a new topic​
  1. At the bottom of the list of Topics, click on the All Views * Fields option in the Advanced section. This will show you the views and the fields in those views available in the model connection you chose.
Topic with a single view​
  1. In the view's menu, click on the Modeling option then choose Make Topic.
  2. The topic is now available in this workbook model.
  3. To promote this topic to the Shared Model, choose from an option outlined here. #ADD A LINK#
Topic with multiple views (Joins)​
  1. Hover over the view name that you want to set as the base view and click on the vertical three-dot icon that appears.
  2. Click on the Set as Base View option. This hides the other views field picker menu.
  3. After opening the view's menu and clicking on Joins there are two options: a. Omni makes a suggested join, it's the option with the links icon to the left of the suggested view name.
    • Clicking on this option still opens up the Join modal but all of the join options are pre-populated based on inferred knowledge of the fields in the two views.
    • (Optional) Edit the choices in the parameter options.
    • Click Update. b. Clicking on + New Join opens up the Join modal. Walk through the field inputs in the pop-up modal to create a new join. Repeat this process for adding multiple joins back to the base view. This method is only recommended for joins requiring one join condition in the ON clause.
    • Choose the view to join from the Choose right view drop-down.
    • Click on the fields you want to join on. Recommend choosing a field like a unique ID.
    • The default join type is a Left join but other join types like inner, full outer and cross joins are also available.
    • In the Relationship (Advanced) field can you can click on the Infer Relationship button in the bottom left of the modal. This will populate the assumed relationship into this field. Alternatively, if you know your join relationship choose one of the options from the drop-down.
    • We recommend only adding joins to your current topic. Use the Add to all possible topics option with caution as this may expose data in workbooks that should not be seen by certain users.

Edit a Model in the IDE (Hard Mode)​

Create Your First Topic​

  1. Navigate to your Omni app's homepage.
  2. Click on the ** + New** button in the top right of your Omni app's homepage.

Quick tips​

  • Omni automatically adds joinable tables by default when you set up your connection.
  • Users can curate the list of joinable tables to add or remove specific tables.
  • New joins can be added to topics using the relationships file or custom joins per-topic basis.

Model History​

Model history in the developer IDE allows users to see the changes made to the model and restore to an older version.

Explore & Compare Older Versions​

The left-hand menu includes a chronological list of time-stamped changes. The detailed view to the right of the list of changes, compares the previous change to the currently selected version.

Restore an Older Version​

Restore a previously saved version of your model files by navigating to the change you want to restore to.

  1. Click Preview restore

  1. Compare the changes in all affected files.

  2. Select Restore this version.

Incorporating database changes with schema refreshes​

Keeping your BI tool in sync with your database when schema changes occur can be a challenge. As such, there may be times when you need to manually refresh the schema model - or make Omni aware of the changes - that your Omni model is built on. This can be done from the Model menu in the Shared Model IDE, via the Connection page in the Omni settings panel, or via the Omni API.

The shared data model exists in two layers:

  • The schema model from the database, and
  • The user-generated, virtual fields that exist only in the Omni layer

Omni performs two types of refreshes to the schema model:

  • Hard Refresh: all changes to the source database will be reflected in the schema model. If structures from the source database have been removed, Omni will also remove them from the shared model.
  • Soft Refresh: Omni will only make additive changes to the shared model. New structures and changes to existing structures will propagate into the Omni schema model but anything that has been dropped from the source will remain.

Triggering schema refreshes​

Schema refreshes can be triggered manually, automated on a schedule, or via API. When you kick off a refresh, this will start a job that runs in the background. This can take several minutes depending on the size of the database.

Hard Refresh Triggers

Manually refreshing the entire Schema model via Model > Refresh schema in the model IDE (no filtering to a specific database schema or tables in the refresh schema dialogue flow), refreshing schema in the connections page of the settings panel, or via the Omni Model API

Soft Refresh Triggers

This includes scheduled schema refreshes and opting to refresh specific schemas via Model > Refresh schema and tables by listing them individually or using wildcard syntax, such as sales_*.

Manually triggered refreshes from Model > Refresh schema in the model IDE offer a few additional options over other methods:

  • Refresh specific schemas and tables by listing them individually or using wildcard syntax, such as sales_*.
  • Checking Skip SQL validation, which will skip validating views that use SELECT * and speed up the refresh. You can opt to perform a subsequent, targeted refresh for these views if needed.
Refreshing dbt

Performing a schema refresh for dbt differs slightly than those performed on a "regular" database schema. Specifically, Omni will:

  • Search the schema for views that correspond to dbt models and add dbt metadata to them
  • If available, generate primary key definitions and relationships based on constraints

Note A manual refresh of the entire Shared Model is needed to remove tables from the Schema and Shared model, this is considered a "hard refresh". Schema Refreshes where specific database schemas or tables have been filtered to as well as recurring scheduled schema refreshes are considered "soft refreshes" which are additive only and will not remove views if the underlying database table has been dropped.

Resolving broken references​

Changes made as a result of a schema refresh may result in broken references in Omni. Use the Content Validator to identify and resolve any issues.

Export to dbt​

We want to make model management easy both in Omni and below the BI layer. To this end, we offer the ability to export a view file's dbt SQL. This will allow users to build fact tables, or virtualized fields into their dbt models beneath Omni.

Currently this will require some rework of your Omni model, because new dbt views will then be populated into the model upon schema refresh. This means field references would need to be remapped to maintain continuity. In the future the intent is for this promotion to become button-click.