Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation on LogicalPlan TreeNode methods #10037

Merged
merged 1 commit into from
Apr 11, 2024
Merged

Improve documentation on LogicalPlan TreeNode methods #10037

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 35 additions & 12 deletions datafusion/expr/src/logical_plan/tree_node.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -451,7 +451,10 @@ macro_rules! handle_transform_recursion_up {
impl LogicalPlan {
/// Calls `f` on all expressions in the current `LogicalPlan` node.
///
/// Note this does not include expressions in child `LogicalPlan` nodes.
/// # Notes
/// * Similar to [`TreeNode::apply`] but for this node's expressions.
/// * Does not include expressions in input `LogicalPlan` nodes
/// * Visits only the top level expressions (Does not recurse into each expression)
pub fn apply_expressions<F: FnMut(&Expr) -> Result<TreeNodeRecursion>>(
&self,
mut f: F,
Expand Down Expand Up @@ -541,7 +544,9 @@ impl LogicalPlan {
///
/// Returns the current node.
///
/// Note this does not include expressions in child `LogicalPlan` nodes.
/// # Notes
/// * Similar to [`TreeNode::map_children`] but for this node's expressions.
/// * Visits only the top level expressions (Does not recurse into each expression)
pub fn map_expressions<F: FnMut(Expr) -> Result<Transformed<Expr>>>(
self,
mut f: F,
Expand Down Expand Up @@ -757,7 +762,8 @@ impl LogicalPlan {
})
}

/// Visits a plan similarly to [`Self::visit`], but including embedded subqueries.
/// Visits a plan similarly to [`Self::visit`], including subqueries that
/// may appear in expressions such as `IN (SELECT ...)`.
pub fn visit_with_subqueries<V: TreeNodeVisitor<Node = Self>>(
&self,
visitor: &mut V,
Expand All @@ -771,7 +777,9 @@ impl LogicalPlan {
.visit_parent(|| visitor.f_up(self))
}

/// Rewrites a plan similarly t [`Self::visit`], but including embedded subqueries.
/// Similarly to [`Self::rewrite`], rewrites this node and its inputs using `f`,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn rewrite_with_subqueries<R: TreeNodeRewriter<Node = Self>>(
self,
rewriter: &mut R,
Expand All @@ -783,10 +791,9 @@ impl LogicalPlan {
)
}

/// Calls `f` recursively on all children of the `LogicalPlan` node.
///
/// Unlike [`Self::apply`], this method *does* includes `LogicalPlan`s that
/// are referenced in `Expr`s
/// Similarly to [`Self::apply`], calls `f` on this node and all its inputs,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn apply_with_subqueries<F: FnMut(&Self) -> Result<TreeNodeRecursion>>(
&self,
f: &mut F,
Expand All @@ -796,20 +803,29 @@ impl LogicalPlan {
.visit_sibling(|| self.apply_children(|c| c.apply_with_subqueries(f)))
}

/// Similarly to [`Self::transform`], rewrites this node and its inputs using `f`,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn transform_with_subqueries<F: Fn(Self) -> Result<Transformed<Self>>>(
self,
f: &F,
) -> Result<Transformed<Self>> {
self.transform_up_with_subqueries(f)
}

/// Similarly to [`Self::transform_down`], rewrites this node and its inputs using `f`,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn transform_down_with_subqueries<F: Fn(Self) -> Result<Transformed<Self>>>(
self,
f: &F,
) -> Result<Transformed<Self>> {
handle_transform_recursion_down!(f(self), |c| c.transform_down_with_subqueries(f))
}

/// Similarly to [`Self::transform_down_mut`], rewrites this node and its inputs using `f`,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn transform_down_mut_with_subqueries<
F: FnMut(Self) -> Result<Transformed<Self>>,
>(
Expand All @@ -820,6 +836,9 @@ impl LogicalPlan {
.transform_down_mut_with_subqueries(f))
}

/// Similarly to [`Self::transform_up`], rewrites this node and its inputs using `f`,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn transform_up_with_subqueries<F: Fn(Self) -> Result<Transformed<Self>>>(
self,
f: &F,
Expand All @@ -836,6 +855,9 @@ impl LogicalPlan {
handle_transform_recursion_up!(self, |c| c.transform_up_mut_with_subqueries(f), f)
}

/// Similarly to [`Self::transform_down`], rewrites this node and its inputs using `f`,
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn transform_down_up_with_subqueries<
FD: FnMut(Self) -> Result<Transformed<Self>>,
FU: FnMut(Self) -> Result<Transformed<Self>>,
Expand All @@ -851,8 +873,9 @@ impl LogicalPlan {
)
}

/// Calls `f` on all subqueries referenced in expressions of the current
/// `LogicalPlan` node.
/// Similarly to [`Self::apply`], calls `f` on this node and its inputs
/// including subqueries that may appear in expressions such as `IN (SELECT
/// ...)`.
pub fn apply_subqueries<F: FnMut(&Self) -> Result<TreeNodeRecursion>>(
&self,
mut f: F,
Expand All @@ -872,8 +895,8 @@ impl LogicalPlan {
})
}

/// Rewrites all subquery `LogicalPlan` in the current `LogicalPlan` node
/// using `f`.
/// Similarly to [`Self::map_children`], rewrites all subqueries that may
/// appear in expressions such as `IN (SELECT ...)` using `f`.
///
/// Returns the current node.
pub fn map_subqueries<F: FnMut(Self) -> Result<Transformed<Self>>>(
Expand Down
Loading