Skip to main content
Omni’s dbt integration connects your dbt repository to an Omni database connection, syncing model metadata like descriptions, tags, and schema mappings into your Omni semantic model. This guide walks you through the setup process, from linking your Git repository to syncing dbt metadata into Omni.

​
Common questions

We strongly recommend using two separate repositories: one for your dbt project and one for your Omni semantic model.This gives you:
  • Clear ownership — Separates data engineering from business logic.
  • Faster iteration — Prevents semantic refreshes from being tied to dbt compilation times.
  • Cleaner Git history — Keeps automatic commits from the Omni IDE out of your dbt pull requests.
  • Coordinated deployments — Ensures Omni model changes only apply after related dbt runs complete, so downstream content doesn’t break.
If you decide to keep Omni and dbt in the same repository, use seperate branches for changes.
Yes. You can connect the same dbt repository to multiple Omni database connections. This is common when using different credentials for different environments, such as using separate Snowflake accounts for different departments.
You must configure dbt settings and environment variables for each individual connection to ensure models map to the correct database and schema.
No. Each Omni connection supports exactly one dbt project integration. If you have multiple dbt projects, you must either:
  • Create separate connections for each project, or
  • Connect to one project formally and pull the other project’s tables as “raw” schemas
This is possible only if the tables are included in the same Omni connection.Since a connection can only have one dbt manifest, you can query tables from Project A (with full metadata) and Project B (as raw tables) in one dashboard.Combining tables from two separate Omni connections into a single query or dashboard tile isn’t supported.

​
Requirements

To follow the steps in this guide, you’ll need:

​
Setup

As part of your dbt setup, if you are planning to use Virtual Schemas to unlock dbt environment switching, we strongly recommend you enable before building in your Omni instance
1

Retrieve the dbt repository's SSH URL

  1. In your browser, navigate to the GitHub dbt repository you want to connect to Omni.
  2. Click the Code button.
  3. In the modal that displays, locate the SSH option.
Keep this page open - you’ll need it in the next step.
  1. In your browser, navigate to the GitLab dbt repository you want to connect to Omni.
  2. Click the Code button.
  3. In the modal that displays, locate the SSH option.
Keep this page open - you’ll need it in the next step.
  1. In your browser, navigate to the Azure DevOps dbt repository you want to connect to Omni.
  2. Click the Clone button near the top right corner of the page.
  3. Click the SSH option to display the repository’s SSH URL.
Keep this page open - you’ll need it in the next step.
2

Create the dbt connection in Omni

  1. In Omni, navigate to Settings > Connections.
  2. Click the connection you want to use.
  3. Click the dbt tab.
  4. Fill in the following fields:
    • Git SSH URL - Enter the SSH URL you retrieved in step 1 of this guide
    • Git Branch - Enter the name of the default branch for the repository. This is usually main or master.
    • Default Schema - Enter the default schema your dbt project writes models to (i.e., without any custom schema overrides). dbt uses this value as a prefix when naming other schemas. For example, if your database has dbt, dbt_one, and dbt_two schemas, the default schema is dbt.
      Need help finding your dbt project’s default schema?
      • For dbt Cloud - Navigate to Deployment Environments > Production Prod > Settings > Deployment Credentials > Schema
      • For dbt Core - Check the schema key in your project’s profiles.yaml
    • Folder - If your repository contains multiple dbt projects, enter the path to the folder that contains the dbt project you want to connect.
    • Enable dbt Semantic Layer - Check this box to enable the dbt Semantic Layer integration. When enabled, Omni will use the dbt Semantic Layer to pull in metrics and dimensions defined in your dbt project.
  5. Click Save.
After the dbt connection is created, a Public Key will display. Leave this page open - you’ll need it in the next step.
3

Add the deploy key to your repository

In this step, you’ll add the Public Key created in step 2 of this guide to your dbt repository as a deploy key.
  1. In the GitHub repository, click the Settings tab.
  2. Click Deploy keys, located in the Security section of the left navigation.
  3. Click Add deploy key.
  4. Fill in the fields as follows:
  • Title - Enter a descriptive title to help you identify what the key is used for. For example, Omni Snowflake dbt
  • Key - Copy the Public key from the Omni dbt settings tab and paste it into this field.
  • Allow write access - Check this box if you want to push changes made in Omni to the repository
  1. Click Add key.
  1. Create a project deploy key for the GitLab repository by following GitLab’s documentation.
  2. Fill in the deploy key fields as follows:
  • Title - Enter a descriptive title to help you identify what the key is used for. For example, Omni Snowflake dbt
  • Key - Copy the Public key from the Omni dbt settings tab and paste it into this field.
  • Grant write permissions to this key - Check this box if you want to push changes made in Omni to the repository
  1. Click Add key.
  1. Browse to the Azure DevOps web portal (ex: https://dev.azure.com/<your-org-name>/).
  2. Click the User settings icon next to your avatar in the top right corner of the page.
  3. Click SSH public keys.
  4. On the page that displays, click + New Key.
  5. In the Add New SSH Key panel that displays, fill in the following:
  • Name - Enter a descriptive name, such as Omni Snowflake dbt
  • Public Key Data - Copy and paste the Public key from the Omni dbt settings tab
  1. Click Add.
4

Sync dbt metadata

Back on the connection page in Omni, click the Settings tab and locate the Schema section. Click the Refresh now button.This will sync metadata from your dbt repository into the connection’s Omni model. The majority of the information Omni pulls is sourced from the schema.yml files that live alongside your project’s models.When a schema refresh is triggered, Omni compiles the dbt code and uses the resulting dbt manifest, which includes information such as finalized schema names and model dependencies.If metadata changes in dbt, you’ll need to refresh the schema again in Omni. This can be done via the model menu in the IDE, the connection page (either manual or on a cron schedule), or by using the Omni API.

​
Troubleshooting

This often happens if views are flagged with an ignored: true parameter. Omni’s sync may interpret complex views — especially those with dynamic logic like Jinja loops — as “not in use,” and automatically hide them to keep the model clean.To fix this:
1
Navigate to the model IDE.
2
Toggle the view mode to Model. The dropdown may default to Combined, so be sure to update it if needed.
3
Navigate to the file for the view and check for an ignored: true parameter.
4
Remove the parameter and promote the changes to the shared model.
Omni only looks for tables in schemas explicitly allowed at the connection level. To fix this, you’ll need to:
1

Update the connection to include the dev schemas

Open the connection’s settings page and enter your dev schema pattern in the Include Schemas field. For example, DBT_USER_*.
2

Run a schema refresh

This will pull the dev schemas you just added into Omni. See Schema refreshes for more information.
This typically occurs when a dbt-imported measure shares the same name as an existing dimension in the Omni Semantic Layer.To fix the issue:
1
Rename the measure, changing the label or name to be unique (e.g., total_revenue).
2
Check the sql parameter to ensure it points to the raw database column, not the measure name.
3
Hide the dimension by adding the hidden: true parameter. This will hide the raw column in Omni.
If your project requires a newer version (e.g., dbt 1.10+), update it in Omni:
1
Navigate to Settings > Connections and click the connection.
2
Click the dbt tab.
3
Select the correct version from the dbt Version dropdown.
4
Click Save.
5
Trigger a schema refresh.

​
Next steps