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
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.
Mapping dbt metadata into Omni
Dimensions
Dimensions defined in your dbt semantic layer are pulled into Omni. Metadata for descriptions, expressions, and labels are mapped onto their respective dimensions in Omni.Entities
Entities are created as their own dimensions in Omni and are used to create joins between tables mapped to their respective semantic models. Entities as a concept are mapped to relationships in Omni.Measures
If your dbt semantic layer project uses measures, they are mapped to measures in Omni.Metrics
dbt metrics are mapped into Omni as measures, with their location dependent on their type:| Metric type | How it maps in Omni |
|---|---|
| Simple | Mapped to the view in Omni that the table of the underlying expression is based on |
| Ratio | Mapped to the view in Omni that the denominator is based on |
| Derived | Mapped to the view in Omni that the first metric is based on |
| Cumulative | Not currently supported |
| Conversion | Not currently supported |
Semantic view labels
The names of semantic view files in dbt are mapped to Omni as labels on the correspondingdbt_models table.
Setup
Enable the semantic layer
- Navigate to Settings > Connections.
- Click the connection where dbt is enabled.
- Click the dbt tab on the connection’s settings page.
- Check the Enable semantic layer box.
- Click Save.
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.
- In the connection settings page, click the Settings tab.
- Click the Refresh now button to trigger the refresh.
If you have branch-based schema refrehses enabled, the steps for triggering a refresh will be different than those listed here. Refer to the Schema refreshes guide for more information.
Troubleshooting
If Omni encounters issues while syncing semantic layer metadata, errors will surface in the model IDE:
- Click Settings > Develop.
- Click the model you want to work with.
- In the left navigation, click the dbt icon.
- In the Settings section of the field browser, click Semantic Layer.
Next steps
- Work with dbt models — Author and edit dbt models from Omni
- Schema refreshes — Sync dbt changes into your Omni model