Skip to main content
Virtual schemas are a powerful abstraction layer in Omni that decouple your modeling logic from specific physical database locations. Think of virtual schemas as a way to swap out the physical tables in your SQL queries for a variable that you can then use to switch in and out different dbt environments. By using the omni_dbt prefix, you can build workbooks and topics once and dynamically swap the underlying data source between dbt environments - like production and a personal dev schema - without breaking your content.
Omni strongly recommends enabling virtual schemas before you begin building Omni. You can enable them later, but doing so will require migrating existing content.

​
Requirements

To set up or migrate to virtual schemas, you’ll need:

​
Setting up virtual schemas

1

Enable the integration

  1. In Omni, click Connections.
  2. Locate the connection you want to work with.
  3. Click the dbt tab.
  4. Toggle on Enable Virtual Schemas.
Omni will automatically generate a new version of your schemas prepended with omni_dbt_.You will need to build your model from views in the omni_dbt_ version of your schema for dbt virtual schemas to work.It’s recommended you only include these schemas going forward, by adding the following to your model file:
2

Configure dbt environments

To use the environment toggle, Omni needs to mirror your dbt runner configuration (e.g., dbt Cloud).Every developer who wants to use environment switching must have their own environment. See Configuring dbt environments for step-by-step instructions.
3

Confirm Omni model and dbt source mappings

In the model IDE, confirm that all models Omni currently accesses are correctly mapped to their dbt sources.If this does not pass automatically, refresh your schema and see the debugging steps in Debugging dbt sync issues.

​
Migrating existing content

If you already have a model built on physical schemas, you’ll need to migrate your logic to the virtual layer to unlock environment switching.
Before you start, check for dbt sync issues in the dbt IDE. Make sure that all the models Omni currently accesses are mapped to the correct dbt sources.
1

Enable the integration

  1. In Omni, click Connections.
  2. Locate the connection you want to work with.
  3. Click the dbt tab.
  4. Toggle on Enable Virtual Schemas.
2

Migrate your semantic logic

Next, you’ll use Omni’s migration tool to copy the existing semantic logic from your physical schemas to the new virtual ones.
Before beginning the migration, note that:
  • Logic migrations can’t be performed in branches, meaning production users could be impacted. Run the migration during a low-traffic period to minimize disruption.
  • Existing dashboards and topics won’t be updated. You’ll migrate content and topics in the next step.
If you skip this step, any hardcoded schema references in existing content will remain pointed at physical schemas and the environment toggle will have no effect on them.
To start the migration, navigate to the connection’s dbt tab and click the Run migration button.The migration scans all existing modeling layers and for every view file and relationship that existed under your physical dbt-managed schemas, it creates a one-to-one copy under the new omni_dbt_ prefixed virtual schema names. Specifically:
  • View files — Every view is recreated with the omni_dbt_ prefix.
  • Relationships/joins — Any joins you previously built are duplicated onto the corresponding virtual schema views.
  • Shared model logic — Things like custom field definitions, measures (e.g. sum of revenue), labels, etc. are carried over to the virtual schema version.
3

Verify the migration results

Navigate to the model IDE and look for a Virtual Schemas section. Database views accessible by Omni but not mapped to a specific dbt model will fall under the generic omni_dbt virtual schema.
4

Migrate your Omni content

  1. Open an Omni branch. This ensures that users won’t be disrupted while you perform the content migration.
  2. In the model IDE, update your topics’ base_view references to use the omni_dbt_ views.
  3. Use the Content Validator to find and replace physical schema references with virtual ones across all dashboards and tiles.
  4. Within your branch, point Omni to a dev schema to verify that changes in your dbt development branch are reflecting correctly. Then:
    1. Open a workbook that uses a virtual schema.
    2. Open the Query Inspector by clicking the icon in the left navigation.
    3. Check that the underlying table name switches to the dev schema you selected in the dbt development settings page.
5

Clean up and go live

  1. Once validated, hide the physical schemas to keep your model clean. Add the following to your model file:
  2. Merge your Omni branch.

