alamb opened a new pull request, #27250: URL: https://github.com/apache/datafusion/pull/27250
## Which issue does this PR close? - N/A, documentation only. ## Rationale for this change While reviewing https://github.com/apache/datafusion/pull/27191 I was researching how `EquivalenceProperties` tracks orderings, equal expressions, constants and groupings, and wanted to write down what I learned so others do not have to repeat it. The concepts were documented in pieces across several structs, with no single place that explained them together or defined terms such as *normal form*, *required ordering*, or *per-partition constant*. ## What changes are included in this PR? Rustdoc only. The `EquivalenceProperties` doc in `datafusion/physical-expr/src/equivalence/properties/mod.rs` becomes the hub that the other struct docs link to. It keeps the existing examples and adds: - An overview table mapping each concept to the struct that stores it. - **Constants**: uniform vs heterogeneous, with a filter example and a `UNION ALL` example showing why a heterogeneous constant must stay in an ordering. - **Constants within a window partition**: what a window partition is, as opposed to an output partition, and how a whole-partition aggregate is recorded as `[k, w]` in all four sort directions, with examples for `PARTITION BY`, no `PARTITION BY`, and set-monotonic aggregates. - **Required orderings**: what a requirement is and where it comes from. - **Normal form** and **Checking whether a requirement is satisfied**. - **Discovering orderings**, with a `CAST` example of an ordering implied through an equality. Back-links to those sections from `PhysicalSortRequirement`, `LexRequirement` and `OrderingRequirements` (via docs.rs URLs, since `physical-expr-common` cannot link upward), from `ExecutionPlan::required_input_ordering`, and from `window_equivalence_properties`. Split out of https://github.com/apache/datafusion/pull/27234. Companion splits: https://github.com/apache/datafusion/pull/27237 (`GroupingEquivalenceClass`) and https://github.com/apache/datafusion/pull/27238 (`EquivalenceClass`, `ConstExpr`, `OrderingEquivalenceClass`), whose links point at the sections added here. ## What is the testing strategy for this PR? No code changes. `cargo doc` with `-D warnings` passes for the three touched crates, and the existing `EquivalenceProperties` doc test still passes. ## Are there any user-facing changes? No. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
