Skip to main content
Omni’s integration with dbt’s semantic layer reads metadata from your dbt semantic layer project and maps it into your Omni model. This includes dimensions, entities, measures, and metrics, so you can use your dbt semantic definitions directly in Omni without recreating them.

​
Requirements

To follow this guide, you’ll need:
  • A dbt semantic layer project configured in your dbt repository
  • To have the dbt integration enabled for an Omni database connection
  • Organization Admin permissions or Connection Admin permissions for the connection where dbt is enabled

​
Mapping dbt metadata into Omni

See the dbt metadata reference to learn about how dbt semantic layer data is mapped into Omni.

​
Setup

1

Enable the semantic layer

  1. Navigate to Settings > Connections.
  2. Click the connection where dbt is enabled.
  3. Click the dbt tab on the connection’s settings page.
  4. Check the Enable semantic layer box.
  5. Click Save.
2

Perform a schema refresh

With the semantic layer sync enabled, the next step is to trigger a schema refresh to pull the metadata into Omni.
  1. In the connection settings page, click the Settings tab.
  2. Click the Refresh now button to trigger the refresh.
If you have branch-based schema refreshes enabled, the steps for triggering a refresh will be different than those listed here. Refer to the Schema refreshes guide for more information.

​
Known differences and limitations

There are some behavioral differences between how dbt’s semantic layer and Omni handle certain concepts:

Not currently supported

The following are not currently supported:
  • Cumulative and conversion metrics
  • Null filling

Aggregation time dimensions

Omni does not support the concept of an agg_time_dimension, so you must carefully pick the dimensions and grains at which you view various metrics. Omni will append a comment to the field’s description to denote the default time field that should be used with the metric to help provide clarity.

Time spines

Time spines exist in dbt’s semantic layer, whereas Omni allows you to fill dates when desired to conduct more complete analyses over various time windows.

Offsets and relative calculations

These can still be done in Omni via YAML configuration or the UI, depending on the specific goal.

Ratio metric calculations

When calculating ratio metrics, Omni joins the tables because its representation of metrics is still tied to a table.This can differ from MetricFlow’s approach of generating two separate metrics in subqueries, joining them, and then calculating the ratio. Omni’s approach automatically leverages symmetric aggregation to avoid miscalculations caused by fan outs.

​
Common questions

Yes. The dbt Semantic Layer is powered by MetricFlow, dbt’s open-source metric query engine. If you’ve defined metrics and semantic models using MetricFlow, this is the integration that brings them into Omni.
The most effective approach is a hybrid model that balances centralized governance with BI agility.Use the dbt Semantic Layer for:
  • Cross-tool consistency: Define “Tier 0” canonical metrics (like Gross Revenue or Churn Rate) that must be identical across multiple platforms (e.g., Hex, Salesforce, or custom apps).
  • Centralized governance: Use dbt when you want the data engineering team to own the “source of truth” through a formal pull request (PR) process.
Use the Omni semantic layer for:
  • BI-specific metadata: Use Omni for logic that only impacts the analysis experience, such as color mapping, field grouping, drill paths, and friendly labels.
  • AI and natural language: Add AI context and synonyms in Omni to help users query data in plain English.
  • Speed and plasticity: Use Omni to prototype new metrics or create complex join logic and workbook-level calculations on the fly without waiting for dbt deployments.
Think of the dbt Semantic Layer as a small set of slow-changing, universal gold metrics. Think of the Omni layer as the plastic workspace where you iterate quickly and provide the rich context users need for self-service.
The dbt Semantic Layer integration is a one-way import. Omni ingests metrics and semantic models defined in dbt, but it does not support exporting or pushing metrics authored in Omni back into dbt semantic files.

​
Troubleshooting

See Debugging dbt sync issues for more information.

​
Next steps