A metric is a timeseries aggregation over a table that supports zero or more dimensions. Some examples of metrics include:
- active users
- monthly recurring revenue (mrr)
In v1.0, dbt supports metric definitions as a new node type. Like exposures, metrics appear as nodes in the directed acyclic graph (DAG) and can be expressed in YAML files. Defining metrics in dbt projects encodes crucial business logic in tested, version-controlled code. Further, you can expose these metrics definitions to downstream tooling, which drives consistency and precision in metric reporting.
Review the video below to learn more about metrics, why they're important, and how to get started:
Benefits of defining metrics
See and select dependencies
As with Exposures, you can see everything that rolls up into a metric (
dbt ls -s +metric:*), and visualize them in dbt documentation. For more information, see "The
metric: selection method."
Defining a metric
You can define metrics in
.yml files nested under a
metrics: key. Metric names must:
- contain only letters, numbers, and underscores (no spaces or special characters)
- begin with a letter
- contain no more than 250 characters
For a short human-friendly name with title casing, spaces, and special characters, use the
label property. More examples and guidance for how to define and structure metrics can be found here..
- You cannot define metrics on ephemeral models. To define a metric, the materialization must have a representation in the data warehouse.
Metrics can have many declared properties, which define aspects of your metric. More information on properties and configs can be found here.
Available calculation methods
|count||This metric type will apply the |
|count_distinct||This metric type will apply the |
|sum||This metric type will apply the |
|average||This metric type will apply the |
|min||This metric type will apply the |
|max||This metric type will apply the |
Filters should be defined as a list of dictionaries that define predicates for the metric. Filters are combined using AND clauses. For more control, users can (and should) include the complex logic in the model powering the metric.
All three properties (
value) are required for each defined filter.
value must be defined as a string in YAML, because it will be compiled into queries as part of a string. If your filter's value needs to be surrounded in quotes inside the query (e.g. text or dates), use
- field: is_paying
- field: lifetime_value
- field: company_name
value: "'Acme, Inc'"
- field: signup_date
Querying Your Metric
You can dynamically query metrics directly in dbt and verify them before running a job in the deployment environment. To query your defined metric, you must have the dbt_metrics package installed. Information on how to install packages can be found here.
Use the following metrics package installation code in your packages.yml file and run
dbt deps to install the metrics package:
Once the package has been installed with
dbt deps, make sure to run the
dbt_metrics_calendar_model model as this is required for macros used to query metrics. More information on this, and additional calendar functionality, can be found in the project README.
Querying metrics with
metrics.calculate macro along with defined metrics to generate a SQL statement that runs the metric aggregation to return the correct metric dataset. Example below:
The example above doesn't display all the potential inputs you can provide to the macro.
You may find some pieces of functionality, like secondary calculations, complicated to use. We recommend reviewing the package README for more in-depth information about each of the inputs that are not covered in the table below.
|grain||The time grain that the metric will be aggregated to in the returned dataset||Required|
|dimensions||[||The dimensions you want the metric to be aggregated by in the returned dataset||Optional|
|secondary_calculations||[||Performs the specified secondary calculation on the metric results. Examples include period over period calculations, rolling calcultions, and period to date calculations.||Optional|
|start_date||Limits the date range of data used in the metric calculation by not querying data before this date||Optional|
|end_date||Limits the date range of data used in the metric claculation by not querying data after this date||Optional|
|where||A sql statment, or series of sql statements, that alter the final CTE in the generated sql. Most often used to limit the data to specific values of dimensions provided||Optional|
Secondary calculations are window functions you can add to the metric calculation and perform on the primary metric or metrics.
You can use them to compare values to an earlier period, calculate year-to-date sums, and return rolling averages. You can add custom secondary calculations into dbt projects - for more information on this, reference the package README.