​
Testing new dbt models in Omni branches

  1. Run dbt build in your local or cloud dev environment.
  2. Push your dbt code to a branch (e.g., git push origin new-feature).
  3. In Omni, create an Omni branch.
  4. In the Omni branch header, click the dbt settings button to navigate to your connection’s dbt development settings page where you can select your dbt dev environment.
  5. Return to your Omni branch and click Model > Refresh schema.
  6. In the dbt IDE, point to the dbt branch you want to align your Omni branch to.
When testing in a branch, use the Query Inspector to confirm that switching to your dev environment successfully re-points the query from PROD.CORE to DEV_USER.CORE.

​
Using virtual schemas with partial dbt builds

If you have a new dbt developer environment or are using deferrals already, you might be missing tables from your developer schema if you’re seeing partial builds.
By default, Omni needs all tables in a model to exist in your physical schema to map them to virtual schemas. If you only build a few models in dev, the rest of the virtual schemas will disappear.

​
Enable deferral (recommended)

The recommended approach is to enable the Enable deferral checkbox when configuring your dev environment in Omni. When enabled, Omni automatically falls back to production builds for models not built in your dev environment, so you can run partial builds without needing to create clones or build the full project. For example, if you only build a subset of models in your dev schema, Omni will use the production version for everything else without any additional setup. See Configuring dbt environments for more information about setting up dev environments.
For partial builds, enable deferral when you routinely build only the models you’re actively changing, rather than running full dbt build commands.

​
Using dbt clone for zero-copy clones

While Omni’s native deferral feature handles most use cases, dbt clone remains a complementary option for creating zero-copy clones of production objects directly in your warehouse. This can be useful when you want physical copies of production tables in your dev schema:
Deferrals require at least one successful job run in the designated production environment.
  1. In dbt Cloud, enable the Defer to staging/production option in your development environment settings. This designates your production job as the reference point.
  2. Once enabled, run dbt clone from the dbt Cloud IDE. On warehouses that support it (like Snowflake), this creates zero-copy clones of all production objects in your development schema, creating the “stubs” or references Omni needs to see the entire project.
  3. Once cloned, you can run dbt build -s <your_model> for just the specific models you are changing. Omni will now see the entire schema - the cloned production tables and your specific dev changes - allowing you to validate your work without a full project run.
See the Troubleshooting section if tables are missing after going through the above steps.

​
Common questions

While dbt metadata like descriptions and primary keys automatically flows into Omni’s standard schemas, virtual schemas unlock advanced environment management.
  • Environment swapping: Toggle your Omni branch to point to a development schema (e.g., dbt_blobby) to test new logic before merging to production.
  • Stable references: Dashboards built on virtual schemas use a stable reference (e.g., omni_dbt__orders). When you switch environments, Omni automatically adjusts to fetch data from your dev schema, but the dashboard itself will remain unchanged.
  • Safety: You can validate dbt changes in an Omni branch before they hit production, ensuring dashboards don’t break after a dbt deployment.
Yes. Virtual schemas prevent your content from being tied to a single physical database location, so you can switch between environments without rebuilding anything. Build once on the virtual layer and swap dynamically as needed.
No. You can still view the source SQL and dbt lineage directly in the Omni IDE to trace the exact database and schema a model originated from.
Only tables built and managed by dbt will have a corresponding virtual schema. Data that comes from other sources — CSV uploads, direct pipeline ingestion, and so on — won’t have a virtual schema. You’ll always use the physical schema for that data.
The raw SQL in the SQL editor may show the virtual alias.To see the physical path being queried, check the Query Inspector. It displays the final, compiled SQL sent to your warehouse, including the specific dev or prod database and schema names.
You can use dynamic schemas and dbt environments to point Omni at your development or feature-branch schemas. This allows you to immediately validate changes in Omni without waiting for a production deployment.
No. Cloning creates zero-copy clones of all production objects in your development schema. If you then run dbt build or dbt run on a specific model, dbt replaces that clone with the table or view built from your code. Omni picks up the new version automatically.
  • Keep it if: You plan to preview how dbt code changes will impact your dashboards before pushing them to production.
  • Turn it off if: You only have one dbt environment and never plan to use Omni for development preview work. Note that even if you turn off virtual schemas, dbt metadata like descriptions and primary keys will still flow into your standard schemas.
