Skip to main content
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 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 for more information, including the metadata Omni excludes.

​
Requirements

To sync dbt with Omni, you’ll need:
  • A connection with dbt configured
  • 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 left navigation.
  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 left navigation.
  4. Click Sync at the top of the file list to open the Sync page:

    Access the dbt sync settings through the dbt IDE

  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 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. Schema refreshes happen at the connection level, so the steps are the same whether or not you use dbt. See 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 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 (e.g., 24 hours) and use the Reset cache API 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 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 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 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, which can help the Omni Agent generate more accurate queries.