Skip to content

Commit 858d3bf

Browse files
authored
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.
1 parent ceaef16 commit 858d3bf

1 file changed

Lines changed: 21 additions & 2 deletions

File tree

  • datafusion/physical-expr/src/equivalence/properties

‎datafusion/physical-expr/src/equivalence/properties/mod.rs‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1165,8 +1165,27 @@ impl EquivalenceProperties {
11651165
self.constraints.project(&indices)
11661166
}
11671167

1168-
/// Projects the equivalences within according to `mapping` and
1169-
/// `output_schema`.
1168+
/// Projects these equivalence properties onto `output_schema` according to
1169+
/// `mapping`, returning the properties that still hold for the projected
1170+
/// output.
1171+
///
1172+
/// `mapping` maps each source expression (evaluated against the current
1173+
/// schema) to the output column(s) it produces. This is more than a
1174+
/// column-index remap: the orderings, the equivalence group and the
1175+
/// constraints are all carried through `mapping`, keeping only what the
1176+
/// projected schema can still express.
1177+
///
1178+
/// - Orderings: an existing ordering is carried to a target only when the
1179+
/// mapping expression is order-preserving for it, as determined from the
1180+
/// expression's [`SortProperties`]. For example, an ordering on `c` is
1181+
/// preserved through `c + 1` but dropped through `abs(c)`. Orderings
1182+
/// implied by the mapping are also derived, e.g. an ordering on `a + b`
1183+
/// yields one on the projected `a_new + b_new`.
1184+
/// - Equivalence group: each class is re-expressed on the output columns.
1185+
/// - Constraints: projected onto the surviving column indices.
1186+
///
1187+
/// Expressions and orderings not representable in `output_schema` are
1188+
/// dropped.
11701189
pub fn project(&self, mapping: &ProjectionMapping, output_schema: SchemaRef) -> Self {
11711190
let eq_group = self.eq_group.project(mapping);
11721191
let orderings =

0 commit comments

Comments
 (0)