(datafusion) branch main updated: docs(minor): Explain the role of `EnsureRequirements` in the physical optimizer pipeline (#26479)

[gi...@apache.org]

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 fbf77371a0 docs(minor): Explain the role of `EnsureRequirements` in the physical optimizer pipeline (#26479)
fbf77371a0 is described below

commit fbf77371a0512765ebf81fdc60e4a6cdceb8101f
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Mon Oct 19 10:36:58 2026 +0000

    docs(minor): Explain the role of `EnsureRequirements` in the physical optimizer pipeline (#26479)
    
    ## Which issue does this PR close?
    
    - Related to https://github.com/apache/datafusion/pull/26351 (split out
    so it can be reviewed and merged independently)
    
    ## Rationale for this change
    
    While reviewing #26351 @jayzhan211 @2010YOUY01 and I have observed that
    `EnsureRequirements` is special among the physical optimizer rules, but
    that isn't documented on the rule itself
    
    ## What changes are included in this PR?
    
    Documentation only, in
    `datafusion/physical-optimizer/src/ensure_requirements/mod.rs`:
    
    ## What is the testing strategy for this PR?
    
    CI
    ## Are there any user-facing changes?
    
    No, only rustdoc text.
    
    Co-authored-by: Claude Fable 5.1 <no...@anthropic.com>
---
 .../physical-optimizer/src/ensure_requirements/mod.rs  | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/datafusion/physical-optimizer/src/ensure_requirements/mod.rs b/datafusion/physical-optimizer/src/ensure_requirements/mod.rs
index 56ca430d69..4554bdf35d 100644
--- a/datafusion/physical-optimizer/src/ensure_requirements/mod.rs
+++ b/datafusion/physical-optimizer/src/ensure_requirements/mod.rs
@@ -18,9 +18,13 @@
 //! [`EnsureRequirements`] optimizer rule that enforces distribution and
 //! sorting requirements together so that the two never invalidate each other.
 //!
-//! This rule replaces the separate `EnforceDistribution` + `EnforceSorting`
-//! rules with a unified approach inspired by Apache Spark's `EnsureRequirements`
-//! and Presto/Trino's `AddExchanges`.
+//! # Placement in the Optimizer Pipeline
+//!
+//! Unlike most optimizer rules, this rule modifies an unexecutable physical
+//! plan that does not satisfy distribution and ordering requirements into an
+//! *executable* one. A pipeline that omits this rule may produce a plan that
+//! is not runnable or that returns incorrect results. See the [Physical
+//! Optimizer](crate::optimizer) for details.
 //!
 //! # Motivation
 //!
@@ -161,10 +165,10 @@ use datafusion_physical_plan::ExecutionPlan;
 
 /// Optimizer rule that enforces both distribution and sorting requirements.
 ///
-/// This rule combines the functionality of `EnforceDistribution` and
-/// `EnforceSorting` into a coordinated sequence where distribution is
-/// always settled before sorting for each operator, preventing the
-/// non-idempotent interactions between the two separate rules.
+/// This rule inserts the repartitioning and sorting operators needed to
+/// satisfy the requirements that operators declare via
+/// [`ExecutionPlan::input_distribution_requirements`] and
+/// [`ExecutionPlan::required_input_ordering`].
 ///
 /// See [module level documentation](self) for more details.
 #[derive(Default, Debug)]


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org