From ae426fd3a8b05de56e285c383b204154796f1986 Mon Sep 17 00:00:00 2001 From: Jake Peterson Date: Tue, 20 May 2025 15:34:21 -0500 Subject: [PATCH 1/2] clarify metrics ref doc --- references/metrics.mdx | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index 44d02e9..cdbd86a 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -7,47 +7,55 @@ A metric is a value that describes or summarizes features from a collection of d In Lightdash, metrics are used to summarize dimensions or, sometimes, other metrics. + ## Adding metrics to your project using the `meta` tag. -### 1. Using the column `meta` tag (Suggested) + +### 1. Using the column `meta` tag To add a metric to Lightdash using the `meta` tag, you define it in your dbt project under the dimension name you're trying to describe/summarize. ```yaml models: - - name: my_model + - name: orders_model columns: - - name: user_id # dimension name of your metric + - name: user_id # dimension your metric is aggregating meta: metrics: - num_unique_user_ids: # name of your metric + distinct_user_ids: # name of your metric type: count_distinct # metric type - num_user_ids: - type: count + - name: revenue # dimension your metric is aggregating + meta: + metrics: + sum_revenue: # name of your metric + type: sum # metric type ``` Once you've got the hang of what these metrics look like, read more about the [metric types you can use below.](#metric-types) + ### 2. Using the model `meta` tag -Sometimes a metric references many columns, in these cases you can define the metric at the model level: +Sometimes a metric references multiple columns, in these cases you can define the metric at the model level: ```yaml -version: 2 - models: - - name: my_model + - name: orders_model meta: metrics: - num_unique_user_ids: - type: count_distinct - sql: ${TABLE}.user_id + revenue_per_user: + type: number # number type metrics can only reference other METRICS - DIMENSIONS cannot be used in this type + sql: ${sum_revenue} / ${distinct_user_ids} # two aggregation metrics from this model are referenced here + sum_total_paid: + type: sum # sum or count metrics can only reference DIMENSIONS - METRICS cannot be used in this type + sql: ${revenue} + ${taxes_paid} # two dimensions are added, then put inside a sum() aggregation ``` ## Metric Categories Each metric type falls into one of these categories. The metric categories tell you whether the metric type is an aggregation and what type of fields the metric can reference: + ### Aggregate metrics Aggregate metric types perform (surprise, surprise) aggregations. Sums and averages are examples of aggregate metrics: they are measurements summarizing a collection of data points. From 0f99619b32ce30cf6929b0bd1f8f39c473830d2f Mon Sep 17 00:00:00 2001 From: Jake Peterson Date: Tue, 20 May 2025 15:43:50 -0500 Subject: [PATCH 2/2] clarify aggreate vs non aggregate --- references/metrics.mdx | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/references/metrics.mdx b/references/metrics.mdx index cdbd86a..a18b0e7 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -31,6 +31,8 @@ models: type: sum # metric type ``` + + Once you've got the hang of what these metrics look like, read more about the [metric types you can use below.](#metric-types) @@ -44,13 +46,21 @@ models: meta: metrics: revenue_per_user: - type: number # number type metrics can only reference other METRICS - DIMENSIONS cannot be used in this type - sql: ${sum_revenue} / ${distinct_user_ids} # two aggregation metrics from this model are referenced here + type: number + sql: ${sum_revenue} / ${distinct_user_ids} sum_total_paid: - type: sum # sum or count metrics can only reference DIMENSIONS - METRICS cannot be used in this type - sql: ${revenue} + ${taxes_paid} # two dimensions are added, then put inside a sum() aggregation + type: sum + sql: ${revenue} + ${taxes_paid} ``` + + **Non-aggregate metrics** (`number`, `boolean`, etc.) can only reference other metrics in `sql:` since they are inserted directly into the generated SQL query without being wrapped in an aggregate function. + + **Aggregate metrics** (`sum`, `count_distinct`, etc.) can only reference dimensions since they are wrapped in an aggregate function before being added to the generated SQL query. Wrapping an aggreate function in another aggregate function will cause an error. + + +Read on to learn more about aggregate vs non-aggregate metrics! + ## Metric Categories Each metric type falls into one of these categories. The metric categories tell you whether the metric type is an aggregation and what type of fields the metric can reference: