rename

Author: adriangb

datafusion/expr-common/src/placement.rs

@@ -29,22 +29,26 @@ pub enum ExpressionPlacement {
     Column,
     /// A cheap expression that can be pushed to leaf nodes in the plan.
     /// Examples include `get_field` for struct field access.
-    PlaceAtLeaves,
-    /// An expensive expression that should stay at the root of the plan.
-    /// This is the default for most expressions.
-    PlaceAtRoot,
+    /// Pushing these expressions down in the plan can reduce data early
+    /// at low compute cost.
+    /// See [`ExpressionPlacement::should_push_to_leaves`] for details.
+    MoveTowardsLeafNodes,
+    /// An expensive expression that should stay where it is in the plan
+    /// or possibly be moved closer to the root nodes (this is not implemented yet).
+    /// Examples include complex scalar functions or UDFs.
+    MoveTowardsRootNodes,
 }
 
 impl ExpressionPlacement {
     /// Returns true if the expression can be pushed down to leaf nodes
     /// in the query plan.
     ///
     /// This returns true for:
-    /// - `Column`: Simple column references can be pushed down. They do no compute and do not increase or
+    /// - [`ExpressionPlacement::Column`]: Simple column references can be pushed down. They do no compute and do not increase or
     ///   decrease the amount of data being processed.
     ///   A projection that reduces the number of columns can eliminate unnecessary data early,
     ///   but this method only considers one expression at a time, not a projection as a whole.
-    /// - `PlaceAtLeaves`: Cheap expressions can be pushed down to leaves to take advantage of
+    /// - [`ExpressionPlacement::MoveTowardsLeafNodes`]: Cheap expressions can be pushed down to leaves to take advantage of
     ///   early computation and potential optimizations at the data source level.
     ///   For example `struct_col['field']` is cheap to compute (just an Arc clone of the nested array for `'field'`)
     ///   and thus can reduce data early in the plan at very low compute cost.
@@ -53,7 +57,7 @@ impl ExpressionPlacement {
     pub fn should_push_to_leaves(&self) -> bool {
         matches!(
             self,
-            ExpressionPlacement::Column | ExpressionPlacement::PlaceAtLeaves
+            ExpressionPlacement::Column | ExpressionPlacement::MoveTowardsLeafNodes
         )
     }
 }

datafusion/expr/src/expr.rs

@@ -1550,7 +1550,7 @@ impl Expr {
                     func.args.iter().map(|arg| arg.placement()).collect();
                 func.func.placement(&arg_placements)
             }
-            _ => ExpressionPlacement::PlaceAtRoot,
+            _ => ExpressionPlacement::MoveTowardsRootNodes,
         }
     }
 

datafusion/expr/src/udf.rs

@@ -978,13 +978,13 @@ pub trait ScalarUDFImpl: Debug + DynEq + DynHash + Send + Sync {
     /// This is used by optimizers to make decisions about expression placement,
     /// such as whether to push expressions down through projections.
     ///
-    /// The default implementation returns [`ExpressionPlacement::PlaceAtRoot`],
+    /// The default implementation returns [`ExpressionPlacement::MoveTowardsRootNodes`],
     /// meaning the expression should stay at the root of the plan.
     ///
     /// Override this method to indicate that the function can be pushed down
     /// closer to the data source.
     fn placement(&self, _args: &[ExpressionPlacement]) -> ExpressionPlacement {
-        ExpressionPlacement::PlaceAtRoot
+        ExpressionPlacement::MoveTowardsRootNodes
     }
 }
 

datafusion/functions/src/core/getfield.rs

@@ -505,13 +505,13 @@ impl ScalarUDFImpl for GetFieldFunc {
         // 1. The base (first arg) is a column or already placeable at leaves
         // 2. All field keys (remaining args) are literals
         if args.is_empty() {
-            return ExpressionPlacement::PlaceAtRoot;
+            return ExpressionPlacement::MoveTowardsRootNodes;
         }
 
         let base_placement = args[0];
         let base_is_pushable = matches!(
             base_placement,
-            ExpressionPlacement::Column | ExpressionPlacement::PlaceAtLeaves
+            ExpressionPlacement::Column | ExpressionPlacement::MoveTowardsLeafNodes
         );
 
         let all_keys_are_literals = args
@@ -520,9 +520,9 @@ impl ScalarUDFImpl for GetFieldFunc {
             .all(|p| matches!(p, ExpressionPlacement::Literal));
 
         if base_is_pushable && all_keys_are_literals {
-            ExpressionPlacement::PlaceAtLeaves
+            ExpressionPlacement::MoveTowardsLeafNodes
         } else {
-            ExpressionPlacement::PlaceAtRoot
+            ExpressionPlacement::MoveTowardsRootNodes
         }
     }
 }
@@ -575,22 +575,31 @@ mod tests {
 
         // get_field(col, 'literal') -> leaf-pushable (static field access)
         let args = vec![ExpressionPlacement::Column, ExpressionPlacement::Literal];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtLeaves);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsLeafNodes
+        );
 
         // get_field(col, 'a', 'b') -> leaf-pushable (nested static field access)
         let args = vec![
             ExpressionPlacement::Column,
             ExpressionPlacement::Literal,
             ExpressionPlacement::Literal,
         ];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtLeaves);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsLeafNodes
