Skip to content

Commit

Permalink
Add docs explaining the relationship between SessionState and `Sess…
Browse files Browse the repository at this point in the history
…ionContext` (apache#10350)
  • Loading branch information
alamb authored May 3, 2024
1 parent 6480020 commit 2c56a3c
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 11 deletions.
33 changes: 23 additions & 10 deletions datafusion/core/src/execution/context/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
///
Expand Down
2 changes: 1 addition & 1 deletion datafusion/execution/src/task.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand Down

0 comments on commit 2c56a3c

Please sign in to comment.