Rust on Opensource internals

DataFusion Rewrites Its Plan Trees In Place: Arc::make_mut and the End of the Clone-Collect-Rebuild Cycle

Jay Hubbert — Wed, 21 Oct 2026 06:29:00 +0000

TL;DR: TreeNode::rewrite is a lovely API and a bad fit for an optimizer that runs 26 rules over a plan tree. Every rule that says “no change” still pays for a full clone-and-rebuild of the tree, because the ownership-based API cannot know in advance whether a node will change. DataFusion added a second, in-place traversal built on Arc::make_mut: if nobody else shares a node, it is mutated for free; if they do, it is cloned exactly once. On top of that, the optimizer checks whether the plan contains any subqueries and, if not, uses a much cheaper traversal that does not need to visit expression subtrees at all.

Query optimizers are tree rewriters. You have a plan, you have a rule, the rule looks at a node and maybe replaces it. The naive Rust implementation of “maybe replaces it” is awkward, because the rule needs an owned node to return an owned node, and the tree is a graph of Arcs.

DataFusion’s TreeNode trait solves this with a consuming rewrite:

 rust
 
 
fn rewrite_with_subqueries(
 &self,
 _f: &mut dyn FnMut(&LogicalPlan) -> Result<Transformed<LogicalPlan>>,
) -> Result<Transformed<LogicalPlan>>;

The rule gets an owned LogicalPlan, returns a Transformed<LogicalPlan>, and the framework rebuilds the tree around it. It is clean, and it is expensive: every node that a rule inspects and declines to change is still cloned, because the rewrite has to produce a new owned tree to reassemble.

With 26 rules and a plan of a few dozen nodes, that is a lot of churn — and the churn is proportional to the size of the plan, not to the amount of actual rewriting.

The in-place traversal

datafusion/optimizer/src/optimizer.rs contains a second traversal written specifically for the optimizer:

 rust
 
 
