Skip to content

Apache DataFusion SQL Query Engine

docs: clarify ExecutionProps and TaskContext docs (#21872)

Andrew Lambbff0ffb682e7
diff --git a/datafusion/execution/src/task.rs b/datafusion/execution/src/task.rs
index 38f31cf462..eadf3ea8ac 100644
--- a/datafusion/execution/src/task.rs
+++ b/datafusion/execution/src/task.rs
@@ -31,7 +31,23 @@ use std::{collections::HashMap, sync::Arc};
/// execution. Please see the documentation on [`SessionContext`] for more
/// information.
///
+/// # Relationship with [`ExecutionProps`]
+///
+/// [`TaskContext`] is intentionally distinct from [`ExecutionProps`].
+/// [`ExecutionProps`] is state used while optimizing a logical
+/// plan and constructing a physical plan.
+///
+/// [`TaskContext`] is the runtime context passed to physical operators when
+/// executing a physical plan. It carries runtime services and session state
+/// needed at that stage, such as [`RuntimeEnv`], memory-pool access, session
+/// configuration, and function lookup.
+///
+/// Keeping these structures separate avoids threading execution/runtime state
+/// through planning APIs, and avoids making execution depend on planner-only
+/// scratch state.
+///
/// [`SessionContext`]: https://docs.rs/datafusion/latest/datafusion/execution/context/struct.SessionContext.html
+/// [`ExecutionProps`]: datafusion_expr::execution_props::ExecutionProps
#[derive(Debug)]
pub struct TaskContext {
/// Session Id
diff --git a/datafusion/expr/src/execution_props.rs b/datafusion/expr/src/execution_props.rs
index 3bf6978eb6..ff53dc495f 100644
--- a/datafusion/expr/src/execution_props.rs
+++ b/datafusion/expr/src/execution_props.rs
@@ -22,8 +22,9 @@ use datafusion_common::alias::AliasGenerator;
use datafusion_common::config::ConfigOptions;
use std::sync::Arc;
-/// Holds per-query execution properties and data (such as statement
-/// starting timestamps).
+/// Holds properties and scratch state used while optimizing a [`LogicalPlan`]
+/// and translating it into an executable physical plan, such as the statement
+/// start time used during simplification.
///
/// An [`ExecutionProps`] is created each time a `LogicalPlan` is
/// prepared for execution (optimized). If the same plan is optimized
@@ -31,6 +32,22 @@ use std::sync::Arc;
///
/// It is important that this structure be cheap to create as it is
/// done so during predicate pruning and expression simplification
+///
+/// # Relationship with [`TaskContext`]
+///
+/// [`ExecutionProps`] is intentionally distinct from [`TaskContext`].
+/// It is used while optimizing a logical plan and constructing physical
+/// expressions and physical plans, before physical operators are run.
+///
+/// [`TaskContext`] is the runtime context passed to physical operators during
+/// physical-plan execution.
+///
+/// Keeping these structures separate avoids threading execution/runtime state
+/// through planning APIs, and avoids making execution depend on planner-only
+/// scratch state.
+///
+/// [`TaskContext`]: https://docs.rs/datafusion/latest/datafusion/execution/struct.TaskContext.html
+/// [`LogicalPlan`]: crate::LogicalPlan
#[derive(Clone, Debug)]
pub struct ExecutionProps {
/// The time at which the query execution started. If `None`,