Skip to content

Apache DataFusion SQL Query Engine

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

Andrew Lambfbf77371a051
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)]