(datafusion) 01/01: Docs: Add `PartialSortExec` documentation (#23092)

[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-23092-a1f56b7ec549718b502e79ad5d6c4a88174fc5af
in repository https://gitbox.apache.org/repos/asf/datafusion.git

commit ad1a26002b8bac436a8f20761f42713e23dc70b2
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Mon Jun 22 17:05:34 2026 -0400

    Docs: Add `PartialSortExec` documentation (#23092)
    
    @mhilton mentioned the other day that he was looking for PartialSortExec
    but it wasn't well documented
    
    So let's fix that!
    
    ## Summary
    - expand PartialSortExec rustdoc with a concise explanation
    - add an ASCII example showing partial sorting from (a, b) to (a, b, c)
    
    cc @berkaysynnada and @akurmustafa perhaps you might have some time to
    review this PR
---
 datafusion/physical-plan/src/sorts/partial_sort.rs | 32 +++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/datafusion/physical-plan/src/sorts/partial_sort.rs b/datafusion/physical-plan/src/sorts/partial_sort.rs
index f7b403d943..d215e5296f 100644
--- a/datafusion/physical-plan/src/sorts/partial_sort.rs
+++ b/datafusion/physical-plan/src/sorts/partial_sort.rs
@@ -77,7 +77,37 @@ use datafusion_physical_expr::LexOrdering;
 use futures::{Stream, StreamExt, ready};
 use log::trace;
 
-/// Partial Sort execution plan.
+/// Sort execution plan for inputs that are already partially sorted.
+///
+/// This operator takes input ordered by a prefix of the required ordering, and
+/// produces output ordered by the required ordering. This is useful for
+/// unbounded or large inputs where a [`SortExec`] must buffer all rows before
+/// producing any output.
+///
+/// [`PartialSortExec`] relies on the property that rows with the same sort
+/// prefix are contiguous, so it can sort one prefix group at a time, emitting
+/// completed groups without reading (and buffering) the entire input.
+///
+/// For example, if the required output is `(a, b, c)`, but the input is only
+/// ordered by `(a, b)`, `PartialSortExec` sorts only within each `(a, b)`
+/// group to produce output ordered by `(a, b, c)`.
+///
+/// ```text
+/// input ordered by a, b              output ordered by a, b, c
+///
+/// +---+---+---+                      +---+---+---+
+/// | a | b | c |                      | a | b | c |
+/// +---+---+---+                      +---+---+---+
+/// | 0 | 0 | 3 |  -- same group  -->  | 0 | 0 | 2 |
+/// | 0 | 0 | 2 |                      | 0 | 0 | 3 |
+/// | 0 | 1 | 1 |  -- single row  -->  | 0 | 1 | 1 |
+/// | 0 | 2 | 4 |  -- same group -->   | 0 | 2 | 0 |
+/// | 0 | 2 | 0 |                      | 0 | 2 | 4 |
+/// | 1 | 0 | 5 |  -- single row  -->  | 1 | 0 | 5 |
+/// +---+---+---+                      +---+---+---+
+/// ```
+///
+/// [`SortExec`]: crate::sorts::sort::SortExec
 #[derive(Debug, Clone)]
 pub struct PartialSortExec {
     /// Input schema


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org