diff --git a/references/dimensions.mdx b/references/dimensions.mdx index 0c27d433..e551ba79 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, 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`). + + ## Dimension configuration diff --git a/references/metrics.mdx b/references/metrics.mdx index 8d26c605..539fbf8e 100644 --- a/references/metrics.mdx +++ b/references/metrics.mdx @@ -144,15 +144,23 @@ 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. 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 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. 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. Post calculation metrics: +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: - 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