> ## 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.
# Triggering dbt syncs in Omni
> How Omni schema refreshes and dbt syncing work together to keep your data warehouse, transformation logic, and BI layer in sync.
export const DbtIdeIcon = ({label}) => {
return ;
};
Omni pulls context from your dbt project into your model, so the descriptions, SQL, and dependencies you maintain in dbt are available to everyone querying in Omni. This allows you to keep definitions in one place, ensuring analytics engineers, analysts, and business users share a single source of truth for what a field or table means.
Two operations keep Omni current with your database and dbt; while the terms are often used interchangeably, they do different jobs:
* **dbt syncs** regenerate the dbt manifest from the selected [dbt environment](/integrations/dbt/environments) and Git branch, locate your dbt models in the database, and pull the model metadata into the corresponding Omni views. They do not scan the database, and therefore do not include structural changes.
* **Schema refreshes** inspect your connected database, identify structural changes, and update the associated Omni model to match. For example, if you add a new column in the warehouse, a schema refresh will pull it into Omni. When an Omni connection has dbt enabled, a schema refresh also performs a dbt sync.
What dbt syncs pull in
Omni includes some metadata in every dbt sync, while the rest depends on the connection's dbt settings. See the [dbt metadata reference](/integrations/dbt/metadata-reference) for more information, including the metadata Omni excludes.
## Requirements
To sync dbt with Omni, you'll need:
* A connection with [dbt configured](/integrations/dbt/setup)
* **Modeler** or **Connection Admin** permissions on the Omni model
Triggering dbt syncs
When nothing has changed in the warehouse — you edited a description, added a tag, switched to a different dbt branch, or changed an environment's settings — you don't need a full schema refresh. You can sync dbt on its own from the dbt IDE.
1. In Omni, click **Develop** in the [sidebar](/administration/settings/sidebar).
2. In the list of models, click the model you want to work with to open the model IDE.
3. In the model IDE, click the icon in the sidebar.
4. Click **Sync** at the top of the file list to open the **Sync** page:
5. Check that **dbt environment** and **dbt git branch** point at the build you want Omni to read.
Both selectors require an active Omni branch. The production environment always uses the repository's default branch, so its branch selector stays disabled.
Unless [Branch-based schema refresh](/modeling/develop/schema-refreshes#requiring-branches-for-schema-refreshes) is enabled, syncing the **production** environment from a branch applies dbt across all models, not only the current branch.
6. Click **Sync now**. If you changed the environment or branch, the button reads **Save and sync** instead and does both.
Omni tells you when a sync is due. If the environment has never been synced or its settings have changed since the last sync, you'll see a notice on the **Sync** page.
Triggering schema refreshes
Run a schema refresh whenever a dbt run changes the structure of your warehouse, such as adding a model or adding, renaming, or removing columns. On a dbt-enabled connection, a schema refresh also runs a [dbt sync](#dbt-sync).
Schema refreshes happen at the connection level, so the steps are the same whether or not you use dbt. See [Schema refreshes](/modeling/develop/schema-refreshes) to learn how to trigger a refresh manually or on a schedule.
To automatically update Omni, use Omni's APIs to trigger a refresh as the last step of your orchestration workflow:
* Call the [Refresh schema API](/api/models/refresh-schema) immediately after a successful `dbt run`. By default, a schema refresh triggers a direct commit to your integrated Git branch to keep your model files in sync with the database.
* Define [cache policies](/modeling/models/cache-policies) (e.g., 24 hours) and use the [Reset cache API](/api/models/reset-cache) to reset the cache specifically when your warehouse jobs complete.
## Troubleshooting
If you notice a discrepancy between your warehouse and Omni, check these areas:
* **dbt sync issues** - In the dbt IDE, click **Sync** to see what the last sync couldn't translate, including dbt models that Omni couldn't match to a view. See [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) for how to work through them.
* **Model version history** - Click the icon in the model IDE to see a chronological list of what changed and who triggered the refresh. See [Viewing and restoring model versions in the model IDE](/modeling/develop/history) for more information.
## Common questions
No. The dbt IDE file tree shows your whole dbt project, including macros, tests, and files that aren't dbt resources at all. Browsing a file there does not mean a sync reads it.
Macros are the exception: Omni runs dbt to build the manifest, so `generate_schema_name` and `generate_database_name` decide where Omni looks for each model's table.
Yes. Omni runs the dbt compiler directly. It detects and handles custom `generate_schema_name()` macros, applying them based on your dbt environment parameters in Omni.
* **Production** - Maps to standard schemas (e.g., `marts`, `reports`).
* **Development** - Maps to prefixed schemas (e.g., `dbt_blobby_marts`).
When column descriptions differ between your dbt instance and your data warehouse's catalog, Omni prioritizes dbt's column descriptions. If descriptions are edited in Omni, Omni prioritizes those descriptions.
Upon refresh, Omni pulls in the new name automatically. The updated field will be available in your topics, but existing workbook references to the old name will break.
Use the [Content Validator](/modeling/develop/content-validator) to find and bulk-replace broken references across your workbooks. You can open a branch to make these fixes safely, then merge once everything is working as expected — rather than making changes live.
In many warehouses, constraints are applied to tables rather than views. If your dbt project outputs views, define constraints at the model level in dbt so Omni can still inherit that logic, even if the warehouse doesn't enforce them on the view.
No. While a combination of `unique` and `not_null` tests is logically equivalent to a primary key, Omni does not infer primary key status from these tests. Instead, Omni identifies a primary key through:
1. dbt constraints, which are included in dbt syncs when **Auto-generate primary keys and relationships from dbt constraints** is enabled in the connection's dbt tab.
2. Primary keys defined on the object in your database
3. Manually adding the primary key in Omni
Omni pulls dbt metadata into your model in ways that directly improve AI accuracy. For example, integrated descriptions are used for [AI context](/modeling/develop/ai-optimization), which can help the Omni Agent generate more accurate queries.
5. Check that **dbt environment** and **dbt git branch** point at the build you want Omni to read.
Both selectors require an active Omni branch. The production environment always uses the repository's default branch, so its branch selector stays disabled.