Document window function limits on dimensions and metrics

references/dimensions.mdx

@@ -22,6 +22,10 @@ models:
         description: "Unique identifier for a user."
 ```
 
+<Warning>
+  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`).
+</Warning>
+
 
 ## Dimension configuration
 

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