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/arrow-datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new f55c1d9021 Improve documentation on `LogicalPlan` TreeNode methods
(#10037)
f55c1d9021 is described below
commit f55c1d90215614ce531a4103c7dbebf318de1cfd
Author: Andrew Lamb <[email protected]>
AuthorDate: Thu Apr 11 10:59:44 2024 -0400
Improve documentation on `LogicalPlan` TreeNode methods (#10037)
---
datafusion/expr/src/logical_plan/tree_node.rs | 47 ++++++++++++++++++++-------
1 file changed, 35 insertions(+), 12 deletions(-)
diff --git a/datafusion/expr/src/logical_plan/tree_node.rs
b/datafusion/expr/src/logical_plan/tree_node.rs
index 1eb9d50277..3644f89e8b 100644
--- a/datafusion/expr/src/logical_plan/tree_node.rs
+++ b/datafusion/expr/src/logical_plan/tree_node.rs
@@ -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,
@@ -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,
@@ -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,
@@ -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,
@@ -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,
@@ -796,6 +803,9 @@ 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,
@@ -803,6 +813,9 @@ impl LogicalPlan {
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,
@@ -810,6 +823,9 @@ impl LogicalPlan {
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>>,
>(
@@ -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,
@@ -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>>,
@@ -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,
@@ -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>>>(
