This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 858d3bf7f9 minor: document EquivalenceProperties::project (#24063)
858d3bf7f9 is described below
commit 858d3bf7f9d36b0668946db7fb9c006892a95309
Author: Qi Zhu <[email protected]>
AuthorDate: Thu Aug 20 13:17:43 2026 +0000
minor: document EquivalenceProperties::project (#24063)
## Rationale for this change
`EquivalenceProperties::project` is a central, widely-called method, but
its doc comment was a single line ("Projects the equivalences within
according to `mapping` and `output_schema`"). That does not convey that
it carries orderings, the equivalence group, and constraints through the
mapping, nor the key subtlety that an ordering is preserved only through
an order-preserving expression (`SortProperties`). This tripped me up
while reasoning about why an ordering survived a projection containing
computed expressions, so I expanded the docs.
## What changes are included in this PR?
Documentation only. Expands the rustdoc on
`EquivalenceProperties::project` to describe:
- it carries orderings, the equivalence group, and constraints through
the mapping (not just a column-index remap);
- orderings survive only through order-preserving expressions,
determined from each expression's `SortProperties` (e.g. preserved
through `c + 1`, dropped through `abs(c)`; compound orderings like `a +
b` map to `a_new + b_new`);
- expressions/orderings not representable in `output_schema` are
dropped.
## Are these changes tested?
No code change. `cargo doc -p datafusion-physical-expr --no-deps` builds
cleanly with `RUSTDOCFLAGS="-D warnings"`.
## Are there any user-facing changes?
Documentation only.
---
.../src/equivalence/properties/mod.rs | 23 ++++++++++++++++++++--
1 file changed, 21 insertions(+), 2 deletions(-)
diff --git a/datafusion/physical-expr/src/equivalence/properties/mod.rs
b/datafusion/physical-expr/src/equivalence/properties/mod.rs
index 54269e07f9..f52b320ed2 100644
--- a/datafusion/physical-expr/src/equivalence/properties/mod.rs
+++ b/datafusion/physical-expr/src/equivalence/properties/mod.rs
@@ -1165,8 +1165,27 @@ impl EquivalenceProperties {
self.constraints.project(&indices)
}
- /// Projects the equivalences within according to `mapping` and
- /// `output_schema`.
+ /// Projects these equivalence properties onto `output_schema` according to
+ /// `mapping`, returning the properties that still hold for the projected
+ /// output.
+ ///
+ /// `mapping` maps each source expression (evaluated against the current
+ /// schema) to the output column(s) it produces. This is more than a
+ /// column-index remap: the orderings, the equivalence group and the
+ /// constraints are all carried through `mapping`, keeping only what the
+ /// projected schema can still express.
+ ///
+ /// - Orderings: an existing ordering is carried to a target only when the
+ /// mapping expression is order-preserving for it, as determined from the
+ /// expression's [`SortProperties`]. For example, an ordering on `c` is
+ /// preserved through `c + 1` but dropped through `abs(c)`. Orderings
+ /// implied by the mapping are also derived, e.g. an ordering on `a + b`
+ /// yields one on the projected `a_new + b_new`.
+ /// - Equivalence group: each class is re-expressed on the output columns.
+ /// - Constraints: projected onto the surviving column indices.
+ ///
+ /// Expressions and orderings not representable in `output_schema` are
+ /// dropped.
pub fn project(&self, mapping: &ProjectionMapping, output_schema:
SchemaRef) -> Self {
let eq_group = self.eq_group.project(mapping);
let orderings =
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
