> ## 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.

# Getting started with dbt

> Integrate dbt Core or dbt Cloud with Omni to sync metadata, author models, push exposures, and connect your semantic layer.

Omni's bi-directional dbt integration makes it easy to view your dbt metadata, create and edit models within Omni, and keep your dbt and BI layer operating in lockstep.

## What you can do with dbt in Omni

After you [connect your dbt Git repository](#setup), Omni compiles your dbt project into a manifest and reads it. From there, you can:

<CardGroup cols={2}>
  <Card title="Sync dbt model metadata" icon="arrows-rotate" href="/integrations/dbt/syncing-dbt">
    Sync metadata in your dbt project into matching views in your Omni model. See the [dbt metadata reference](/integrations/dbt/metadata-reference) for all available metadata.
  </Card>

  <Card title="Configure environments" icon="user-pen" href="/integrations/dbt/environments">
    Tell Omni how to run dbt commands against your project - which schema your models are built into, which database they live in, and what `target` your project expects.
  </Card>

  <Card title="Test dbt changes against real content" icon="arrow-right-arrow-left" href="/integrations/dbt/virtual-schemas">
    Use Virtual Schemas to enable environment switching without rewriting content, so you can see what a model change does before it reaches users.
  </Card>

  <Card title="Integrate dbt's semantic layer" icon="layer-group" href="/integrations/dbt/semantic-layer">
    Map dimensions, entities, measures, and metrics defined in dbt's semantic layer into your Omni model.
  </Card>

  <Card title="Author dbt models in Omni" icon="pen" href="/integrations/dbt/models">
    Promote an Omni query into a dbt model, or edit existing models in the Omni UI.
  </Card>

  <Card title="Push descriptions to dbt" icon="arrow-up-from-bracket" href="/integrations/dbt/push-descriptions">
    Sync descriptions written or edited in Omni back into your dbt project's schema.yml files.
  </Card>

  <Card title="Push exposures to dbt" icon="share-nodes" href="/integrations/dbt/exposures">
    Track Omni dependencies in dbt by generating exposure files from published dashboards and apps and pushing them to your dbt repository.
  </Card>

  <Card title="Collaborate with Git" icon="code-branch" href="/integrations/dbt/git-workflows">
    Learn how to manage the development lifecycle between Omni, dbt, and Git.
  </Card>
</CardGroup>

<h2 id="setup">
  Setting up dbt
</h2>

To use dbt in Omni:

1. [**Connect your dbt Git repository**](/integrations/dbt/setup). Omni reads your dbt project from the Git repository that holds it. Each Omni connection supports one dbt project.
2. [**Configure your production dbt environment**](/integrations/dbt/environments). A dbt environment tells Omni where your models are built. Omni creates a production environment automatically when you connect a dbt Git repository, but you must configure its settings to mirror your `profiles.yml` (dbt Core) or your dbt Cloud environment.
3. [**Sync dbt with Omni**](/integrations/dbt/syncing-dbt). Trigger a dbt sync to compile the manifest, locate your dbt models in the database, and pull descriptions, tests, and tags into the matching Omni views.
4. [**Optional: Set up Virtual Schemas**](/integrations/dbt/virtual-schemas). Virtual Schemas point your content at a dbt environment instead of a physical schema, so users can swap between production and a personal dev build without breaking workbooks and topics.

## Guides

<Columns cols={2}>
  <Card title="Preview dbt changes in Omni" icon="magnifying-glass" href="/guides/modeling/preview-dbt-changes">
    Preview dbt model changes in an Omni development environment.
  </Card>

  <Card title="Embed dbt data health tiles in Omni dashboards and apps" icon="heart-pulse" href="/guides/dashboards/dbt-data-health-tiles">
    Embed dbt data health tiles (formerly status tiles) in Omni dashboards and apps.
  </Card>

  <Card title="All dbt guides" icon="book" href="/guides/?tags=dbt">
    See all dbt guides
  </Card>
</Columns>

## Common questions

<AccordionGroup>
  <Accordion title="What dbt platforms and versions does Omni support?">
    Omni supports dbt Core and dbt Cloud. Since Omni reads your dbt project directly from its Git repository for either platform, version detection works the same way regardless of which one you use.

    The connection's **dbt Version** setting defaults to **Auto**. In Auto mode, Omni detects the version from the `require-dbt-version` pin in your `dbt_project.yml`. Auto prefers 1.x and only uses dbt 2.0 if the pin rules out every 1.x version, such as `>=2.0.0,<3.0.0`. If the pin is missing or no supported version satisfies it, Omni falls back to the latest 1.x version. You can also choose a specific version from the **dbt Version** setting in the connection's dbt settings.

    The list of versions Omni supports changes as new dbt releases come out, so check the **dbt Version** dropdown in your connection's settings for what's currently available. dbt 2.0 rejects some project configuration that 1.x accepted, so Auto doesn't move existing connections to it. Some versions aren't offered for every warehouse because they have no dbt adapter for it; for example, dbt 2.0 isn't available for Athena or StarRocks connections. For dbt's own policy on which versions it supports, see the [dbt version support documentation](https://docs.getdbt.com/docs/dbt-versions).
  </Accordion>

  <Accordion title="What features require using the formal dbt integration?">
    If you connect to tables as raw schemas rather than using the formal dbt integration, you won't be able to:

    * Sync metadata from dbt into your Omni model
    * View upstream dbt dependencies within Omni
    * Toggle between dbt environments
    * Edit dbt models in Omni
  </Accordion>

  <Accordion title="Can I connect multiple dbt projects to a single Omni connection?">
    Only one dbt project at a time can be associated with an Omni connection. If you have multiple dbt projects, the workaround depends on how you want to query the data in Omni.

    To query the datasets together, you'll need to do one of the following:

    1. Connect to one project and pull the other projects' tables as raw schemas
    2. Consolidate dbt projects

    Otherwise, you'll need to create a connection for each dataset. Depending on your goals and whether the datasets are identical, you can use [dynamic environments](/connect-data/dynamic-environments) to switch between the datasets in Omni. Dynamic environments only change the connection being used, not the structure of the underlying model - this means if one model uses an object that doesn't exist in another, there will be errors.
  </Accordion>

  <Accordion title="Can I use a custom dbt plugin to sync multi-project models?">
    No. Omni does not currently support custom dbt plugins.
  </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. A connection can have only one dbt manifest, so you can query Project A with full metadata and Project B as raw tables in the same dashboard.

    Combining tables from two separate Omni connections into a single query or dashboard tile isn't supported.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.