You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by gi...@apache.org on 2026/08/21 14:00:46 UTC
(datafusion) branch gh-readonly-queue/main/pr-24557-a4e071d17a4d691fe4764a2a5180b94412667240 created (now 5f0ba13c80)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a change to branch gh-readonly-queue/main/pr-24557-a4e071d17a4d691fe4764a2a5180b94412667240
in repository https://gitbox.apache.org/repos/asf/datafusion.git
at 5f0ba13c80 docs: document negative n behavior for `nth_value` (#24557)
This branch includes the following new commits:
new 5f0ba13c80 docs: document negative n behavior for `nth_value` (#24557)
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org
(datafusion) 01/01: docs: document negative n behavior for `nth_value` (#24557)
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-24557-a4e071d17a4d691fe4764a2a5180b94412667240
in repository https://gitbox.apache.org/repos/asf/datafusion.git
commit 5f0ba13c804ea8835766e68ba0ed3f3c8ab54a93
Author: linfeng <33...@users.noreply.github.com>
AuthorDate: Fri Aug 21 14:00:23 2026 +0000
docs: document negative n behavior for `nth_value` (#24557)
## Which issue does this PR close?
<!--
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax. For example
`Closes #123` indicates that this PR will close issue #123.
-->
- Follow-up to #24453.
## Rationale for this change
<!--
Why are you proposing this change? If this is already explained clearly
in the issue then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand
your changes and offer better suggestions for fixes.
Please explain the problem you are trying to solve in terms of the
user-visible
behavior, rather than the implementation.
For example, "The code in `foo.rs` doesn't handle nulls" is a symptom of
the
implementation. "COUNT(DISTINCT) returns wrong results when the column
contains
nulls" is the user-visible problem.
-->
`nth_value` supports negative `n`, but the user documentation only
describes positive, one-based positions. This behavior was discussed
while reviewing #24453, where a documentation follow-up was proposed.
Negative `n` is a DataFusion extension that counts backward from the end
of the ordered group or window frame. It provides the behavior of
SQL-standard `from last`.
## What changes are included in this PR?
<!--
There is no need to duplicate the description in the issue here, but it
is sometimes worth providing a summary of the individual changes in this
PR.
-->
- Document positive and negative `n` for the aggregate `nth_value`.
- Document positive and negative `n` for the window `nth_value`.
- Update the generated aggregate and window function documentation.
## Are these changes tested?
<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code
If tests are not included in your PR, please explain why (for example,
are they covered by existing tests)?
-->
Yes. Documentation formatting was checked.
## Are there any user-facing changes?
<!--
If there are user-facing changes then we may require documentation to be
updated before approving the PR.
If there are any breaking changes to public APIs, please add the `api
change` label.
-->
Documentation only;
---
datafusion/functions-aggregate/src/nth_value.rs | 4 +++-
datafusion/functions-window/src/nth_value.rs | 4 +++-
docs/source/user-guide/sql/aggregate_functions.md | 2 +-
docs/source/user-guide/sql/window_functions.md | 2 +-
4 files changed, 8 insertions(+), 4 deletions(-)
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
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org