/// Rewrites a plan tree in place using `Arc::make_mut` for
/// copy-on-write semantics on `Arc<LogicalPlan>` children.
///
/// This avoids the `Arc::unwrap_or_clone` + `Arc::new` cycle that the
/// ownership-based `TreeNode::rewrite` performs at every child node.
#[cfg_attr(feature = "recursive_protection", recursive::recursive)]
fn rewrite_plan_in_place(
 plan: &mut LogicalPlan,
 apply_order: ApplyOrder,
 rule: &dyn OptimizerRule,
 config: &dyn OptimizerConfig,
) -> Result<bool> {

Arc::make_mut is the whole trick. If the Arc has refcount 1, it hands out a &mut to the value with zero cost. If the refcount is greater than one, it clones the value once and hands out a mutable reference to the clone. Either way the caller gets a mutable slot and never has to write the match Arc::try_unwrap dance by hand.

The children accessor is a big match over the plan enum, and each arm is one line:

 rust
 
 
fn map_children_mut<F: FnMut(&mut LogicalPlan) -> Result<bool>>(
 plan: &mut LogicalPlan,
 mut f: F,
) -> Result<bool> {
 Ok(match plan {
 LogicalPlan::Projection(Projection { input, .. })
 | LogicalPlan::Filter(Filter { input, .. })
 | LogicalPlan::Repartition(Repartition { input, .. })
 | LogicalPlan::Window(Window { input, .. })
 | LogicalPlan::Aggregate(Aggregate { input, .. })
 | LogicalPlan::Sort(Sort { input, .. })
 | LogicalPlan::Limit(Limit { input, .. })
 | LogicalPlan::SubqueryAlias(SubqueryAlias { input, .. })
 ...
 => f(Arc::make_mut(input))?,
 LogicalPlan::Join(Join { left, right, .. }) => {
 let l = f(Arc::make_mut(left))?;
 let r = f(Arc::make_mut(right))?;
 l || r
 }
 ...
 })
}

The f callback returns bool — “did you change this child?” — and the match combines them with ||. The whole tree walk returns a single bool saying whether anything changed, which is exactly the signal the optimizer needs to know whether to run another pass.

Bridging `&mut` to owned

There is a wrinkle. The OptimizerRule trait is defined in terms of owned plans:

 rust
 
 
fn rewrite(&self, plan: LogicalPlan, config: &dyn OptimizerConfig)
 -> Result<Transformed<LogicalPlan>>;

The rule consumes the plan and returns a new one. To call it through a &mut LogicalPlan, the in-place traversal has to bridge the two, and the way it does it is a small piece of care:

 rust
 
 
// f_down phase
let mut changed = false;
if apply_order == ApplyOrder::TopDown {
 // `rule.rewrite()` takes the plan by value, so bridge the `&mut` to an
 // owned value with `std::mem::take`. `LogicalPlan::default()` is a cheap
 // empty placeholder (shared empty schema, no allocation) and is
 // overwritten with the rule's output on the next line.
 let owned = std::mem::take(plan);
 let result = rule.rewrite(owned, config)?;
 *plan = result.data;
 changed |= result.transformed;
 ...
}

std::mem::take(plan) moves the plan out, leaving LogicalPlan::default() behind. default() is documented as cheap — a shared empty schema, no allocation — so the placeholder costs nothing. The ? on the rule’s result is safe because the placeholder is still a valid (if useless) plan, so an early return leaves the tree in a well-defined state rather than with a dangling hole.

The same trick appears in datafusion/common/src/tree_node.rs, at the container level:

 rust
 
 
fn map_elements<F: FnMut(T) -> Result<Transformed<T>>>(
 mut self,
 f: F,
) -> Result<Transformed<Self>> {
 // Rewrite in place so the existing heap allocation can be reused.
 // `mem::take` hands the inner `C` to `f` while leaving
 // `C::default()` in the slot, so an unwinding drop finds a valid
 // `C` even if `f` panics or the `?` short-circuits.
 let inner = std::mem::take(&mut *self);
 Ok(inner.map_elements(f)?.update_data(|c| {
 *self = c;
 self
 }))
}

The comment is the interesting part: “an unwinding drop finds a valid C even if f panics or the ? short-circuits”. This is panic-safety by construction. If f panics halfway, the Box/Arc slot contains C::default() rather than a partially-initialised value, so the drop glue does the right thing. Rust’s “leave a valid value in place of what you took” pattern is usually discussed as a way to avoid Option; here it is used as a panic guard.

The Arc version adds the CoW step:

 rust
 
 
fn map_elements<F: FnMut(T) -> Result<Transformed<T>>>(
 mut self,
 f: F,
) -> Result<Transformed<Self>> {
 // Rewrite in place using the same `mem::take` strategy as
 // `Box<C>::map_elements`. `Arc::make_mut` gives us exclusive
 // access (cloning `C` first if we were sharing), after which
 // `get_mut` is infallible.
 let inner = std::mem::take(Arc::make_mut(&mut self));
 Ok(inner.map_elements(f)?.update_data(|c| {
 *Arc::get_mut(&mut self).unwrap() = c;
 self
 }))
}

Note Arc::get_mut(&mut self).unwrap() — infallible because make_mut guaranteed exclusivity.

The subquery fast path

The in-place traversal is not the only optimisation. The optimizer decides which traversal to use based on whether the plan contains subqueries:

 rust
 
 
let result = match rule.apply_order() {
 Some(apply_order) => {
 if has_subqueries {
 // Plans with subqueries need the full
 // rewrite_with_subqueries traversal to
 // recurse into subquery plans.
 new_plan.rewrite_with_subqueries(...)
 } else {
 // No subqueries: use in-place rewriting
 // with Arc::make_mut for zero-cost CoW on
 // children, avoiding Arc unwrap/rewrap.
 rewrite_plan_in_place(...)
 }
 }
 None => rule.rewrite(new_plan, config),
}

and the predicate is computed by a dedicated traversal:

 rust
 
 
/// Returns true if the plan contains any subquery expressions
/// (EXISTS, IN subquery, scalar subquery, set comparison).
///
/// Used to determine whether the more expensive `rewrite_with_subqueries`
/// traversal is needed. When the plan has no subqueries, the cheaper
/// `rewrite` traversal is sufficient since all plan nodes are reachable
/// via direct children.
fn plan_has_subqueries(plan: &LogicalPlan) -> bool {

The reason is structural. rewrite_with_subqueries has to walk inside every expression looking for Expr::Exists, Expr::InSubquery, Expr::SetComparison and Expr::ScalarSubquery, each of which carries a nested LogicalPlan. A plan with no subqueries has no such nested plans, so the ordinary child-only traversal reaches everything.

And the check is re-done during the pass, not just once:

 rust
 
 
if transformed {
 has_subqueries = plan_has_subqueries(&new_plan);
 log_plan(rule.name(), &new_plan);
}

Because a rule such as ScalarSubqueryToJoin can introduce subqueries (well, remove them) or change their shape. The comment in the optimizer explains:

Track subquery presence across the pass. Refresh after changed rules so decorrelation can move later rules onto the in-place path; that path refreshes parent schemas after child schemas change.

Note that the refresh only happens when a rule actually changed something (if transformed). An unchanged plan cannot have changed its subquery content, so the re-check would be pure waste.

The catch

Arc::make_mut is only free if nobody else holds a reference. If a plan node is shared (a CTE used twice, a cached plan, a plan held by an Arc in the session state), the first mutation clones it. That clone is a deep clone of the node’s contents but a shallow clone of its children — which is exactly the right granularity.
The error semantics are different, and the code says so. The in-place traversal documents:

On Err, *plan is left in an unspecified state and must not be used. Note this is different than consuming APIs such as TreeNode::rewrite where the original plan is freed and no longer available on error

The optimizer handles this by cloning the plan before each rule when skip_failed_rules is enabled:
rust
```
let prev_plan = options
 .optimizer
 .skip_failed_rules
 .then(|| new_plan.clone());
```
Note this clone is only paid when the option is on — the default path does not clone at all, because in-place rewriting leaves the plan recoverable in the normal case.
The Arc::make_mut approach does not generalise. The source is candid:

the Arc::make_mut approach does not generalize to the other tree types (Expr children are Boxed; PhysicalExpr/ExecutionPlan children are Arc<dyn _>, which Arc::make_mut cannot handle)

Arc::make_mut requires a concrete T, not a trait object. So the in-place trick works for LogicalPlan and not for the physical plan tree. That is a genuine limit of the technique, and the code documents it rather than pretending otherwise.
The map_children_mut match must be kept in sync with the enum. Adding a new LogicalPlan variant without adding an arm is a compile-time error only because the match is exhaustive — a good property, but it is the only thing keeping this correct.

Why it matters

Optimisation time is not free. A DataFusion deployment serving short interactive queries pays the optimiser cost on every request. The difference between “clone the plan 26 times” and “mutate the plan in place” is the difference between an optimiser that shows up in a latency histogram and one that does not.

And the same reasoning scales up: the physical planner, the rule engine, and the proto serialisation layer all have the same shape of problem, and each has grown its own local solution. The in-place traversal is the generalised version of that idea, applied where it pays the most.

How DataFusion Knows the Optimizer Has Stopped Improving: A Hash, a Node Count, and a Set of Previous Plans

Jay Hubbert — Wed, 21 Oct 2026 01:33:00 +0000

TL;DR: Optimizer rules can undo each other. PushDownFilter can push a predicate down, and another rule can pull it back up, and if the optimizer just kept looping it would never terminate. DataFusion runs rules in passes and stops when a pass produces a plan it has already seen. The “already seen” test is a LogicalPlanSignature — the plan’s node count plus a hash of its contents — and the seen-plans are kept in a HashSet that grows with each pass.

Termination is the boring half of fixed-point optimization, and it is where most optimizer implementations get sloppy.

The naive approach is a pass counter: “run at most N passes”. That works, but it means every query pays N passes even if the second one changed nothing. And a plan that oscillates between two shapes will happily burn all N passes producing the same answer.

DataFusion’s approach is better: it detects the fixed point.

The loop

The optimizer driver is Optimizer::optimize (datafusion/optimizer/src/optimizer.rs):

 rust
 
 
let mut previous_plans = HashSet::with_capacity(16);
previous_plans.insert(LogicalPlanSignature::new(&new_plan));

let starting_schema = Arc::clone(new_plan.schema());

let mut i = 0;
while i < options.optimizer.max_passes {
 ...
 for rule in &self.rules {
 ...
 }
 log_plan(&format!("Optimized plan (pass {i})"), &new_plan);

 // HashSet::insert returns, whether the value was newly inserted.
 let plan_is_fresh =
 previous_plans.insert(LogicalPlanSignature::new(&new_plan));
 if !plan_is_fresh {
 // plan did not change, so no need to continue trying to optimize
 debug!("optimizer pass {i} did not make changes");
 break;
 }
 i += 1;
}

Two mechanisms, deliberately separate:

max_passes is the hard cap — a safety net. If the rules somehow keep producing genuinely new plans forever, the optimizer gives up.
The previous_plans set is the early exit — the normal case.

The HashSet::with_capacity(16) is a small but revealing detail: the authors expect a typical query to reach its fixed point in a handful of passes, and pre-allocating 16 slots avoids rehashing during the first passes.

The insert returning false means “we have seen this exact plan before”. Note that this is not the same as “the plan is unchanged since the last pass” — it is “the plan is unchanged since any previous pass”, which is exactly what you want for cycle detection. Two rules that push a predicate down and pull it back up produce plan A, plan B, plan A — and the third pass is caught immediately rather than after max_passes iterations.

The signature

LogicalPlanSignature (datafusion/optimizer/src/plan_signature.rs) is the identity used for that comparison:

 rust
 
 
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct LogicalPlanSignature {
 node_number: NonZeroUsize,
 plan_hash: u64,
}

Two components. The node count is obtained by a traversal:

 rust
 
 
/// Get total number of [`LogicalPlan`]s in the plan.
fn get_node_number(plan: &LogicalPlan) -> NonZeroUsize {
 let mut node_number = 0;
 plan.apply_with_subqueries(|_plan| {
 node_number += 1;
 Ok(TreeNodeRecursion::Continue)
 })
 // Closure always return Ok
 .unwrap();
 // Visitor must have at least visited the root,
 // so v.node_number is at least 1.
 NonZeroUsize::new(node_number).unwrap()
}

and the hash is the plan’s own Hash implementation:

 rust
 
 
pub fn new(plan: &LogicalPlan) -> Self {
 let mut hasher = DefaultHasher::new();
 plan.hash(&mut hasher);

 Self {
 node_number: get_node_number(plan),
 plan_hash: hasher.finish(),
 }
}

The node count is a cheap, structural discriminator that makes hash collisions vanishingly unlikely: two plans with different node counts cannot be confused, so a collision requires two plans with the same node count and the same 64-bit hash.

The doc comment is careful about the guarantees:

If p1 and p2 have a different number of LogicalPlans, then they will have different LogicalPlanSignatures.

If p1 and p2 have a different Hash, then they will have different LogicalPlanSignatures.

Caveats

The intention of LogicalPlanSignature is to have a lower chance of hash collisions.

There exist different LogicalPlans with the same LogicalPlanSignature.

When two LogicalPlans differ only in metadata, then they will have the same LogicalPlanSignatures (due to hash implementation in LogicalPlan).

That last caveat is worth dwelling on. The signature is a heuristic identity, not a true one. Two different plans that differ only in metadata hash the same and have the same node count, so they share a signature. The consequence is benign in this context: the optimizer will stop one pass earlier than it theoretically could. The alternative — a true structural equality — would require comparing every node of every plan on every pass, which is exactly the cost this design is trying to avoid.

Why not just compare the plans?

Because comparing two LogicalPlans structurally is O(size of plan), and the optimizer does it after every pass. For a plan of a few dozen nodes that is not free, but it is not free repeatedly either.

The hash is computed with DefaultHasher, which is SipHash-1-3 — a seeded hasher whose seed is fixed per-process (zero-initialised DefaultHasher). That gives a strong guarantee against adversarial collisions for hash-map use, and it is fast enough for a plan-sized input.

The traversal for the node count is a second walk of the plan, on top of the hash. That sounds wasteful, but the hash itself has to walk the tree anyway, and the count is a counter increment in the same closure shape. Two walks of a 50-node tree is microseconds.

Actually — it is not the same walk. get_node_number uses apply_with_subqueries, which visits nested plans inside expressions. The hash walks the plan’s own Hash implementation. They are different traversals, but both are O(plan size), and both are dwarfed by the 26 rule rewrites that follow.

The cap

max_passes is a config option:

 rust
 
 
pub fn with_max_passes(mut self, v: u8) -> Self {
 Arc::make_mut(&mut self.options).optimizer.max_passes = v as usize;
 self
}

The default is a small number (three, in the shipped configuration), which tells you how much the DataFusion developers trust the fixed-point detection to do the real work. If the detection were unreliable, the cap would need to be large enough to cover the worst case; a small default means the detection is expected to fire quickly.

There is even a test for the pathological case — a rule that rotates a projection, which is a classic way to make an optimizer oscillate:

 rust
 
 
fn optimizer_detects_plan_equal_to_the_initial() -> Result<()> {
 let opt = Optimizer::with_rules(vec![Arc::new(RotateProjectionRule::new(false))]);
 let config = OptimizerContext::new().with_max_passes(16);
 ...

Note with_max_passes(16) in the test: the test gives the optimizer a generous cap precisely so that it is the detection that terminates the loop, not the cap. If the detection were broken, the test would run 16 passes instead of 2 and the assertions would catch it.

The catch

A hash collision terminates the optimizer early. The probability with a 64-bit hash is negligible, but it is not zero, and the failure mode is silent: you get a slightly less-optimised plan, not an error.
Metadata-only differences are invisible. Two plans that differ only in metadata are considered “the same plan”. This is documented, and the consequences are mild.
The previous_plans set grows with the number of passes. It is bounded by max_passes, so it is bounded by a small constant, but it is not free: each pass computes a fresh signature, which is a full plan hash.
Detection requires a complete pass. The check happens after all 26 rules have run, not after each rule. A plan that oscillates within a pass (rule A undoes rule B, rule C undoes rule A) will not be detected until the pass completes — but it will be detected, because the signature is compared against all previous passes, not just the previous one.

The broader idea

Fixed-point detection by plan identity is a general technique. Compilers use it (hash-consing, “seen this IR before” caches). Query planners use it. What DataFusion does well here is the specificity of the signature: the node count is a structural discriminator that makes the cheap 64-bit hash safe to use as an identity for termination purposes.

The alternative — comparing plans structurally — would be correct in all cases and would cost O(plan) per pass instead of O(plan) per pass plus a hash. Same order of magnitude, honestly. The real win is the early exit: the fixed point is usually reached in pass two, and the set-based check lets the optimizer skip the remaining rules entirely rather than running them and discovering they are no-ops.

Rust on Opensource internals

DataFusion Rewrites Its Plan Trees In Place: Arc::make_mut and the End of the Clone-Collect-Rebuild Cycle

The in-place traversal

Bridging &mut to owned

The subquery fast path

The catch

Why it matters

How DataFusion Knows the Optimizer Has Stopped Improving: A Hash, a Node Count, and a Set of Previous Plans

The loop

The signature

Caveats

Why not just compare the plans?

The cap

The catch

The broader idea

Bridging `&mut` to owned