Skip to content

Apache DataFusion SQL Query Engine

docs: document negative n behavior for `nth_value` (#24557)

linfeng5f0ba13c804e
diff --git a/datafusion/functions-aggregate/src/nth_value.rs b/datafusion/functions-aggregate/src/nth_value.rs
index 32d9d3057c..5e7f9c6c31 100644
--- a/datafusion/functions-aggregate/src/nth_value.rs
+++ b/datafusion/functions-aggregate/src/nth_value.rs
@@ -85,7 +85,9 @@ pub fn nth_value(
),
argument(
name = "n",
- description = "The position (nth) of the value to retrieve, based on the ordering."
+ description = "The position of the value to retrieve. Positive values count from the first \
+ value, starting at 1; negative values count backward from the last value, where -1 \
+ returns the last value."
)
)]
/// Expression for a `NTH_VALUE(..., ... ORDER BY ...)` aggregation. In a multi
diff --git a/datafusion/functions-window/src/nth_value.rs b/datafusion/functions-window/src/nth_value.rs
index df72377216..0651872d74 100644
--- a/datafusion/functions-window/src/nth_value.rs
+++ b/datafusion/functions-window/src/nth_value.rs
@@ -217,7 +217,9 @@ static NTH_VALUE_DOCUMENTATION: LazyLock<Documentation> = LazyLock::new(|| {
)
.with_argument(
"n",
- "Integer. Specifies the row number (starting from 1) in the window frame.",
+ "Integer position in the window frame. Positive values count from the first \
+ row, starting at 1; negative values count backward from the last row, where -1 \
+ returns the last row.",
)
.with_sql_example(
r#"
diff --git a/docs/source/user-guide/sql/aggregate_functions.md b/docs/source/user-guide/sql/aggregate_functions.md
index 4f130d4008..12508ab149 100644
--- a/docs/source/user-guide/sql/aggregate_functions.md
+++ b/docs/source/user-guide/sql/aggregate_functions.md
@@ -705,7 +705,7 @@ nth_value(expression, n ORDER BY expression)
#### Arguments
- **expression**: The column or expression to retrieve the nth value from.
-- **n**: The position (nth) of the value to retrieve, based on the ordering.
+- **n**: The position of the value to retrieve. Positive values count from the first value, starting at 1; negative values count backward from the last value, where -1 returns the last value.
#### Example
diff --git a/docs/source/user-guide/sql/window_functions.md b/docs/source/user-guide/sql/window_functions.md
index 6496da1102..d13fb64f86 100644
--- a/docs/source/user-guide/sql/window_functions.md
+++ b/docs/source/user-guide/sql/window_functions.md
@@ -498,7 +498,7 @@ nth_value(expression, n)
#### Arguments
- **expression**: The column from which to retrieve the nth value.
-- **n**: Integer. Specifies the row number (starting from 1) in the window frame.
+- **n**: Integer position in the window frame. Positive values count from the first row, starting at 1; negative values count backward from the last row, where -1 returns the last row.
#### Example