2010YOUY01 commented on code in PR #26351: URL: https://github.com/apache/datafusion/pull/26351#discussion_r4278728405
########## datafusion/physical-optimizer/src/optimizer.rs: ########## @@ -16,6 +16,85 @@ // under the License. //! Physical optimizer traits +//! +//! # Physical Optimizer Contract +//! +//! This section explains the contract for extending or replacing the default +//! list of optimizer rules. +//! +//! [`PhysicalOptimizer::new`] defines the default rule sequence: +//! +//! ```text +//! // Default rules +//! let rules = vec![ +//! rule1, +//! rule2, +//! rule3, +//! rule4, +//! // ... +//! ]; +//! ``` +//! +//! It's recommended to keep the default rule order and using supported configuration +//! options to disable optimizations. These variations preserve correctness. For +//! example, `SET datafusion.optimizer.enable_distinct_aggregation_soft_limit = false` +//! disables the distinct aggregation soft-limit optimization. Custom pipelines +//! require more care, as described below. +//! +//! ## Custom Optimizer Pipelines +//! +//! The following extension pipeline can expect built-in optimizer rules to preserve +//! plan validity, but not to provide complete optimization coverage. +//! +//! ```text +//! // Custom rules +//! let rules = vec![ +//! rule3, +//! extension_rule_1, +//! rule1, +//! ]; +//! ``` +//! +//! - **Plan Validity:** Applying `rule1` after `rule3` should preserve query +//! semantics and return a valid plan without internal errors or invalid +//! plan shapes. +//! +//! The pipeline must still satisfy requirements needed for correctness. For +//! example, [`EnsureRequirements`] enforces input distribution and ordering. +//! Some constraints remain implicit or are documented only in individual rules. +//! +//! - **Optimization Coverage:** A non-default rule order may expose rules to Review Comment: A CI tool might help to verify optimization coverage is reachable from queries. - https://github.com/apache/datafusion/pull/26219 -- 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]
