Skip to main content


Metrics are new

An initial version of metrics was introduced in v1.0.0, following vibrant community discusion. Try them out, and let us know what you think!

Metrics are experimental

metrics will be released in v1.0, but they should not be considered a stable API. We reserve the right to make breaking changes to their schema in future minor versions. We will aim for backwards compatibility whenever possible.

Related documentation#

Getting started#

A metric is a timeseries aggregation over a table that supports zero or more dimensions. Some examples of metrics include:

  • active users
  • churn rate
  • mrr (monthly recurring revenue)

Starting in v1.0, dbt supports metric definitions as a new node type. Like exposures, metrics participate in the dbt DAG and can be expressed in yaml files. By defining metrics in dbt projects, analytics engineers can encode crucial business logic in tested, version controlled code. Further, these metrics definitions can be exposed to downstream tooling to drive consistency and precision in metric reporting.

Declaring a metric#

Exposures are defined in .yml files nested under an metrics: key.

# models/marts/product/schema.yml
version: 2
models: - name: dim_customers   ...
metrics:  - name: new_customers    label: New Customers    model: ref('dim_customers')    description: "The number of paid customers who are using the product"
    type: count    sql: user_id # superflous here, but shown as an example
    timestamp: signup_date    time_grains: [day, week, month]
    dimensions:      - plan      - country        filters:      - field: is_paying        value: true
    meta: {}

Available properties#

nameA unique identifier for the metricnew_customersyes
modelThe dbt model that powers this metricdim_customersyes
labelA short for name / label for the metricNew Customersno
descriptionLong form, human-readable description for the metricThe number of customers
typeThe type of calculation to perform when evaluating a metriccount_distinctyes
sqlThe expression to aggregate/calculate overuser_idyes
timestampThe time-based component of the metricsignup_dateyes
time_grainsOne or more "grains" at which the metric can be evaluated[day, week, month]yes
dimensionsA list of dimensions to group or filter the metric by[plan, country]no
filtersA list of filters to apply before calculating the metricSee belowno
metaArbitrary key/value store{team: Finance}no

Why define metrics?#

Use metric specifications in downstream tools. Metrics are available to dbt's compilation context via the graph.metrics variable. They are included in the manifest artifact for downstream metadata consumption.

See and select dependencies. As with exposures, it's possible to see everything that rolls up into a metric (dbt ls -s +metric:*), and visualize them in dbt documentation.

Metrics appear as pink nodes in the DAG (for now)

Metrics appear as pink nodes in the DAG (for now)

Open questions#

  • Should metrics be defined on top of more strongly typed attributes, rather than columns? dbt-core#4090
  • Should metrics include support for joins? How should dbt know about foreign-key relationships between models? dbt-core#4125
  • Should metrics inherit configurations from the models on which they are defined? Should it be possible to define metrics directly on models/columns, like tests?

These are just a start! We welcome you to check out open issues on GitHub, and join the conversation.