From af20bac0a34f1d2bff4ad6cb3813d664a820d581 Mon Sep 17 00:00:00 2001 From: Connor Tsui Date: Thu, 30 Jan 2025 09:35:08 -0500 Subject: [PATCH] format and add docs for the plan module --- docs/src/architecture/glossary.md | 4 +-- optd-core/src/plan/logical_plan.rs | 6 ++++ optd-core/src/plan/partial_logical_plan.rs | 35 ++++++++++++++----- optd-core/src/plan/physical_plan.rs | 6 ++++ optd-core/src/plan/scalar_plan.rs | 6 +++- optd-core/src/rules/implementation/mod.rs | 2 +- .../rules/implementation/physical_filter.rs | 5 ++- .../transformation/join_associativity.rs | 4 +-- .../transformation/join_commutativity.rs | 4 +-- optd-core/src/rules/transformation/mod.rs | 2 +- 10 files changed, 55 insertions(+), 19 deletions(-) diff --git a/docs/src/architecture/glossary.md b/docs/src/architecture/glossary.md index 024dec2..9a5f855 100644 --- a/docs/src/architecture/glossary.md +++ b/docs/src/architecture/glossary.md @@ -126,7 +126,7 @@ See the following sections for more information. A logical expression is a version of a [Relational Expression]. -TODO(connor) Add more details. +TODO(connor): Add more details. Examples of logical expressions include Logical Scan, Logical Join, or Logical Sort expressions (which can just be shorthanded to Scan, Join, or Sort). @@ -135,7 +135,7 @@ Examples of logical expressions include Logical Scan, Logical Join, or Logical S A physical expression is a version of a [Relational Expression]. -TODO(connor) Add more details. +TODO(connor): Add more details. Examples of physical expressions include Table Scan, Index Scan, Hash Join, or Sort Merge Join. diff --git a/optd-core/src/plan/logical_plan.rs b/optd-core/src/plan/logical_plan.rs index 4ae6420..2a5aff8 100644 --- a/optd-core/src/plan/logical_plan.rs +++ b/optd-core/src/plan/logical_plan.rs @@ -1,5 +1,7 @@ //! This module contains the [`LogicalPlan`] type, which is the representation of a logical query //! plan from SQL. +//! +//! See the documentation for [`LogicalPlan`] for more information. use super::scalar_plan::ScalarPlan; use crate::operator::relational::logical::LogicalOperator; @@ -15,5 +17,9 @@ use std::sync::Arc; /// TODO(connor): add more docs. #[derive(Clone)] pub struct LogicalPlan { + /// Represents the current logical operator that is the root of the current subplan. + /// + /// Note that the children of the operator are other plans, which means that this data structure + /// is an in-memory DAG (directed acyclic graph) of logical operators. pub node: Arc>, } diff --git a/optd-core/src/plan/partial_logical_plan.rs b/optd-core/src/plan/partial_logical_plan.rs index d1ab57a..dbda1bd 100644 --- a/optd-core/src/plan/partial_logical_plan.rs +++ b/optd-core/src/plan/partial_logical_plan.rs @@ -1,11 +1,17 @@ -use crate::memo::GroupId; +//! This module contains the [`PartialLogicalPlan`] type, which is the representation of a partially +//! materialized logical query plan that is a mix of materialized logical operators and +//! unmaterialized group ID references to memo table groups of expressions. +//! +//! See the documentation for [`PartialLogicalPlan`] for more information. + +use crate::memo::{GroupId, ScalarGroupId}; use crate::operator::relational::logical::LogicalOperator; use crate::operator::scalar::ScalarOperator; use std::sync::Arc; /// A partially materialized logical query plan represented as a DAG (directed acyclic graph). /// -/// While a [`LogicalPlan`] contains fully materialized operator nodes, a `PartialLogicalPlan` +/// While a [`LogicalPlan`] contains fully materialized operator nodes, a [`PartialLogicalPlan`] /// can contain both materialized nodes and references to unmaterialized memo groups. This enables /// efficient plan exploration and transformation during query optimization. /// @@ -24,27 +30,38 @@ use std::sync::Arc; /// [`LogicalPlan`]: crate::plan::logical_plan::LogicalPlan #[derive(Clone)] pub struct PartialLogicalPlan { + /// Represents the current logical operator that is the root of the current partially + /// materialized subplan. + /// + /// Note that the children of the operator are either a [`Relation`] or a [`Scalar`], both of + /// which are defined in this module. See their documentation for more information. pub node: Arc>, } /// A link to a relational node in a [`PartialLogicalPlan`]. /// -/// Can be either: -/// - A materialized logical operator node -/// - A reference to an unmaterialized memo group +/// This link (which denotes what kind of relational children the operators of a +/// [`PartialLogicalPlan`] can have) can be either: +/// - A materialized logical operator node. +/// - A reference (identifier) to an unmaterialized memo group. #[derive(Clone)] pub enum Relation { + /// A materialized logical operator node. Operator(Arc>), + /// A reference (identifier) to an unmaterialized memo group. GroupId(GroupId), } /// A link to a scalar node in a [`PartialLogicalPlan`]. /// -/// Can be either: -/// - A materialized scalar operator node -/// - A reference to an unmaterialized memo group +/// This link (which denotes what kind of scalar children the operators of a [`PartialLogicalPlan`] +/// can have) can be either: +/// - A materialized scalar operator node. +/// - A reference to an unmaterialized memo group. #[derive(Clone)] pub enum Scalar { + /// A materialized scalar operator node. Operator(Arc>), - GroupId(GroupId), + /// A reference to an unmaterialized memo group. + ScalarGroupId(ScalarGroupId), } diff --git a/optd-core/src/plan/physical_plan.rs b/optd-core/src/plan/physical_plan.rs index 2d16954..bcb73f5 100644 --- a/optd-core/src/plan/physical_plan.rs +++ b/optd-core/src/plan/physical_plan.rs @@ -1,5 +1,7 @@ //! This module contains the [`PhysicalPlan`] type, which is the representation of a physical //! execution plan that can be sent to a query execution engine. +//! +//! See the documentation for [`PhysicalPlan`] for more information. use super::scalar_plan::ScalarPlan; use crate::operator::relational::physical::PhysicalOperator; @@ -15,5 +17,9 @@ use std::sync::Arc; /// TODO(connor): add more docs. #[derive(Clone)] pub struct PhysicalPlan { + /// Represents the current physical operator that is the root of the current subplan. + /// + /// Note that the children of the operator are other plans, which means that this data structure + /// is an in-memory DAG (directed acyclic graph) of physical operators. pub node: Arc>, } diff --git a/optd-core/src/plan/scalar_plan.rs b/optd-core/src/plan/scalar_plan.rs index c4cdc5b..f65c790 100644 --- a/optd-core/src/plan/scalar_plan.rs +++ b/optd-core/src/plan/scalar_plan.rs @@ -1,9 +1,13 @@ -use std::sync::Arc; +//! TODO(everyone): Figure out what exactly a `ScalarPlan` is (tree? DAG? always materialized?) use crate::operator::scalar::ScalarOperator; +use std::sync::Arc; /// A representation of a scalar query plan DAG (directed acyclic graph). #[derive(Clone)] pub struct ScalarPlan { + /// Represents the current scalar operator that is the root of the current scalar subtree. + /// + /// TODO(connor): Figure out if scalar plans can be a DAG pub node: Arc>, } diff --git a/optd-core/src/rules/implementation/mod.rs b/optd-core/src/rules/implementation/mod.rs index 22ee6ef..9e461a1 100644 --- a/optd-core/src/rules/implementation/mod.rs +++ b/optd-core/src/rules/implementation/mod.rs @@ -1,7 +1,7 @@ //! This module contains the implementation rule trait / API, as well as the rules that implement //! said trait. //! -//! TODO(connor) Add more docs. +//! TODO(connor): Add more docs. use crate::expression::{LogicalExpression, PhysicalExpression}; diff --git a/optd-core/src/rules/implementation/physical_filter.rs b/optd-core/src/rules/implementation/physical_filter.rs index 019e243..a169e24 100644 --- a/optd-core/src/rules/implementation/physical_filter.rs +++ b/optd-core/src/rules/implementation/physical_filter.rs @@ -19,6 +19,9 @@ impl ImplementationRule for PhysicalFilterRule { return None; }; - Some(PhysicalOperator::Filter(PhysicalFilter { child, predicate })) + Some(PhysicalOperator::Filter(PhysicalFilter { + child, + predicate, + })) } } diff --git a/optd-core/src/rules/transformation/join_associativity.rs b/optd-core/src/rules/transformation/join_associativity.rs index 3e6bf36..2e48be0 100644 --- a/optd-core/src/rules/transformation/join_associativity.rs +++ b/optd-core/src/rules/transformation/join_associativity.rs @@ -1,11 +1,11 @@ //! The rule for join associativity. -//! +//! //! See [`JoinAssociativityRule`] for more information. use super::*; /// A unit / marker struct for join associativity. -/// +/// /// Since joining is an associative operation, we can convert a `Join(Join(A, B), C)` into a /// `Join(A, Join(B, C))`. pub struct JoinAssociativityRule; diff --git a/optd-core/src/rules/transformation/join_commutativity.rs b/optd-core/src/rules/transformation/join_commutativity.rs index 2f78a18..959d6db 100644 --- a/optd-core/src/rules/transformation/join_commutativity.rs +++ b/optd-core/src/rules/transformation/join_commutativity.rs @@ -1,11 +1,11 @@ //! The rule for join commutativity. -//! +//! //! See [`JoinCommutativityRule`] for more information. use super::*; /// A unit / marker struct for join commutativity. -/// +/// /// Since joining is an commutative operation, we can convert a `Join(A, B)` into a `Join(B, C)`. pub struct JoinCommutativityRule; diff --git a/optd-core/src/rules/transformation/mod.rs b/optd-core/src/rules/transformation/mod.rs index fee2d9f..3152e94 100644 --- a/optd-core/src/rules/transformation/mod.rs +++ b/optd-core/src/rules/transformation/mod.rs @@ -33,7 +33,7 @@ pub trait TransformationRule { /// /// These changes can create new logical or scalar expressions. However, note that /// transformation rules will _not_ create new physical expressions. - /// + /// /// TODO(everyone) Figure out what the return type should really be. fn apply(&self, expr: PartialLogicalPlan) -> PartialLogicalPlan; }