From 75487c06f0c8d00f62b498d453db34f1fbb41c00 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 09:05:15 +0000 Subject: [PATCH 1/2] docs: note window function limits on dimensions and metrics --- references/dimensions.mdx | 4 ++++ references/metrics.mdx | 8 +++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 0c27d433..662947a7 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -22,6 +22,10 @@ models: description: "Unique identifier for a user." ``` + + Dimensions cannot use window functions in their `sql`. A dimension's SQL is inserted into the same `SELECT` as the main `GROUP BY` in the generated query, and SQL does not allow window functions in that position. If you need window-function logic on a metric, define a [post calculation metric](/references/metrics#post-calculation-metrics), which runs after the main aggregations. For row-level window logic on query results, use a [table calculation](/references/table-calculation-functions) instead. + + ## Dimension configuration diff --git a/references/metrics.mdx b/references/metrics.mdx index 8d26c605..0517347c 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -144,15 +144,21 @@ Aggregate metric types perform (surprise, surprise) aggregations. Sums and avera Aggregate metrics can _only_ reference dimensions, not other metrics. +Aggregate metrics cannot use window functions in their `sql`. Their SQL is wrapped in an aggregate function and evaluated as part of the main `GROUP BY` in the generated query, and SQL does not allow window functions inside an aggregate call. To use window functions on a metric, define a [post calculation metric](#post-calculation-metrics) instead. + ### Non-aggregate metrics Non-aggregate metrics are metric types that, you guessed it, do _not_ perform aggregations. Numbers and booleans are examples of non-aggregate metrics. These metric types perform a calculation on a single data point, so they can only reference aggregate metrics. They _cannot_ reference dimensions. +Non-aggregate metrics cannot use window functions in their `sql`. Their SQL is inserted alongside the aggregate metrics in the same `SELECT`, which runs in the same step as the `GROUP BY`, so window functions (which must run after aggregation) are not allowed. To use window functions on a metric, define a [post calculation metric](#post-calculation-metrics) instead. + ### Post calculation metrics -Post calculation metrics are computed after aggregate and non-aggregate metrics in the query. Because they run after the main aggregations, they can use window functions. Post calculation metrics: +Post calculation metrics are computed after aggregate and non-aggregate metrics in the query. Because they run after the main aggregations, they can use window functions — Lightdash wraps the aggregated results in an outer `SELECT` and evaluates the post calculation metric's SQL there, where `OVER (...)` clauses are valid. + +Post calculation metrics: - Can only reference aggregate and non-aggregate metrics (they cannot reference dimensions or other post calculation metrics) - Can be referenced in table calculations like any other metric From c2d97fe42ea60fadd957efd6cb3c9af2a80513a2 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 09:11:21 +0000 Subject: [PATCH 2/2] docs: recommend dbt or table calculations for window function logic --- references/dimensions.mdx | 2 +- references/metrics.mdx | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 662947a7..e551ba79 100644 --- a/references/dimensions.mdx +++ b/references/dimensions.mdx @@ -23,7 +23,7 @@ models: ``` - Dimensions cannot use window functions in their `sql`. A dimension's SQL is inserted into the same `SELECT` as the main `GROUP BY` in the generated query, and SQL does not allow window functions in that position. If you need window-function logic on a metric, define a [post calculation metric](/references/metrics#post-calculation-metrics), which runs after the main aggregations. For row-level window logic on query results, use a [table calculation](/references/table-calculation-functions) instead. + Dimensions cannot use window functions in their `sql`. A dimension's SQL is inserted into the same `SELECT` as the main `GROUP BY` in the generated query, and SQL does not allow window functions in that position. If you need window-function logic, either model it directly in your dbt model (so the value is precomputed before Lightdash queries it), or add a [table calculation](/references/table-calculation-functions) on the query results. Lightdash also supports a small set of built-in window operations through [post calculation metrics](/references/metrics#post-calculation-metrics) (`percent_of_previous`, `percent_of_total`, `running_total`). diff --git a/references/metrics.mdx b/references/metrics.mdx index 0517347c..539fbf8e 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -144,7 +144,7 @@ Aggregate metric types perform (surprise, surprise) aggregations. Sums and avera Aggregate metrics can _only_ reference dimensions, not other metrics. -Aggregate metrics cannot use window functions in their `sql`. Their SQL is wrapped in an aggregate function and evaluated as part of the main `GROUP BY` in the generated query, and SQL does not allow window functions inside an aggregate call. To use window functions on a metric, define a [post calculation metric](#post-calculation-metrics) instead. +Aggregate metrics cannot use window functions in their `sql`. Their SQL is wrapped in an aggregate function and evaluated as part of the main `GROUP BY` in the generated query, and SQL does not allow window functions inside an aggregate call. If you need window-function logic, either model it directly in your dbt model (so the value is precomputed before Lightdash queries it), or add a [table calculation](/references/table-calculation-functions) on the query results. Lightdash also supports a small set of built-in window operations through [post calculation metrics](#post-calculation-metrics) (`percent_of_previous`, `percent_of_total`, `running_total`). ### Non-aggregate metrics @@ -152,11 +152,13 @@ Non-aggregate metrics are metric types that, you guessed it, do _not_ perform ag Numbers and booleans are examples of non-aggregate metrics. These metric types perform a calculation on a single data point, so they can only reference aggregate metrics. They _cannot_ reference dimensions. -Non-aggregate metrics cannot use window functions in their `sql`. Their SQL is inserted alongside the aggregate metrics in the same `SELECT`, which runs in the same step as the `GROUP BY`, so window functions (which must run after aggregation) are not allowed. To use window functions on a metric, define a [post calculation metric](#post-calculation-metrics) instead. +Non-aggregate metrics cannot use window functions in their `sql`. Their SQL is inserted alongside the aggregate metrics in the same `SELECT`, which runs in the same step as the `GROUP BY`, so window functions (which must run after aggregation) are not allowed. If you need window-function logic, either model it directly in your dbt model (so the value is precomputed before Lightdash queries it), or add a [table calculation](/references/table-calculation-functions) on the query results. Lightdash also supports a small set of built-in window operations through [post calculation metrics](#post-calculation-metrics) (`percent_of_previous`, `percent_of_total`, `running_total`). ### Post calculation metrics -Post calculation metrics are computed after aggregate and non-aggregate metrics in the query. Because they run after the main aggregations, they can use window functions — Lightdash wraps the aggregated results in an outer `SELECT` and evaluates the post calculation metric's SQL there, where `OVER (...)` clauses are valid. +Post calculation metrics are computed after aggregate and non-aggregate metrics in the query. Because they run after the main aggregations, Lightdash wraps the aggregated results in an outer `SELECT` and evaluates the post calculation metric's SQL there, where window functions (`OVER (...)`) are valid. + +Post calculation metrics only cover a fixed set of built-in window operations: [`percent_of_previous`](#percent_of_previous), [`percent_of_total`](#percent_of_total), and [`running_total`](#running_total). They do not accept custom `OVER (...)` clauses. For anything else, model the logic directly in your dbt model, or use a [table calculation](/references/table-calculation-functions) on the query results. Post calculation metrics: