Using Branch Mode for model versioning & collaboration

More structured than document drafts but less complex than the git integration, Branch Mode allows you to test changes to models and impacted content before they go live.

By creating a separate space to experiment with updates, Branch Mode allows you to 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.

Branching in Omni

What's a branch?

If you're familiar with git - and it's okay if you're not! - branches in Omni are similar.

In Omni, a branch is an isolated copy of a model that allows you to make changes without affecting the live version - typically referred to as production - used by queries. This enables you to experiment, update, and refine the model before applying any modifications to the live environment.

Why use branches?

To demonstrate why branches are useful, let's take a look at a few examples.

When changes are made directly to the shared model, the model's history might look like this:

The changes in this example were immediately applied to the model. If a query had been using the modified field, its logic and results could have changed unexpectedly. These differences might not be noticed right away, potentially leading to incorrect conclusions or broken content.

Now consider this example, where changes were made in a branch and merged back into the shared model:

In this example, the change to the field logic was only applied to the model in the branch. You could navigate to workbooks that use the field, open the branch, and immediately see the impact your changes would have. If everything looked as expected, you would then merge the branch and apply the changes to the live version of the model.

Want to learn more?

Check out this blog post to learn more about why traditional development practices - like branches - are useful for modern data teams.

Where can branches be used?

Branches can be used in the model IDE and workbooks, but there are some limitations on how they work in workbooks.

Who can use branches?

Your connection permissions determine the level of access you have to branches:

	View branches	Create branches	Merge branches
Viewer	X No	X No	X No
Restricted Queriers	X No	X No	X No
Queriers	✓ Yes	✓ Yes	X No
Connection Admins	✓ Yes	✓ Yes	✓ Yes

Note: Create branches also includes the ability to make changes within a branch.

Do branches work with the git & dbt integrations?

Yes! When the git is configured for a connection, Branch Mode is required to make changes to the connection's models. The dbt integration uses branches to enable switching dbt environments.

Limitations

Workbooks don't currently support branch changes, meaning that any changes made in a branch will be immediately applied to the workbook's current draft. These changes will become visible once the document is published.

Creating branches

note

Connection Admin or Querier permissions are required to create branches.

1. Click Settings > Develop.

2. Click the model file you want to edit.

3. In the IDE, click Model > New branch or Model > Branch > New branch:

   

4. Enter a name for the branch.

   Want to group branches in the branch menu?

   To group (or nest) branches in the branch menu, you can use forward slashes. For example, these branch names:

   - add-new-topic
   - field-updates/add-new-calc
   - field-updates/rename-fields
   - field-updates/update-field-def
   - remove-topic

   Would create this structure in the branch menu:

   - add-new-topic
   - field-updates
      - add-new-calc
      - rename-fields
      - update-field-def
   - remove-topic

5. Click Create.

6. A green header will display at the top of the page, indicating that you're in the branch:

   

At this point, you can make changes to the model.

Editing models in branches

note

Connection Admin or Querier permissions are required to edit models in branches.

In the model IDE:

1. If you've already created a branch, click Model > Branch and select your branch.

2. Make changes to the model, such as adding fields, making join changes, or modifying a topic.

3. Click Save to branch to add a change to the branch:

   

   Each time you save a change in the IDE an entry will be added to the Model history. Open this panel to view the changes currently on the branch, as well as the before and after (also called a diff) of each change.

   

   To view only the files you've changed (and saved) in the branch, click the Browse mode dropdown in the file picker, then Staged. The IDE will update to filter out any unchanged files:

   

Reviewing workbook changes

note

Connection Admin or Querier permissions are required to access branches in workbooks.

While you're working, you may want to periodically see how your changes will impact a workbook. You can do this by opening the branch in the workbook. Note: Changes made while on a branch in a workbook will be immediately applied to the document's current draft.

1. Navigate to the workbook.

2. Click Model > Branch.

3. Select the branch you're working in. The changes from the branch will be applied to the workbook.

   

Merging branches

note

Connection Admin permissions are required to merge branches.

After you've verified your changes work as expected, you'll need to merge the branch to apply them to the shared model.

1. In the branch header at the top of the page, click Merge:

   

2. You'll be prompted to confirm the merge. Note: Leaving the Delete branch after merge box checked is recommended.

   

3. Click Merge.