How dbt Semantic Layer works with Steep

When using the dbt Semantic Layer integration, you are defining your semantic layer in your dbt project and Steep uses the dbt Cloud APIs to make your metrics available for all end users in Steep. For these metrics, Steep will not use the built-in semantic layer, and will instead use dbt Cloud for definitions, query generation and execution. Otherwise everything works just like with native metrics.


You can combine metrics from dbt Semantic Layer with metrics defined natively in Steep. This can help you to iterate on new metrics definitions in a flexible way, while managing core metrics centrally in code.

Please note

Access to dbt Semantic Layer API requires a dbt Cloud account on the Team or Enterprise plan. See dbt plans.

Setting up dbt Semantic Layer

In order to get started you need to set up your dbt Semantic Layer, by creating Semantic Models and defining Metrics.

1. Create semantic models

Create semantic models that consist of entities, dimensions and measures.

  - name: orders
    description: Order fact table. This table is at the order grain with one row per order.
      agg_time_dimension: ordered_at

    model: ref('orders')

      - name: order_id
        type: primary

      - name: order_total
        description: The total revenue for each order.
        agg: sum

      - name: ordered_at
        type: time

          time_granularity: day

      - name: country
        type: categorical
        expr: country

2. Define metrics

Example metric:

  - name: order_total
    description: Sum of total order amount. Includes tax + revenue.
    type: simple
    label: Order Total
      measure: order_total
Learn more

Learn how to define metrics in the Build your metrics guide (dbt docs)

Connecting the dbt Semantic Layer to Steep

1. Set up your dbt Semantic Layer

In dbt Cloud:

  • Navigate to Account Settings and select the specific project you want to enable the Semantic Layer for.
  • In the Project Details page, navigate to the Semantic Layer section, and select Configure Semantic Layer.
Read the docs

Get all the steps in the Setup Semantic layer guide (dbt docs)

2. Get your Environment ID and Service token

  • After saving your dbt Semantic Layer you will get an Environment ID and a Host, and can generate a Service account token (also called Service Token)

dbt Cloud setup

3. Add dbt Cloud as a data source in Steep

  • In Steep, navigate to Settings / Data sources and add dbt Cloud
    • If this is your first data source in Steep, you will see a range of options. Select dbt Cloud from the Semantic API section
    • If you already have a database connection set up in Steep, select Add semantic API
  • Copy the Environment ID, Host and Service account token you got from the previous step and paste it into the form in Steep:

4. Connect

  • Hit Continue for your connection to be established and your dbt Semantic Layer metrics to be synced into Steep. Done 🎉

Syncing metrics to Steep

When first connecting, all dbt Semantic Layer metrics will be synced into Steep.

API sync

You can call an API endpoint at Steep to trigger a sync. This way you can automate the sync based on your needs by just integrating a call to Steep in your process of updating metrics. Go to Settings / Data sources and expand the API sync section for detailed instructions on how to set it up.

Manual sync

Anytime you update a metric in dbt Semantic Layer you can manually trigger a sync in Steep on Settings / Data sources

Owners and categories

Defining category and owners of metrics in metadata is coming soon. You can also manually assign category and owners via the Steep UI, in the metrics catalog.