This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 4fb4b216fb Minor: Document `ExecutionPlan::equivalence_properties`
more thoroughly (#8128)
4fb4b216fb is described below
commit 4fb4b216fb02349133f4204cf600004342e2e5c5
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon Nov 13 14:04:37 2023 -0500
Minor: Document `ExecutionPlan::equivalence_properties` more thoroughly
(#8128)
* Minor: Document ExecutionPlan::equivalence_properties more thoroughly
* Apply suggestions from code review
Co-authored-by: Liang-Chi Hsieh <[email protected]>
Co-authored-by: Mustafa Akur
<[email protected]>
---------
Co-authored-by: Liang-Chi Hsieh <[email protected]>
Co-authored-by: Mustafa Akur
<[email protected]>
---
datafusion/physical-plan/src/lib.rs | 18 +++++++++++++++++-
1 file changed, 17 insertions(+), 1 deletion(-)
diff --git a/datafusion/physical-plan/src/lib.rs
b/datafusion/physical-plan/src/lib.rs
index 9519f6a5a1..e5cd5e674c 100644
--- a/datafusion/physical-plan/src/lib.rs
+++ b/datafusion/physical-plan/src/lib.rs
@@ -203,7 +203,23 @@ pub trait ExecutionPlan: Debug + DisplayAs + Send + Sync {
.collect()
}
- /// Get the [`EquivalenceProperties`] within the plan
+ /// Get the [`EquivalenceProperties`] within the plan.
+ ///
+ /// Equivalence properties tell DataFusion what columns are known to be
+ /// equal, during various optimization passes. By default, this returns "no
+ /// known equivalences" which is always correct, but may cause DataFusion
to
+ /// unnecessarily resort data.
+ ///
+ /// If this ExecutionPlan makes no changes to the schema of the rows
flowing
+ /// through it or how columns within each row relate to each other, it
+ /// should return the equivalence properties of its input. For
+ /// example, since `FilterExec` may remove rows from its input, but does
not
+ /// otherwise modify them, it preserves its input equivalence properties.
+ /// However, since `ProjectionExec` may calculate derived expressions, it
+ /// needs special handling.
+ ///
+ /// See also [`Self::maintains_input_order`] and [`Self::output_ordering`]
+ /// for related concepts.
fn equivalence_properties(&self) -> EquivalenceProperties {
EquivalenceProperties::new(self.schema())
}
