dbt Cloud

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.

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.

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

    model: ref('orders')

		entities:
      - name: order_id
        type: primary

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

		dimensions:
      - name: ordered_at
        type: time
        type_params:

          time_granularity: day

      - name: country
        type: categorical
        expr: country

2. Define metrics

Example metric:

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

3. Set metadata

Besides the core metric specification, it is possible to control some additional Steep metric properties from your dbt project using the meta field. This is optional and if not defined in your dbt project you can instead use the Steep UI to configure these properties for your metrics.

Currently supported properties are category_name (string), owner_emails(string array) and is_private(boolean). You define these in the config.meta field of metric.

# Example
metrics:
  - name: registrations
    ...
    config:
      meta:
        category_name: Onboarding
        owner_emails: [john@example.com]
        is_private: false

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.

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)

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