Virtual schemas use consistent aliases to keep references stable. To verify the query is hitting your dev schema, check the Query Inspector to see the final, compiled SQL sent to your warehouse.
Omni derives each virtual schema name from the custom schema configured on the dbt model. The custom schema is different from the target (or “default”) schema — it’s the +schema: config you set in dbt_project.yml or in a model’s config block.Where Omni places models depends on if the model has a custom schema:
  • No custom schema - Placed in omni_dbt
  • Custom schema - Placed in omni_dbt_<custom_schema>
For example, given the following dbt_project.yml:
Omni generates these virtual schemas:
  • Models under marketing/ → omni_dbt_marketing
  • Models under finance/ → omni_dbt_finance
  • Models under staging/ (no custom schema) → omni_dbt

​
Troubleshooting

This is almost always a configuration issue with the environments that aren’t working. Each developer needs their own separate environment entry in Omni; a working environment for one person doesn’t carry over to others.For each person, check the following:
  • Missing environment entry: Every developer needs their own entry, added under Environments on the dbt IDE’s Sync page. If an entry doesn’t exist for a given developer, Omni has nothing to resolve to when they switch environments.
  • Incorrect default schema: Each developer typically builds into their own personal schema in dbt (e.g., dbt_blobby). If the Omni connection’s Default schema doesn’t match where that developer’s dbt builds, Omni will look in the wrong place.
  • Incorrect target name: The Target name dbt setting in Omni must exactly match the target that developer uses when running dbt (e.g., dev, default, or a custom value). See the Configure dbt environments section for guidance on where to find this in dbt Cloud.
  • dbt hasn’t been run for that developer yet: If a developer has never run dbt build or dbt run in their personal schema, there will be nothing for Omni to find. Once the environment is configured, open the dbt IDE’s Sync page, select that environment, and click Sync now.
  • Missing warehouse permissions: The Omni service account must have access to each developer’s personal database and schema. If it doesn’t, you’ll see a warning like "Database 'DEV_BLOBBY' does not exist or not authorized" in the health check. To verify, open the SQL editor in an Omni workbook and run SHOW DATABASES. If the developer’s database (e.g., DEV_BLOBBY) doesn’t appear in the results, the service account hasn’t been granted access to it. Confirm the service account has been granted the correct permissions on that developer’s database and schema, then re-run the health check.
  • Missing environment variables: If your dbt project uses custom environment variables to control schema names, those need to be added per environment in Omni.
To diagnose quickly, open the dbt health check for the failing environment. It will tell you whether the issue is a configuration mismatch or a permissions problem.
Virtual schemas may be empty for a few reasons:
  • Missing materialization: Omni can only see models that have been physically built in your warehouse. Ensure you executed dbt run or dbt build in that specific environment.
  • Schema refresh needed: If the data exists in your warehouse but isn’t showing in Omni, trigger a schema refresh. See Schema refreshes for instructions.
  • Permissions: The database user Omni uses must have USAGE and SELECT permissions on your personal development schema.
  • Inclusion filters: If your model file has included_views or included_schemas defined, you must explicitly add "omni_dbt*" to that list.
dbt environment switching only works for views built on the omni_dbt_ (virtualized) layer. If your topic or SQL shows a hardcoded schema name that doesn’t start with the virtual prefix, the environment switch will be ignored.
If dbt clone runs but certain tables still error out or don’t appear in Omni:
  • Check the Omni user’s permissions. Ensure the database user Omni uses (or your individual OAuth user) has SELECT grants on the production schemas being cloned.
  • Check production health: Verify that the models exist and have had a successful run in your production environment. If a model is missing from the production manifest, it cannot be deferred or cloned.
  • Check your environment settings. If you have multiple environments (e.g., Staging and Prod) and are using dbt cloud, check that your dbt settings are deferring to the environment that actually contains your data before running the dbt clone command.
Omni expects every model referenced in an environment to physically exist in the target schema. If you’ve only built modified models, Omni can’t resolve the missing tables.Enable deferral for your dev environment to automatically fall back to production builds for unbuilt models. Alternatively, run dbt clone before switching environments in Omni to create zero-copy clones of all production tables. If errors persist, confirm your database user has permission to read the production schema — see dbt connection setup for more information.

​
Next steps