Skip to content

Commit a2ccc1a

Browse files
committed
Updating docs.
1 parent 3c9d8e4 commit a2ccc1a

2 files changed

Lines changed: 40 additions & 19 deletions

File tree

‎datafusion/physical-plan/src/execution_plan.rs‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -303,11 +303,11 @@ pub trait ExecutionPlan: Any + Debug + DisplayAs + Send + Sync {
303303
/// Reset any internal state within this [`ExecutionPlan`].
304304
///
305305
/// This method is called when an [`ExecutionPlan`] needs to be re-executed,
306-
/// such as in recursive queries. Unlike [`ExecutionPlan::with_new_children`], this method
306+
/// such as in recursive queries. Unlike [`ExecutionPlan::replace_children`], this method
307307
/// ensures that any stateful components (e.g., [`DynamicFilterPhysicalExpr`])
308308
/// are reset to their initial state.
309309
///
310-
/// The default implementation simply calls [`ExecutionPlan::with_new_children`] with the existing children,
310+
/// The default implementation simply calls [`ExecutionPlan::replace_children`] with the existing children,
311311
/// effectively creating a new instance of the [`ExecutionPlan`] with the same children but without
312312
/// necessarily resetting any internal state. Implementations that require resetting of some
313313
/// internal state should override this method to provide the necessary logic.
@@ -316,7 +316,7 @@ pub trait ExecutionPlan: Any + Debug + DisplayAs + Send + Sync {
316316
/// it will be called from within a walk of the execution plan tree so that it will be called on each child later
317317
/// or was already called on each child.
318318
///
319-
/// Note to implementers: unlike [`ExecutionPlan::with_new_children`] this method does not accept new children as an argument,
319+
/// Note to implementers: unlike [`ExecutionPlan::replace_children`] this method does not accept new children as an argument,
320320
/// thus it is expected that any cached plan properties will remain valid after the reset.
321321
///
322322
/// [`DynamicFilterPhysicalExpr`]: datafusion_physical_expr::expressions::DynamicFilterPhysicalExpr
@@ -1398,16 +1398,16 @@ pub fn need_data_exchange(plan: Arc<dyn ExecutionPlan>) -> bool {
13981398
///
13991399
/// 1. **Same child pointers** — if every `children[i]` is `Arc::ptr_eq` to the
14001400
/// corresponding existing child, the original `plan` is returned
1401-
/// unchanged (no allocation, no [`ExecutionPlan::with_new_children`]
1401+
/// unchanged (no allocation, no [`ExecutionPlan::replace_children`]
14021402
/// call).
14031403
/// 2. **Same child properties** — if the children's `PlanProperties` Arcs
14041404
/// match (via [`has_same_children_properties`]), the plan's own
14051405
/// `PlanProperties` cache can be reused. This calls
1406-
/// [`ExecutionPlan::with_new_children_and_same_properties`], which
1407-
/// swaps the child pointers without recomputing `PlanProperties`.
1406+
/// [`ExecutionPlan::replace_children`] with [`ChildrenPropertiesHint::SameProperties`],
1407+
/// which swaps the child pointers without recomputing `PlanProperties`.
14081408
/// 3. **Full recompute** — otherwise, delegate to
1409-
/// [`ExecutionPlan::with_new_children`], which recomputes
1410-
/// `PlanProperties` from scratch.
1409+
/// [`ExecutionPlan::replace_children`] with [`ChildrenPropertiesHint::Recompute`],
1410+
/// which recomputes `PlanProperties` from scratch.
14111411
///
14121412
/// The size of `children` must be equal to the size of `ExecutionPlan::children()`.
14131413
pub fn with_new_children_if_necessary(
@@ -1721,8 +1721,7 @@ macro_rules! check_if_same_properties {
17211721
/// child count.
17221722
///
17231723
/// This is useful for [`ExecutionPlan::replace_children`] implementations that
1724-
/// no longer call [`check_if_same_properties`] but still need to preserve the
1725-
/// same child-count validation behavior.
1724+
/// need to preserve the same child-count validation behavior.
17261725
#[macro_export]
17271726
macro_rules! validate_child_count {
17281727
($plan: expr, $children: expr) => {

‎docs/source/library-user-guide/custom-table-providers.md‎

Lines changed: 31 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -247,14 +247,22 @@ impl ExecutionPlan for MyExecPlan {
247247
vec![] // Leaf node -- no children
248248
}
249249
250-
fn with_new_children(
250+
fn replace_children(
251251
self: Arc<Self>,
252252
children: Vec<Arc<dyn ExecutionPlan>>,
253+
_: ChildrenPropertiesHint,
253254
) -> Result<Arc<dyn ExecutionPlan>> {
254255
assert!(children.is_empty());
255256
Ok(self)
256257
}
257258
259+
fn with_new_children(
260+
self: Arc<Self>,
261+
children: Vec<Arc<dyn ExecutionPlan>>,
262+
) -> Result<Arc<dyn ExecutionPlan>> {
263+
self.replace_children(children, ChildrenPropertiesHint::Recompute)
264+
}
265+
258266
fn execute(
259267
&self,
260268
partition: usize,
@@ -655,7 +663,7 @@ and reading files that cannot possibly match the query.
655663
# use datafusion::execution::context::TaskContext;
656664
# use datafusion::logical_expr::{Expr, TableProviderFilterPushDown};
657665
# use datafusion::physical_expr::EquivalenceProperties;
658-
# use datafusion::physical_plan::{DisplayAs, DisplayFormatType, ExecutionPlan, Partitioning, PhysicalExpr, PlanProperties};
666+
# use datafusion::physical_plan::{DisplayAs, DisplayFormatType, ExecutionPlan, Partitioning, PhysicalExpr, PlanProperties, ChildrenPropertiesHint};
659667
# use datafusion::physical_plan::execution_plan::{Boundedness, EmissionType};
660668
#
661669
/// A table provider backed by date-partitioned directories.
@@ -764,7 +772,15 @@ impl DatePartitionedTable {
764772
# fn name(&self) -> &str { "DatePartitionedExec" }
765773
# fn properties(&self) -> &Arc<PlanProperties> { &self.properties }
766774
# fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> { vec![] }
767-
# fn with_new_children(self: Arc<Self>, _: Vec<Arc<dyn ExecutionPlan>>) -> Result<Arc<dyn ExecutionPlan>> { Ok(self) }
775+
# fn replace_children(self: Arc<Self>, _: Vec<Arc<dyn ExecutionPlan>>, _: ChildrenPropertiesHint) -> Result<Arc<dyn ExecutionPlan>> { Ok(self) }
776+
#
777+
# fn with_new_children(
778+
# self: Arc<Self>,
779+
# children: Vec<Arc<dyn ExecutionPlan>>,
780+
# ) -> Result<Arc<dyn ExecutionPlan>> {
781+
# self.replace_children(children, ChildrenPropertiesHint::Recompute)
782+
# }
783+
#
768784
# fn execute(&self, _: usize, _: Arc<TaskContext>) -> Result<SendableRecordBatchStream> { todo!() }
769785
# }
770786
```
@@ -800,10 +816,8 @@ use datafusion::physical_expr::EquivalenceProperties;
800816
use datafusion::physical_plan::execution_plan::{Boundedness, EmissionType};
801817
use datafusion::physical_plan::stream::RecordBatchStreamAdapter;
802818
use datafusion::physical_plan::{
803-
# DisplayAs, DisplayFormatType,
804-
ExecutionPlan, Partitioning,
805-
# PhysicalExpr,
806-
PlanProperties,
819+
# DisplayAs, DisplayFormatType, PhysicalExpr,
820+
ChildrenPropertiesHint, ExecutionPlan, Partitioning, PlanProperties,
807821
};
808822
use futures::stream;
809823

@@ -873,13 +887,21 @@ impl ExecutionPlan for CountingExec {
873887
fn properties(&self) -> &Arc<PlanProperties> { &self.properties }
874888
fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> { vec![] }
875889

876-
fn with_new_children(
890+
fn replace_children(
877891
self: Arc<Self>,
878-
_children: Vec<Arc<dyn ExecutionPlan>>,
892+
_: Vec<Arc<dyn ExecutionPlan>>,
893+
_: ChildrenPropertiesHint,
879894
) -> Result<Arc<dyn ExecutionPlan>> {
880895
Ok(self)
881896
}
882897

898+
fn with_new_children(
899+
self: Arc<Self>,
900+
children: Vec<Arc<dyn ExecutionPlan>>,
901+
) -> Result<Arc<dyn ExecutionPlan>> {
902+
self.replace_children(children, ChildrenPropertiesHint::Recompute)
903+
}
904+
883905
fn execute(
884906
&self,
885907
partition: usize,

0 commit comments

Comments
 (0)