This is an automated email from the ASF dual-hosted git repository.
comphead 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 2c56a3c2e5 Add docs explaining the relationship between `SessionState`
and `SessionContext` (#10350)
2c56a3c2e5 is described below
commit 2c56a3c2e5f2f6106b632072af0d1ce8f9d08784
Author: Andrew Lamb <[email protected]>
AuthorDate: Fri May 3 11:25:12 2024 -0400
Add docs explaining the relationship between `SessionState` and
`SessionContext` (#10350)
---
datafusion/core/src/execution/context/mod.rs | 33 +++++++++++++++++++---------
datafusion/execution/src/task.rs | 2 +-
2 files changed, 24 insertions(+), 11 deletions(-)
diff --git a/datafusion/core/src/execution/context/mod.rs
b/datafusion/core/src/execution/context/mod.rs
index d83644597e..d9efd1a037 100644
--- a/datafusion/core/src/execution/context/mod.rs
+++ b/datafusion/core/src/execution/context/mod.rs
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-//! [`SessionContext`] contains methods for registering data sources and
executing queries
+//! [`SessionContext`] API for registering data sources and executing queries
use std::collections::{hash_map::Entry, HashMap, HashSet};
use std::fmt::Debug;
@@ -216,17 +216,29 @@ where
///
/// # `SessionContext`, `SessionState`, and `TaskContext`
///
-/// A [`SessionContext`] can be created from a [`SessionConfig`] and
-/// stores the state for a particular query session. A single
-/// [`SessionContext`] can run multiple queries.
+/// The state required to optimize, and evaluate queries is
+/// broken into three levels to allow tailoring
///
-/// [`SessionState`] contains information available during query
-/// planning (creating [`LogicalPlan`]s and [`ExecutionPlan`]s).
+/// The objects are:
///
-/// [`TaskContext`] contains the state available during query
-/// execution [`ExecutionPlan::execute`]. It contains a subset of the
-/// information in[`SessionState`] and is created from a
-/// [`SessionContext`] or a [`SessionState`].
+/// 1. [`SessionContext`]: Most users should use a `SessionContext`. It
contains
+/// all information required to execute queries including high level APIs such
+/// as [`SessionContext::sql`]. All queries run with the same `SessionContext`
+/// share the same configuration and resources (e.g. memory limits).
+///
+/// 2. [`SessionState`]: contains information required to plan and execute an
+/// individual query (e.g. creating a [`LogicalPlan`] or [`ExecutionPlan`]).
+/// Each query is planned and executed using its own `SessionState`, which can
+/// be created with [`SessionContext::state`]. `SessionState` allows finer
+/// grained control over query execution, for example disallowing DDL
operations
+/// such as `CREATE TABLE`.
+///
+/// 3. [`TaskContext`] contains the state required for query execution (e.g.
+/// [`ExecutionPlan::execute`]). It contains a subset of information in
+/// [`SessionState`]. `TaskContext` allows executing [`ExecutionPlan`]s
+/// [`PhysicalExpr`]s without requiring a full [`SessionState`].
+///
+/// [`PhysicalExpr`]: crate::physical_expr::PhysicalExpr
#[derive(Clone)]
pub struct SessionContext {
/// UUID for the session
@@ -1320,6 +1332,7 @@ pub enum RegisterFunction {
/// Table user defined function
Table(String, Arc<dyn TableFunctionImpl>),
}
+
/// Execution context for registering data sources and executing queries.
/// See [`SessionContext`] for a higher level API.
///
diff --git a/datafusion/execution/src/task.rs b/datafusion/execution/src/task.rs
index 4216ce95f3..9370084a73 100644
--- a/datafusion/execution/src/task.rs
+++ b/datafusion/execution/src/task.rs
@@ -32,7 +32,7 @@ use crate::{
/// Task Execution Context
///
-/// A [`TaskContext`] contains the state available during a single
+/// A [`TaskContext`] contains the state required during a single
/// query's execution. Please see [`SessionContext`] for a user level
/// multi-query API.
///
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
