Metric definitions and semantic layer in dbt

Introduction

Metric definitions help you clearly describe how to measure things in your data. A semantic layer makes these definitions easy to use and understand for everyone.

When you want to track sales numbers like total revenue or average order value.

When different teams need to use the same definitions for metrics to avoid confusion.

When you want to build dashboards that update automatically with correct numbers.

When you want to make your data easier to explore without writing complex code.

When you want to keep your business rules consistent across reports.

Syntax

dbt

metrics:
  - name: total_revenue
    label: "Total Revenue"
    model: ref('orders')
    calculation_method: sum
    expression: amount
    timestamp: order_date
    dimensions:
      - product_category
      - region

The metrics block defines one or more metrics.

model points to the data source, calculation_method tells how to calculate, and expression is the field used.

Examples

This metric counts the number of orders.

dbt

metrics:
  - name: total_orders
    label: "Total Orders"
    model: ref('orders')
    calculation_method: count
    expression: order_id
    timestamp: order_date

This metric calculates the average amount per order.

dbt

metrics:
  - name: average_order_value
    label: "Average Order Value"
    model: ref('orders')
    calculation_method: average
    expression: amount
    timestamp: order_date

This metric sums revenue grouped by product category.

dbt

metrics:
  - name: total_revenue_by_category
    label: "Total Revenue by Category"
    model: ref('orders')
    calculation_method: sum
    expression: amount
    timestamp: order_date
    dimensions:
      - product_category

Sample Program

This example defines a metric for total revenue by product category. Then it shows SQL to calculate it from the orders table.

dbt

metrics:
  - name: total_revenue
    label: "Total Revenue"
    model: ref('orders')
    calculation_method: sum
    expression: amount
    timestamp: order_date
    dimensions:
      - product_category


-- Example SQL to use the metric in a dbt model
select
  product_category,
  sum(amount) as total_revenue
from {{ ref('orders') }}
group by product_category
order by total_revenue desc;

Important Notes

Always use clear names and labels for metrics so everyone understands them.

Dimensions let you break down metrics by categories like region or product type.

The semantic layer helps keep metric logic in one place, avoiding mistakes in reports.

Summary

Metric definitions describe how to measure key numbers in your data.

The semantic layer makes metrics easy to find and use across your team.

Using metrics consistently helps keep reports accurate and trustworthy.