From 9f45bca46ff1216a4a690cd0afc7efdddebe6335 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Sun, 8 Nov 2026 08:54:27 -0500 Subject: [PATCH 1/3] docs: add example and cross-links to GroupingEquivalenceClass Co-Authored-By: Claude Fable 5.1 --- .../physical-expr/src/equivalence/grouping.rs | 30 ++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/datafusion/physical-expr/src/equivalence/grouping.rs b/datafusion/physical-expr/src/equivalence/grouping.rs index 2fce6dad8292d..ab84fb1f49836 100644 --- a/datafusion/physical-expr/src/equivalence/grouping.rs +++ b/datafusion/physical-expr/src/equivalence/grouping.rs @@ -22,10 +22,38 @@ use datafusion_physical_expr_common::physical_expr::format_physical_expr_list; /// order. Contiguity applies to the complete partition stream, not separately /// to each record batch. /// +/// For example, consider the following table: +/// +/// ```text +/// ┌───┬───┬───┐ +/// │ a │ b │ c │ +/// ├───┼───┼───┤ +/// │ 2 │ 1 │ 5 │ +/// │ 2 │ 1 │ 3 │ +/// │ 1 │ 3 │ 4 │ +/// │ 2 │ 2 │ 1 │ +/// │ 2 │ 2 │ 2 │ +/// └───┴───┴───┘ +/// ``` +/// +/// * Is grouped by `[a, b]`, as rows with the same `(a, b)` are contiguous, +/// even though the table is not sorted by `a`, `b` nor `(a, b)`. +/// * Is grouped by `[b]`, since each value of `b` is in one run. +/// * Is NOT grouped by `[a]`, because `a = 2` appears in two separate runs. +/// /// Expression order within an entry is not significant: `[a, b]` and `[b, a]` /// describe the same grouping. Entries do not imply properties for subsets; -/// `[a, b]` alone says nothing about whether all rows with the same `a` are +/// as the table shows, `[a, b]` does not imply `[a]` as the same `a` may not be /// contiguous. +/// +/// # See also +/// * [`OrderingEquivalenceClass`] for the stronger property that rows are +/// sorted. +/// * [`EquivalenceProperties`] for how groupings relate to the other +/// properties of a plan node. +/// +/// [`EquivalenceProperties`]: crate::equivalence::EquivalenceProperties +/// [`OrderingEquivalenceClass`]: crate::equivalence::OrderingEquivalenceClass #[derive(Clone, Debug, Default)] pub struct GroupingEquivalenceClass { groupings: Vec>>, From 5769f02c9cb8f418ec0d6197083b3bab6d7eba0a Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 10 Nov 2026 20:21:35 -0500 Subject: [PATCH 2/3] docs: note that the example is also grouped by tuples containing c Co-Authored-By: Claude Fable 5.2 --- datafusion/physical-expr/src/equivalence/grouping.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/datafusion/physical-expr/src/equivalence/grouping.rs b/datafusion/physical-expr/src/equivalence/grouping.rs index ab84fb1f49836..f867ca13eb83d 100644 --- a/datafusion/physical-expr/src/equivalence/grouping.rs +++ b/datafusion/physical-expr/src/equivalence/grouping.rs @@ -39,6 +39,8 @@ use datafusion_physical_expr_common::physical_expr::format_physical_expr_list; /// * Is grouped by `[a, b]`, as rows with the same `(a, b)` are contiguous, /// even though the table is not sorted by `a`, `b` nor `(a, b)`. /// * Is grouped by `[b]`, since each value of `b` is in one run. +/// * Is grouped by `[c]`, and by any tuple that contains `c` such as `[a, c]`, +/// because each value of `c` is distinct, so every row is its own run. /// * Is NOT grouped by `[a]`, because `a = 2` appears in two separate runs. /// /// Expression order within an entry is not significant: `[a, b]` and `[b, a]` From 7121542de6356c6c72fe22ab512cc83d81bab47f Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 11 Nov 2026 09:19:28 -0500 Subject: [PATCH 3/3] docs: shorten explanation of grouping by c Co-Authored-By: Claude Fable 5.2 --- datafusion/physical-expr/src/equivalence/grouping.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/datafusion/physical-expr/src/equivalence/grouping.rs b/datafusion/physical-expr/src/equivalence/grouping.rs index f867ca13eb83d..4f0c249e1244a 100644 --- a/datafusion/physical-expr/src/equivalence/grouping.rs +++ b/datafusion/physical-expr/src/equivalence/grouping.rs @@ -40,7 +40,7 @@ use datafusion_physical_expr_common::physical_expr::format_physical_expr_list; /// even though the table is not sorted by `a`, `b` nor `(a, b)`. /// * Is grouped by `[b]`, since each value of `b` is in one run. /// * Is grouped by `[c]`, and by any tuple that contains `c` such as `[a, c]`, -/// because each value of `c` is distinct, so every row is its own run. +/// because each value of `c` is distinct. /// * Is NOT grouped by `[a]`, because `a = 2` appears in two separate runs. /// /// Expression order within an entry is not significant: `[a, b]` and `[b, a]`