From c68d294b0dc4fb8d3f682d6b670b681de58e00e7 Mon Sep 17 00:00:00 2001 From: goodroot <9484709+goodroot@users.noreply.github.com> Date: Mon, 25 Nov 2024 13:35:46 -0800 Subject: [PATCH] return more window function explanations --- documentation/reference/function/window.md | 158 ++++++++++++++++++--- 1 file changed, 142 insertions(+), 16 deletions(-) diff --git a/documentation/reference/function/window.md b/documentation/reference/function/window.md index 6257a1f6..63363230 100644 --- a/documentation/reference/function/window.md +++ b/documentation/reference/function/window.md @@ -245,7 +245,17 @@ Frame boundaries determine which rows are included in the window calculation: - ` PRECEDING`: Starts or ends at a specified number of rows or interval before the current row - `CURRENT ROW`: Starts or ends at the current row -> **Default Frame**: If unspecified, defaults to `RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW` +When the frame clause is not specified, the default frame is +`RANGE UNBOUNDED PRECEDING`, which includes all rows from the start of the +partition to the current row. + +- If `ORDER BY` is not present, the frame includes the entire partition, as all + rows are considered equal. + +- If `ORDER BY` is present, the frame includes all rows from the start of the + partition to the current row. Note that `UNBOUNDED FOLLOWING` is only allowed + when the frame start is `UNBOUNDED PRECEDING`, which means the frame includes + the entire partition. ### Restrictions @@ -276,16 +286,37 @@ Modifies the window frame by excluding certain rows: ### avg() -Calculates the average of a numeric expression over the window frame. +In the context of window functions, `avg(value)` calculates the average of +`value` over the set of rows defined by the window frame. + +**Arguments:** + +- `value`: The column of numeric values to calculate the average of. + +**Return value:** + +- The average of `value` for the rows in the window frame. + +**Description** + +When used as a window function, `avg()` operates on a "window" of rows defined +by the `OVER` clause. The rows in this window are determined by the +`PARTITION BY`, `ORDER BY`, and frame specification components of the `OVER` +clause. + +The `avg()` function respects the frame clause, meaning it only includes rows +within the specified frame in the calculation. The result is a separate average +for each row, based on the corresponding window of rows. + +Note that the order of rows in the result set is not guaranteed to be the same +with each execution of the query. To ensure a consistent order, use an +`ORDER BY` clause outside of the `OVER` clause. **Syntax:** ```questdb-sql title="avg() syntax" avg(value) OVER (window_definition) ``` -**Arguments:** -- `value`: Numeric column or expression - **Example:** ```questdb-sql title="avg() example" demo SELECT @@ -300,18 +331,39 @@ SELECT FROM trades; ``` -### sum() +### Cumulative sum() -Calculates the sum of a numeric expression over the window frame. +In the context of window functions, `sum(value)` calculates the sum of `value` +in the set of rows defined by the window frame. Also known as "cumulative sum". + +**Arguments:** + +- `value`: Any numeric value. + +**Return value:** + +- The sum of `value` for the rows in the window frame. + +**Description** + +When used as a window function, `sum()` operates on a "window" of rows defined +by the `OVER` clause. The rows in this window are determined by the +`PARTITION BY`, `ORDER BY`, and frame specification components of the `OVER` +clause. + +The `sum()` function respects the frame clause, meaning it only includes rows +within the specified frame in the calculation. The result is a separate value +for each row, based on the corresponding window of rows. + +Note that the order of rows in the result set is not guaranteed to be the same +with each execution of the query. To ensure a consistent order, use an +`ORDER BY` clause outside of the `OVER` clause. **Syntax:** ```questdb-sql title="sum() syntax" sum(value) OVER (window_definition) ``` -**Arguments:** -- `value`: Numeric column or expression - **Example:** ```questdb-sql title="sum() example" demo SELECT @@ -354,16 +406,37 @@ FROM trades; ### first_value() -Returns the first value in the window frame. +In the context of window functions, `first_value(value)` calculates the first +`value` in the set of rows defined by the window frame. + +**Arguments:** + +- `value`: Any numeric value. + +**Return value:** + +- The first occurrence of `value` (including null) for the rows in the window + frame. + +**Description** + +`first_value()` operates on a "window" of rows defined by the `OVER` clause. The +rows in this window are determined by the `PARTITION BY`, `ORDER BY`, and frame +specification components of the `OVER` clause. + +The `first_value()` function respects the frame clause, meaning it only includes +rows within the specified frame in the calculation. The result is a separate +value for each row, based on the corresponding window of rows. + +Note that the order of rows in the result set is not guaranteed to be the same +with each execution of the query. To ensure a consistent order, use an +`ORDER BY` clause outside of the `OVER` clause. **Syntax:** ```questdb-sql title="first_value() syntax" first_value(value) OVER (window_definition) ``` -**Arguments:** -- `value`: Column or expression - **Example:** ```questdb-sql title="first_value() example" demo SELECT @@ -379,7 +452,34 @@ FROM trades; ### rank() -Assigns a rank to each row within the partition, with gaps for ties. +In the context of window functions, `rank()` assigns a unique rank to each row +within the window frame, with the same rank assigned to rows with the same +values. Rows with equal values receive the same rank, and a gap appears in the +sequence for the next distinct value; that is, the `row_number` of the first row +in its peer group. + +**Arguments:** + +- `rank()` does not require arguments. + +**Return value:** + +- The rank of each row within the window frame. Return value type is `long`. + +**Description** + +When used as a window function, `rank()` operates on a "window" of rows defined +by the `OVER` clause. The rows in this window are determined by the +`PARTITION BY` and `ORDER BY` components of the `OVER` clause. + +The `rank()` function assigns a unique rank to each row within its window, with +the same rank assigned to rows with the same values in the `ORDER BY` clause of +the `OVER` clause. It ignores the frame clause, meaning it considers all rows in +each partition, regardless of the frame specification. + +Note that the order of rows in the result set is not guaranteed to be the same +with each execution of the query. To ensure a consistent order, use an +`ORDER BY` clause outside of the `OVER` clause. **Syntax:** ```questdb-sql title="rank() syntax" @@ -401,7 +501,33 @@ FROM trades; ### row_number() -Assigns a unique sequential integer to rows within a partition. +In the context of window functions, `row_number()` assigns a unique row number +to each row within the window frame. For each partition, the row number starts +with one and increments by one. + +**Arguments:** + +- `row_number()` does not require arguments. + +**Return value:** + +- The row number of each row within the window frame. Return value type is + `long`. + +**Description** + +When used as a window function, `row_number()` operates on a "window" of rows +defined by the `OVER` clause. The rows in this window are determined by the +`PARTITION BY` and `ORDER BY` components of the `OVER` clause. + +The `row_number()` function assigns a unique row number to each row within its +window, starting at one for the first row in each partition and incrementing by +one for each subsequent row. It ignores the frame clause, meaning it considers +all rows in each partition, regardless of the frame specification. + +Note that the order of rows in the result set is not guaranteed to be the same +with each execution of the query. To ensure a consistent order, use an +`ORDER BY` clause outside of the `OVER` clause. **Syntax:** ```questdb-sql title="row_number() syntax"