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-24063-ceaef16778f3422312cc1e22ddf40e8f6acda56b in repository https://gitbox.apache.org/repos/asf/datafusion.git
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]
