Metric properties
Metrics define measurable quantities that you can query through the Semantic Layer. You define them in different places, depending on your dbt version:
- In a model using the latest YAML spec. Top-level
metrics:list on a model that has semantic modeling enabled, alongsidesemantic_model:andcolumns:. Available in the dbt platform Latest release track and the dbt Fusion engine. - In the standalone legacy YAML spec. Refer to Creating metrics for more information.
The latest YAML spec is supported in the following environments:
- dbt platform (Latest release track)
- dbt Fusion engine
- dbt Core v1.12
For more information, refer to Migrate to the latest YAML spec.
Latest spec (model YAML)
In the latest YAML spec, you can define metrics on a model that has semantic modeling enabled. Add a top-level metrics list alongside semantic_model and columns (metrics are not nested under semantic_model). Type-specific settings are top-level keys on each metric.
Available metric properties (latest spec)
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Unique metric name. Use lowercase letters, numbers, and underscores. |
| type | string | Yes | One of: simple, cumulative, ratio, derived, conversion. |
| description | string | No | Documentation for the metric. |
| label | string | No | Display name in downstream tools. |
| filter | string | No | MetricFlow filter expression (dimensions, entities, or other metrics). |
| config | object | No | Supports meta, group, tags, enabled. |
Properties by metric type (latest spec)
| Metric type | Key properties |
|---|---|
| All | name, type, description, label, hidden, filter, config |
| Simple | agg, expr, time_granularity, agg_time_dimension, join_to_timespine, fill_nulls_with; optionally non_additive_dimension |
| Derived | expr, input_metrics (each with optional alias, filter, offset_window) |
| Ratio | numerator, denominator (each a metric name or a dict with name, filter, alias) |
| Conversion | entity, calculation, base_metric, conversion_metric, window; optional constant_properties |
| Cumulative | input_metric, window, grain_to_date, period_agg |
Cross-model metrics: Metrics under a model's metrics: list can only reference that semantic model. Metrics that depend on other semantic models (for example, cross-model cumulative, ratio, derived, or conversion) go in a top-level metrics: block (outside models:). This can live in the same YAML file or a separate file.
Note: For the legacy spec, all metrics were defined in standalone YAML; there was no model-level metrics: list.
For the latest spec, refer to Semantic models. For metric types, type_params, and more examples, refer to Creating metrics.
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
