From 525fdc2013fd675eeb26bed963cab142e76d8cb0 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Mon, 27 Apr 2026 07:08:25 -0400 Subject: [PATCH] Document difference between `ExecutionProps` and `TaskContext` more clearly --- datafusion/execution/src/task.rs | 16 ++++++++++++++++ datafusion/expr/src/execution_props.rs | 21 +++++++++++++++++++-- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/datafusion/execution/src/task.rs b/datafusion/execution/src/task.rs index 38f31cf4629eb..eadf3ea8ac487 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 3bf6978eb60ee..ff53dc495f5cf 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`,