+        );
 
-        // get_field(get_field(col, 'a'), 'b') represented as PlaceAtLeaves for base
+        // get_field(get_field(col, 'a'), 'b') represented as MoveTowardsLeafNodes for base
         let args = vec![
-            ExpressionPlacement::PlaceAtLeaves,
+            ExpressionPlacement::MoveTowardsLeafNodes,
             ExpressionPlacement::Literal,
         ];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtLeaves);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsLeafNodes
+        );
     }
 
     #[test]
@@ -599,15 +608,21 @@ mod tests {
 
         // get_field(col, other_col) -> NOT leaf-pushable (dynamic per-row lookup)
         let args = vec![ExpressionPlacement::Column, ExpressionPlacement::Column];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtRoot);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsRootNodes
+        );
 
         // get_field(col, 'a', other_col) -> NOT leaf-pushable (dynamic nested lookup)
         let args = vec![
             ExpressionPlacement::Column,
             ExpressionPlacement::Literal,
             ExpressionPlacement::Column,
         ];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtRoot);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsRootNodes
+        );
     }
 
     #[test]
@@ -616,32 +631,47 @@ mod tests {
 
         // get_field(root_expr, 'literal') -> NOT leaf-pushable
         let args = vec![
-            ExpressionPlacement::PlaceAtRoot,
+            ExpressionPlacement::MoveTowardsRootNodes,
             ExpressionPlacement::Literal,
         ];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtRoot);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsRootNodes
+        );
 
         // get_field(col, root_expr) -> NOT leaf-pushable
         let args = vec![
             ExpressionPlacement::Column,
-            ExpressionPlacement::PlaceAtRoot,
+            ExpressionPlacement::MoveTowardsRootNodes,
         ];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtRoot);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsRootNodes
+        );
     }
 
     #[test]
     fn test_placement_edge_cases() {
         let func = GetFieldFunc::new();
 
         // Empty args -> NOT leaf-pushable
-        assert_eq!(func.placement(&[]), ExpressionPlacement::PlaceAtRoot);
+        assert_eq!(
+            func.placement(&[]),
+            ExpressionPlacement::MoveTowardsRootNodes
+        );
 
-        // Just base, no key -> PlaceAtLeaves (not a valid call but should handle gracefully)
+        // Just base, no key -> MoveTowardsLeafNodes (not a valid call but should handle gracefully)
         let args = vec![ExpressionPlacement::Column];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtLeaves);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsLeafNodes
+        );
 
         // Literal base with literal key -> NOT leaf-pushable (would be constant-folded)
         let args = vec![ExpressionPlacement::Literal, ExpressionPlacement::Literal];
-        assert_eq!(func.placement(&args), ExpressionPlacement::PlaceAtRoot);
+        assert_eq!(
+            func.placement(&args),
+            ExpressionPlacement::MoveTowardsRootNodes
+        );
     }
 }

datafusion/optimizer/src/optimize_projections/mod.rs

@@ -525,7 +525,7 @@ fn merge_consecutive_projections(proj: Projection) -> Result<Transformed<Project
     expr.iter()
         .for_each(|expr| expr.add_column_ref_counts(&mut column_referral_map));
 
-    // If an expression is non-trivial (PlaceAtRoot) and appears more than once, do not merge
+    // If an expression is non-trivial (MoveTowardsRootNodes) and appears more than once, do not merge
     // them as consecutive projections will benefit from a compute-once approach.
     // For details, see: https://github.com/apache/datafusion/issues/8296
     if column_referral_map.into_iter().any(|(col, usage)| {

datafusion/physical-expr-common/src/physical_expr.rs

@@ -437,9 +437,9 @@ pub trait PhysicalExpr: Any + Send + Sync + Display + Debug + DynEq + DynHash {
     /// This is used by optimizers to make decisions about expression placement,
     /// such as whether to push expressions down through projections.
     ///
-    /// The default implementation returns [`ExpressionPlacement::PlaceAtRoot`].
+    /// The default implementation returns [`ExpressionPlacement::MoveTowardsRootNodes`].
     fn placement(&self) -> ExpressionPlacement {
-        ExpressionPlacement::PlaceAtRoot
+        ExpressionPlacement::MoveTowardsRootNodes
     }
 }
 

datafusion/physical-plan/src/projection.rs

@@ -288,7 +288,7 @@ impl ExecutionPlan for ProjectionExec {
                 .all(|proj_expr| {
                     !matches!(
                         proj_expr.expr.placement(),
-                        ExpressionPlacement::PlaceAtRoot
+                        ExpressionPlacement::MoveTowardsRootNodes
                     )
                 });
         // If expressions are all either column_expr or Literal (or other cheap expressions),
@@ -1007,7 +1007,7 @@ fn try_unifying_projections(
             .unwrap();
     });
     // Merging these projections is not beneficial, e.g
-    // If an expression is not trivial (PlaceAtRoot) and it is referred more than 1, unifies projections will be
+    // If an expression is not trivial (MoveTowardsRootNodes) and it is referred more than 1, unifies projections will be
     // beneficial as caching mechanism for non-trivial computations.
     // See discussion in: https://github.com/apache/datafusion/issues/8296
     if column_ref_map.iter().any(|(column, count)| {