> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/integrations/dbt/setup",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Connecting dbt to Omni

> Set up Omni's dbt integration by connecting a dbt repository to an Omni database connection.

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

<AccordionGroup>
  <Accordion title="Can I use the same Git repo for Omni models and dbt code?">
    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 separate branches for changes.
  </Accordion>

  <Accordion title="Can I use the same dbt repository for multiple database connections?">
    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.

    <Note>
      You must configure dbt settings and environment variables for each individual connection to ensure models map to the correct database and schema.
    </Note>
  </Accordion>

  <Accordion title="Can I connect multiple dbt projects to a single Omni connection?">
    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
  </Accordion>

  <Accordion title="Can I query tables from different dbt projects in the same dashboard?">
    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.
  </Accordion>
</AccordionGroup>

## Requirements

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

* **An existing [database connection](/connect-data/setup) in Omni**
* [**Omni Connection Admin permissions**](/administration/users/permissions) for the connection you want to connect to dbt

## Setup

<Tip>
  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
</Tip>

<Steps titleSize="h3">
  <Step title="Retrieve the dbt repository's SSH URL" id="retrieve-ssh-url">
    <AccordionGroup>
      <Accordion title="GitHub" icon="github">
        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.
      </Accordion>

      <Accordion title="GitLab" icon="gitlab">
        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.
      </Accordion>

      <Accordion title="Azure DevOps" icon="microsoft">
        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.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Create the dbt connection in Omni" id="create-connection">
    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`.

             <Tip>
               **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`](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml)
             </Tip>
       * **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](/integrations/dbt/semantic-layer). 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.
  </Step>

  <Step title="Add the deploy key to your repository" id="add-deploy-key">
    In this step, you'll add the **Public Key** created in step 2 of this guide to your dbt repository as a deploy key.

    <AccordionGroup>
      <Accordion title="GitHub" icon="github">
        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

        5. Click **Add key**.
      </Accordion>

      <Accordion title="GitLab" icon="gitlab">
        1. Create a **project deploy key** for the GitLab repository by following [GitLab's documentation](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key).
        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

        3. Click **Add key**.
      </Accordion>

      <Accordion title="Azure DevOps" icon="microsoft">
        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

        6. Click **Add**.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Sync dbt metadata" id="sync-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](/modeling/develop/schema-refreshes) (either manual or on a cron schedule), or by using the [Omni API](/api/models/refresh-schema).
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Missing views">
    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:

    <Steps>
      <Step noAnchor>
        Navigate to the model IDE.
      </Step>

      <Step noAnchor>
        Toggle the view mode to **Model**. The dropdown may default to **Combined**, so be sure to update it if needed.
      </Step>

      <Step noAnchor>
        Navigate to the file for the view and check for an `ignored: true` parameter.
      </Step>

      <Step noAnchor>
        Remove the parameter and promote the changes to the shared model.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="'No models mapped to views' message in a dev environment">
    Omni only looks for tables in schemas explicitly allowed at the connection level. To fix this, you'll need to:

    <Steps>
      <Step title="Update the connection to include the dev schemas" noAnchor>
        Open the connection's settings page and enter your dev schema pattern in the **Include Schemas** field. For example, `DBT_USER_*`.
      </Step>

      <Step title="Run a schema refresh" noAnchor>
        This will pull the dev schemas you just added into Omni. See [Schema refreshes][schema-refresh] for more information.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="'Circular reference' or duplication errors">
    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:

    <Steps>
      <Step noAnchor>
        **Rename the measure**, changing the label or name to be unique (e.g., `total_revenue`).
      </Step>

      <Step noAnchor>
        **Check the `sql` parameter** to ensure it points to the raw database column, not the measure name.
      </Step>

      <Step noAnchor>
        **Hide the dimension** by adding the [`hidden: true`](/modeling/dimensions/parameters/hidden) parameter. This will hide the raw column in Omni.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="dbt version and compatibility errors">
    If your project requires a newer version (e.g., `dbt 1.10+`), update it in Omni:

    <Steps>
      <Step noAnchor>
        Navigate to **Settings > Connections** and click the connection.
      </Step>

      <Step noAnchor>
        Click the **dbt** tab.
      </Step>

      <Step noAnchor>
        Select the correct version from the **dbt Version** dropdown.
      </Step>

      <Step noAnchor>
        Click **Save**.
      </Step>

      <Step noAnchor>
        Trigger a [schema refresh][schema-refresh].
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Next steps

* [Working with dbt models](/integrations/dbt/models) — Author and edit dbt models from Omni
* [dbt Semantic Layer](/integrations/dbt/semantic-layer) — Pull dbt metrics and dimensions into Omni
* [Schema refreshes](/modeling/develop/schema-refreshes) — Keep your Omni model in sync with dbt changes

[schema-refresh]: /modeling/develop/schema-refreshes#hard-refreshes