Lazy on Opensource internals

Polars Evaluates Expressions in an Arena

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

TL;DR: A Polars expression exists in three shapes. The one you write is a tree of Arc<Expr>. The one the optimizer reasons about is an AExpr node living in a flat Arena<AExpr>, addressed by an 8-byte Node index. The one that touches data is an Arc<dyn PhysicalExpr> tree.

The middle shape is the interesting one: because the plan is a vector plus integers, cloning it is copying indices, comparing two subtrees is comparing integers, and nothing in it is individually freed until the whole arena drops.

Every dataframe engine has to answer the same question twice: how do I describe an expression, and how do I run it? The naive answer is to use one structure for both, and to run it by walking the tree.

Polars does not. It has three distinct representations, and the transitions between them are explicit, one-way, and cheap. This post is about the middle one: the arena.

The shape you write: a tree of `Arc<Expr>`

The user-facing expression is an enum whose children are Arc<Expr>:

 rust
 
 
// crates/polars-plan/src/dsl/expr/mod.rs:76
pub enum Expr {
 /// Values in a `eval` context.
 ///
 /// Equivalent of `pl.element()`.
 Element,
 Alias(Arc<Expr>, PlSmallStr),
 Column(PlSmallStr),
 Selector(Selector),
 Literal(LiteralValue),
 DataTypeFunction(DataTypeFunction),
 BinaryExpr {
 left: Arc<Expr>,
 op: Operator,
 right: Arc<Expr>,
 },
 Cast {
 expr: Arc<Expr>,
 dtype: DataTypeExpr,
 options: CastOptions,
 },

This is a perfectly good API shape: it is cheap to clone (cloning an Arc is a refcount bump), it is easy to pattern match on, and it is what the Python bindings, the R bindings, and the Expr builder methods all produce.

It is also a bad shape for a plan. A tree of Arc means:

every node lives in its own heap allocation, scattered across the heap;
“the same expression” is a deep structural comparison, not a pointer comparison;
you cannot hand a sub-expression to another subsystem without either cloning it or keeping the Arc alive, which keeps the whole tree alive.

Polars needs all three capabilities constantly. The optimizer compares sub-expressions to find common subplans. The projection pushdown needs to answer “does this expression mention column a?”. The CSE pass needs to deduplicate identical subtrees. So the DSL tree gets converted, once, into something flat.

The arena

The whole arena is 172 lines in crates/polars-utils/src/arena.rs, and the relevant parts are tiny:

 rust
 
 
// crates/polars-utils/src/arena.rs:26
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Ord, PartialOrd)]
#[repr(transparent)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct Node(pub usize);

...

#[derive(Debug, Clone)]
#[cfg_attr(feature = "ir_serde", derive(Serialize, Deserialize))]
pub struct Arena<T> {
 version: u32,
 items: Vec<T>,
}

and adding a node is a Vec::push plus an index:

 rust
 
 
// crates/polars-utils/src/arena.rs:57
 pub fn add(&mut self, val: T) -> Node {
 let idx = self.items.len();
 self.items.push(val);
 Node(idx)
 }

Reading a node is a bounds-checked index:

 rust
 
 
// crates/polars-utils/src/arena.rs:106
 #[inline]
 pub fn get(&self, idx: Node) -> &T {
 self.items.get(idx.0).unwrap()
 }

That is the entire data structure. A Node is a usize — a Copy, Eq, Hash, Ord index into a Vec. Everything else in the design follows from that.

The IR node: `AExpr`

The expression IR is a single enum whose children are Nodes rather than pointers:

 rust
 
 
// crates/polars-plan/src/plans/aexpr/mod.rs:180
/// IR expression node that is allocated in an [`Arena`][polars_utils::arena::Arena].
#[derive(Clone, Debug, Default)]
#[cfg_attr(feature = "ir_serde", derive(serde::Serialize, serde::Deserialize))]
pub enum AExpr {
 /// Values in a `eval` context.
 ///
 /// Equivalent of `pl.element()`.
 Element,
 Explode {
 expr: Node,
 options: ExplodeOptions,
 },
 Column(PlSmallStr),
 ...
 BinaryExpr {
 left: Node,
 op: Operator,
 right: Node,
 },
 Cast {
 expr: Node,
 dtype: DataType,
 options: CastOptions,
 },

Note what is not here: no Box, no Arc, no dyn. The recursive edges of the expression graph are plain usizes. The graph is stored in the arena; the enum only carries the edges.

The handle: `ExprIR`

A plan does not hold AExprs directly. It holds ExprIRs, which pair a node index with the output name and a memoized dtype:

 rust
 
 
// crates/polars-plan/src/plans/expr_ir.rs:70
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct ExprIR {
 /// Output name of this expression.
 output_name: OutputName,
 /// Output dtype of this expression
 /// Reduced expression.
 /// This expression is pruned from `alias` and already expanded.
 node: Node,
 #[cfg_attr(feature = "serde", serde(skip))]
 output_dtype: OnceLock<DataType>,
}

ExprIR is Clone, and cloning it copies a Node (8 bytes), an OutputName, and a OnceLock<DataType>. It does not copy the expression subtree, because the subtree lives in the arena and is shared by reference. This is the “cheap cloning of expression trees” property, and it is not an optimization bolted on later — it falls out of the representation.

ExprIR also caches the dtype:

 rust
 
 
// crates/polars-plan/src/plans/expr_ir.rs:291
 pub fn dtype(&self, schema: &Schema, expr_arena: &Arena<AExpr>) -> PolarsResult<&DataType> {
 match self.output_dtype.get() {
 Some(dtype) => Ok(dtype),
 None => {
 let dtype = expr_arena
 .get(self.node)
 .to_dtype(&ToFieldContext::new(expr_arena, schema))?;
 let _ = self.output_dtype.set(dtype);
 Ok(self.output_dtype.get().unwrap())
 },
 }
 }

Since the arena is immutable once built, the dtype of a node is a property of the node, so every ExprIR referring to it agrees. The OnceLock turns a repeated schema query into a pointer read.

From `Expr` to `ExprIR`

The conversion is a recursive walk that bottoms out in a single arena.add:

 rust
 
 
// crates/polars-plan/src/plans/conversion/dsl_to_ir/expr_to_ir.rs:38
/// Converts expression to AExpr and adds it to the arena, which uses an arena (Vec) for allocation.
#[recursive]
pub(super) fn to_aexpr_impl(
 expr: Expr,
 ctx: &mut ExprToIRContext,
) -> PolarsResult<(Node, PlSmallStr)> {

 rust
 
 
// crates/polars-plan/src/plans/conversion/dsl_to_ir/expr_to_ir.rs:170
 Expr::BinaryExpr { left, op, right } => {
 let (l, output_name) = recurse_arc!(left)?;
 let (r, _) = recurse_arc!(right)?;
 (
 AExpr::BinaryExpr {
 left: l,
 op,
 right: r,
 },
 output_name,
 )
 },

 rust
 
 
// crates/polars-plan/src/plans/conversion/dsl_to_ir/expr_to_ir.rs:681
 Ok((ctx.arena.add(v), output_name))
}

The recursion is bottom-up: children are converted first, so by the time the parent is built, its children already have indices. The parent is pushed onto the arena last. The resulting arena is in post-order, which is also the order the physical planner wants to walk.

The whole plan uses two arenas — one for plan nodes, one for expressions:

 rust
 
 
// crates/polars-plan/src/plans/conversion/dsl_to_ir/mod.rs:58
pub fn to_alp(
 lp: DslPlan,
 expr_arena: &mut Arena<AExpr>,
 lp_arena: &mut Arena<IR>,
 // Only `SIMPLIFY_EXPR`, `TYPE_COERCION`, `TYPE_CHECK`, and `PREDICATE_PUSHDOWN` are respected.
 opt_flags: &mut OptFlags,
) -> PolarsResult<Node> {

Lowering to physical expressions

Now the interesting part: the arena is walked to build the operators that actually touch data. The walk is a single match on the IR enum — this is where the plan-time dispatch happens:

 rust
 
 
// crates/polars-expr/src/planner.rs:132
#[recursive]
fn create_physical_expr_inner(
 expression: Node,
 expr_arena: &mut Arena<AExpr>,
 schema: &SchemaRef, // Schema of the input.
 state: &mut ExpressionConversionState,
) -> PolarsResult<Arc<dyn PhysicalExpr>> {
 use AExpr::*;

 let aexpr = expr_arena.get(expression);
 match aexpr.clone() {

 rust
 
 
// crates/polars-expr/src/planner.rs:301
 BinaryExpr { left, op, right } => {
 let output_field = expr_arena
 .get(expression)
 .to_field(&ToFieldContext::new(expr_arena, schema))?;
 let is_scalar = is_scalar_ae(expression, expr_arena);
 let lhs = create_physical_expr_inner(left, expr_arena, schema, state)?;
 let rhs = create_physical_expr_inner(right, expr_arena, schema, state)?;
 Ok(Arc::new(phys_expr::BinaryExpr::new(
 lhs,
 op,
 rhs,
 node_to_expr(expression, expr_arena),
 state.local.has_lit,
 state.allow_threading,
 is_scalar,
 output_field,
 )))
 },

So the dynamic dispatch that a naive engine would pay per row is paid per plan node, at planning time. The match is on a #[derive(Clone)] enum, so the compiler can, in principle, turn the whole arm dispatch into a jump table or a set of specialized branches. What survives into the hot loop is Arc<dyn PhysicalExpr> — a vtable call per operator, not per row.

Note the node_to_expr(expression, expr_arena) argument. Every physical expression carries a copy of the original DSL expression, purely so that error messages can say “this failed in col("a") + col("b")”. That is a deliberate, expensive-in-the-plan-but-free-at-runtime trade: the arena makes it possible to reconstruct the DSL tree lazily, only on the error path.

 rust
 
 
// crates/polars-plan/src/plans/conversion/ir_to_dsl.rs:7
/// converts a node from the AExpr arena to Expr
#[recursive]
pub fn node_to_expr(node: Node, expr_arena: &Arena<AExpr>) -> Expr {
 let expr = expr_arena.get(node).clone();

 match expr {
 AExpr::Element => Expr::Element,
 AExpr::Explode { expr, options } => Expr::Explode {
 input: Arc::new(node_to_expr(expr, expr_arena)),
 options,
 },

The dispatch table

Not every IR node becomes a bespoke physical operator. Most function expressions are lowered into a generic ApplyExpr that calls a closure. The mapping from IR function to closure lives in one big match in crates/polars-expr/src/dispatch/mod.rs:

 rust
 
 
// crates/polars-expr/src/dispatch/mod.rs:175
/// `input` and `expr_arena` let a function pick a variant based on its arguments, e.g. a
/// constant argument that can be prepared once.
pub fn function_expr_to_udf(
 func: IRFunctionExpr,
 input: &[ExprIR],
 expr_arena: &Arena<AExpr>,
) -> SpecialEq<Arc<dyn ColumnsUdf>> {
 use IRFunctionExpr as F;
 match func {
 // Namespaces
 #[cfg(feature = "dtype-array")]
 F::ArrayExpr(func) => array::function_expr_to_udf(func),
 F::BinaryExpr(func) => binary::function_expr_to_udf(func),
 #[cfg(feature = "dtype-categorical")]
 F::Categorical(func) => cat::function_expr_to_udf(func),
 ...
 F::Boolean(func) => boolean::function_expr_to_udf(func, input, expr_arena),

and the closures are built with a small macro that fixes the calling convention (first column is the root, the rest are arguments):

 rust
 
 
// crates/polars-expr/src/dispatch/mod.rs:58
/// `Fn(&Series, args)`
#[macro_export]
macro_rules! map {
 ($func:path) => {{
 let f = move |c: &mut [::polars_core::prelude::Column]| {
 let c = &c[0];
 $func(c)
 };

 SpecialEq::new(Arc::new(f))
 }};

That is the whole extension mechanism for user-defined and built-in functions: an IR enum variant, one arm in the dispatch table, one function taking &Column.

Where the `dyn` actually is

It is worth being precise about the dynamic dispatch, because the usual claim (“Polars avoids Box<dyn>”) is only half true and the half that is false matters.

The DSL layer is an enum with Arc<Expr> children — there is no Box<dyn Expr> anywhere in it. The IR layer is an enum with Node children, and it has no Box<dyn> either. The dyn appears exactly twice, and both times it is bounded by the number of plan nodes, never by the number of rows:

Arc<dyn PhysicalExpr>, the operator tree. One vtable call per operator per chunk of data, and the kind of operator is resolved at planning time by the match you saw above.
Arc<dyn ColumnsUdf>, the function layer. One vtable call per function application per chunk.

So the cost of dynamic dispatch in Polars is O(operators) per chunk, not O(rows). Compare that with the design where the expression tree itself is Box<dyn Expr> and is walked per row: there the cost is O(rows × operators). The arena is what makes it possible to have the first shape without paying the second.

The other thing the arena changes is where the type information lives. In a Box<dyn Expr> design, the type of a sub-expression is a vtable lookup at runtime. In the IR, the type of a node is a property of the enum variant, known at compile time; the only thing resolved at runtime is the data type, and even that is memoized in the ExprIR.

What the arena buys, concretely

Cheap equality and hashing. Two ExprIRs that refer to the same arena node are the same expression. The canonicalization map exploits this to assign structural equivalence classes to subtrees:

 rust
 
 
// crates/polars-plan/src/plans/aexpr/canonical.rs:23
slotmap::new_key_type! {
 /// Identifies an `AExpr` up to structural equality: two nodes get the same
 /// `CanonicalExprId` if and only if they represent the same expression.
 pub struct CanonicalExprId;
}

Cheap duplication. Duplicating a subtree is one clone of the item plus one push:

 rust
 
 
// crates/polars-utils/src/arena.rs:144
impl<T: Clone> Arena<T> {
 pub fn duplicate(&mut self, node: Node) -> Node {
 let item = self.items[node.0].clone();
 self.add(item)
 }
}

One allocation strategy. Every expression node in the whole plan lives in one Vec. No per-node allocator calls, no Box, no Arc refcount traffic while the plan is being built and rewritten. When the optimizer pushes expressions around — predicate pushdown rewriting a filter, projection pushdown splitting a select, CSE inserting a cache — it copies Nodes, not trees.

Node lifetime. The trade-off is real and worth stating plainly: an arena never frees an individual node. Arena has clear() and pop(), but there is no “free this node”. A rewritten plan leaks the expressions it replaced until the arena itself is dropped. For a query plan, whose lifetime is one collect() call, that is the right trade. It is the wrong trade for a long-lived structure that mutates one node at a time — which is exactly why Arena is not used for, say, the physical operator tree, where each operator has its own lifetime and is dropped independently.

Caching the arena across calls

Because the arena is the plan, and the plan is expensive to rebuild, a LazyFrame keeps it around:

 rust
 
 
// crates/polars-lazy/src/frame/cached_arenas.rs:9
pub(crate) struct CachedArena {
 lp_arena: Arena<IR>,
 expr_arena: Arena<AExpr>,
}

impl LazyFrame {
 pub fn set_cached_arena(&self, lp_arena: Arena<IR>, expr_arena: Arena<AExpr>) {
 let mut cached = self.cached_arena.lock().unwrap();
 *cached = Some(CachedArena {
 lp_arena,
 expr_arena,
 });
 }

 rust
 
 
// crates/polars-lazy/src/frame/cached_arenas.rs:116
 pub(super) fn get_arenas(&mut self) -> (Arena<IR>, Arena<AExpr>) {
 match self.cached_arena.lock().unwrap().as_mut() {
 Some(arenas) => (arenas.lp_arena.clone(), arenas.expr_arena.clone()),
 None => (Arena::with_capacity(16), Arena::with_capacity(16)),
 }
 }

collect_schema() on a LazyFrame converts the DSL plan to IR once, caches both arenas, and reuses them for every subsequent schema query or collect(). Since Arena is Clone and cloning a Vec<AExpr> is a memcpy of the node vector, “reuse the plan” is nearly free. Note the arena has a version counter, bumped on every clear(), so a stale cached plan can be detected rather than silently reused.

The bottom line

The arena is not a performance micro-optimization; it is a representation decision that makes a class of algorithms possible.

The DSL tree (Arc<Expr>) is the right shape for a user API: cheap to build, cheap to share.
The IR (Arena<AExpr> + Node) is the right shape for a plan: flat, index-addressed, comparable by integer, duplicable by memcpy.
The physical tree (Arc<dyn PhysicalExpr>) is the right shape for execution: one vtable call per operator per chunk, and the dispatch on the kind of operator happens at planning time.

The one thing to remember when reading the code: Node is not a pointer, it is an index. That single fact explains why the plan is cheap to copy, why the optimizer can rewrite it freely, why common subplan elimination works, and why every physical operator can afford to carry a copy of the original expression for error messages.

Polars Kills Duplicate Subplans by Fingerprinting Them

Jay Hubbert — Wed, 21 Oct 2026 05:20:00 +0000

TL;DR: The fingerprint of a plan node in Polars is the hash of the node itself plus the canonical ids of its children. The canonical id is obtained by interning that hash in a hashbrown::HashTable whose equality closure compares the children’s ids and the nodes “shallowly”. Two subplans are duplicates exactly when their roots get the same id, which makes the duplicate search a hash-table lookup instead of a subtree comparison. The rewrite replaces the duplicate with an IR::Cache node, and a later pass decides — with row estimates — whether sharing the subplan is actually cheaper than computing it twice.

The brief for this article mentioned a WithCluster rewrite and a Hash impl on IR nodes. Neither exists in that form at this commit. What exists is CanonicalIRMap in crates/polars-plan/src/plans/ir/canonical.rs and CanonicalExprMap in crates/polars-plan/src/plans/aexpr/canonical.rs, and the rewrite they enable is the insertion of IR::Cache nodes. The cluster_with_columns.rs, in the same optimizer directory, is a different optimisation entirely — it merges stacked with_columns stages by name — and it does not fingerprint anything. The title survives the pivot; the mechanism underneath it is better than the one I was promised.

The problem the pass solves

A lazy query like “read this Parquet file, join it to that one, aggregate” often mentions the same scan twice — once on each side of a join, or once per branch of a union. If the engine computes that subplan twice, it reads the file twice, decodes it twice and does the work twice. If it computes it once and shares the result, it holds the intermediate in memory.

Neither is always right. The decision depends on how expensive the subplan is and how expensive it is to materialise, which is why the pass is structured in three stages: detect, rewrite, then evaluate the trade-off.

Detection is gated on a cheap pre-check. Before the expensive pass runs, a member collector walks the plan and counts the scans:

 rust
 
 
// Tracks canonical source identities to check if we have duplicate sources.
#[cfg(feature = "cse")]
#[derive(Default)]
struct UniqueScans {
 ids: PlIndexSet<CanonicalIRId>,
 count: usize,
}

#[cfg(feature = "cse")]
impl UniqueScans {
 fn insert(
 &mut self,
 node: Node,
 lp_arena: &Arena<IR>,
 expr_arena: &Arena<AExpr>,
 canonical_ir_map: &mut CanonicalIRMap,
 ) {
 self.ids
 .insert(canonical_ir_map.resolve(node, lp_arena, expr_arena));
 self.count += 1;
 }
}

crates/polars-plan/src/plans/optimizer/collect_members.rs:24

The collector puts every scan through the canonical map:

 rust
 
 
 #[cfg(feature = "cse")]
 Scan { .. } => {
 self.scans
 .insert(_node, lp_arena, _expr_arena, &mut canonical_ir_map);
 },

crates/polars-plan/src/plans/optimizer/collect_members.rs:95

and the “are there duplicates?” question is answered by comparing the number of scans against the number of distinct scan ids:

 rust
 
 
 #[cfg(feature = "cse")]
 pub(super) fn has_duplicate_scans(&self) -> bool {
 self.scans.count != self.scans.ids.len()
 }

crates/polars-plan/src/plans/optimizer/collect_members.rs:124

Note that this pre-check already uses the fingerprinting machinery. The collector interns every scan into a CanonicalIRMap and counts how many distinct ids there are. If there are as many ids as scans, nothing is duplicated and the whole common-subplan pass is skipped. This is the first place the “fingerprint” earns its keep: the duplicate check is a hash lookup, not a plan comparison.

The pass itself is then run conditionally, and only when there is a reason to believe it will find something:

 rust
 
 
 if comm_subplan_elim {
 feature_gated!("cse", {
 let members = get_or_init_members!();
 if ((members.has_sink_multiple || members.has_joins || members.has_unions)
 && members.has_duplicate_scans())
 || members.has_cse_equivalent_resolvers()
 {
 if verbose {
 eprintln!("found multiple sources; run comm_subplan_elim")
 }

 run_set_cache_states = cse::cspe::common_subplan_elimination(
 root,
 ir_arena,
 expr_arena,
 polars_config::config().allow_nested_cspe(),
 !opt_flags.streaming(),
 );
 }
 });
 };

crates/polars-plan/src/plans/optimizer/mod.rs:165

The fingerprint

Here is the whole idea in one function. resolve_single is called for a node whose children already have canonical ids; it hashes the node and the child ids together, looks the hash up in a hash table, and returns the id of the equivalence class it belongs to:

 rust
 
 
 fn resolve_single(
 &mut self,
 node: Node,
 child_ids: Vec<CanonicalIRId>,
 lp_arena: &Arena<IR>,
 expr_arena: &Arena<AExpr>,
 ) -> CanonicalIRId {
 let exprs_are_nondeterministic = lp_arena.get(node).exprs().any(|expr| {
 let expr_id = self.expr_map.resolve(expr.node(), expr_arena);
 self.expr_map.is_nondeterministic_excluding_udfs(expr_id)
 });

 let Self {
 deduplication_map,
 cache,
 eq_classes,
 expr_map,
 } = self;

 let expr_cmp = CanonicalExprMapWithArena::new(expr_map, expr_arena);
 let hash = combined_hash(node, &child_ids, lp_arena, &expr_cmp);
 let entry = deduplication_map.entry(
 hash,
 |&other| {
 let other = &eq_classes[other.index()];
 child_ids == other.child_ids
 && lp_arena
 .get(node)
 .is_ir_equal_shallow(lp_arena.get(other.representative), &expr_cmp)
 },
 |&other| {
 let other = &eq_classes[other.index()];
 combined_hash(other.representative, &other.child_ids, lp_arena, &expr_cmp)
 },
 );

crates/polars-plan/src/plans/ir/canonical.rs:109

and the hash itself:

 rust
 
 
/// Hashes the node itself, without descending into its inputs, combined with the
/// ids of those inputs.
fn combined_hash(
 node: Node,
 child_ids: &[CanonicalIRId],
 lp_arena: &Arena<IR>,
 expr_cmp: &CanonicalExprMapWithArena,
) -> u64 {
 let mut hasher = DefaultHasher::new();
 lp_arena
 .get(node)
 .hash_excluding_inputs(&mut hasher, expr_cmp);
 for child_id in child_ids {
 child_id.hash(&mut hasher);
 }
 hasher.finish()
}

crates/polars-plan/src/plans/ir/canonical.rs:214

This is a Merkle-style structural hash, and it is the reason the whole thing is cheap. The hash of a node depends only on (a) the node’s own contents and (b) the ids of its children — and those ids are already canonical, so two structurally identical subtrees produce the same child ids, hence the same parent hash, hence the same id, all the way up. The recursion is never done twice for the same subtree: the ids are memoised per node in a cache.

text

 subplan A subplan B
 --------- ---------
 Filter(a > 3) hash -> h1 Filter(a > 3) hash -> h1
 | |
 child id 7 child id 7
 | |
 Scan(files) hash -> h2 Scan(files) hash -> h2
 | |
 child id 11 child id 11
 | |
 Select(*) hash -> h3 Select(*) hash -> h3
 | |
 id = 42 <---------------------------> id = 42 (same class)

Note the direction of the arrows: the id of a node is a function of its children’s ids, so the ids have to be computed bottom-up. That is exactly what the post-order traversal in resolve does.

Note the two-level structure: hash is a bucket selector, and the equality closure is the real test. Two nodes with the same hash are only the same if their child ids match and their shallow contents match. That is the standard hash-table contract, and it is why the equality closure has to be exactly as strong as the hash — if hash_excluding_inputs hashed something the equality check ignores, two different plans could land in the same class.

The Hash impl

The brief asked about a Hash impl for IR nodes. There is not one, and there cannot be a simple one: an IR node contains child plan nodes (Node indices into an arena) and child expression nodes. Hashing the arena indices would make the hash depend on the arena layout rather than on the plan, which is exactly what the canonical id is supposed to avoid.

So IR gets a hand-written method instead, and the method is explicit about what it does and does not cover:

 rust
 
 
impl IR {
 /// Hash the contents of the enum, without descending into child IR nodes.
 /// The user can choose how to hash the referenced ExprIR nodes by providing `expr_hash`
 pub(crate) fn hash_excluding_inputs<H: Hasher>(
 &self,
 state: &mut H,
 expr_hash: &impl ExpressionHasher,
 ) {
 let hash_exprs = |exprs: &[ExprIR], state: &mut H| {
 for e in exprs {
 expr_hash.hash_expr(e, state);
 }
 };

 std::mem::discriminant(self).hash(state);

crates/polars-plan/src/plans/ir/hash.rs:21

and the arms themselves show the pattern — the node’s own payload is hashed, the child plan node is not:

 rust
 
 
 IR::Slice {
 offset,
 len,
 input: _,
 } => {
 len.hash(state);
 offset.hash(state);
 },
 IR::Filter {
 input: _,
 predicate,
 } => {
 expr_hash.hash_expr(predicate, state);
 },

crates/polars-plan/src/plans/ir/hash.rs:81

The input: _ in every arm is the point: the children are not hashed here, they are contributed by the caller as canonical ids. The expressions that hang off the node are hashed, but through the pluggable ExpressionHasher, because an expression is hashed by its canonical id rather than by its contents:

 rust
 
 
#[cfg(feature = "cse")]
impl<'a> ExpressionHasher for CanonicalExprMapWithArena<'a> {
 fn hash_expr<H: Hasher>(&self, expr: &ExprIR, state: &mut H) {
 self.map
 .borrow_mut()
 .resolve(expr.node(), self.arena)
 .hash(state);
 expr.output_name_inner().hash(state);
 }
}

crates/polars-plan/src/plans/aexpr/canonical.rs:231

The expression side has its own Hash impl, and it is a shallow one — the variant plus the attributes that matter for equality, never the children:

 rust
 
 
impl Hash for AExpr {
 // This hashes the variant, not the whole expression
 // Make sure that all attributes that are important for equality are hashed. Nodes don't have
 // to be hashed.
 fn hash<H: Hasher>(&self, state: &mut H) {
 std::mem::discriminant(self).hash(state);

 match self {
 AExpr::Column(name) => name.hash(state),
 #[cfg(feature = "dtype-struct")]
 AExpr::StructField(name) => name.hash(state),
 AExpr::Literal(lv) => lv.hash(state),
 AExpr::Function {
 options,
 function,
 input: _,
 } => {
 options.hash(state);
 function.hash(state)
 },

crates/polars-plan/src/plans/aexpr/hash.rs:15

So there are two nested Merkle constructions: an expression’s id is the hash of its own contents plus its children’s ids, and a plan node’s id is the hash of its own contents plus its children’s ids. CanonicalExprMap and CanonicalIRMap are the same algorithm at two levels, and CanonicalIRMap literally embeds one inside the other:

 rust
 
 
/// Assigns [`CanonicalIRId`]s to `IR` nodes.
pub struct CanonicalIRMap {
 deduplication_map: HashTable<CanonicalIRId>,
 cache: PlIndexMap<Node, CanonicalIRId>,
 /// Indexed by [`CanonicalIRId`], which are handed out densely.
 eq_classes: Vec<CanonicalIRClass>,
 expr_map: CanonicalExprMap,
}

crates/polars-plan/src/plans/ir/canonical.rs:33

Finding the duplicates and rewriting them

With ids assigned, the duplicate search is trivial: a hash map from canonical id to “how many times have I seen this?”. The first traversal assigns the ids and counts the hits:

 rust
 
 
 fn post_visit(
 &mut self,
 key: Self::Key,
 storage: &mut Self::Storage,
 edges: &mut dyn NodeEdgesProvider<Self::Edge>,
 ) -> ControlFlow<Self::BreakValue> {
 let id = self.canonical_ir_map.resolve(key, storage, self.expr_arena);

 use indexmap::map::Entry;

 let entry_idx = match self.id_map.entry(id) {
 Entry::Occupied(mut e) => {
 e.get_mut().hits += 1;
 e.index()
 },
 Entry::Vacant(e) => {
 let idx = e.index();

 e.insert(IDState::new(
 self.canonical_ir_map.is_nondeterministic_excluding_udfs(id),
 ));

 idx
 },
 };

crates/polars-plan/src/plans/optimizer/cse/cspe.rs:128

The second traversal decides which node to cache. The condition is subtle and worth reading closely:

 rust
 
 
 // Cache the topmost deterministic node
 let should_cache = !curr_state.is_nondeterministic_excluding_udfs
 && if output_state.is_nondeterministic_excluding_udfs {
 curr_state.hits > 1
 } else {
 curr_state.hits > output_state.hits
 }
 && (self.cache_plain_scans || !is_plain_scan(storage.get(key)));

crates/polars-plan/src/plans/optimizer/cse/cspe.rs:213

Three conditions:

The node must be deterministic. Caching now() and reading it twice would give two different answers, so a non-deterministic subtree is never shared.
The node must be hit more often than its parent. If the parent is already shared, caching the child again buys nothing; the rule caches the topmost node that is duplicated, so one cache covers the whole duplicate subtree.
A plain scan is only cached if cache_plain_scans is set. Re-reading a file is often cheaper than materialising it — the file is on disk, the cache is in memory.

When the condition holds, the node is wrapped in an IR::Cache:

 rust
 
 
 if should_cache {
 let replacement_ir = match storage.get(key) {
 ir @ IR::Cache { .. } => ir.clone(),
 _ => {
 let ir = storage.take(key);
 let new_key = storage.add(ir);

 IR::Cache {
 input: new_key,
 id: UniqueId::new(),
 }
 },
 };

 curr_state.replacement_ir = Some(replacement_ir);

crates/polars-plan/src/plans/optimizer/cse/cspe.rs:235

The id is a fresh UniqueId per cache node, and it is the thing that ties the duplicates together at execution time. Lowering the plan, the second occurrence of the cache id resolves to the same physical node:

 rust
 
 
 IR::Cache { input, id } => {
 let id = *id;
 if let Some(cached) = cache_nodes.get(&id) {
 return Ok(*cached);
 }

 let phys_input = lower_ir!(*input)?;
 cache_nodes.insert(id, phys_input);
 return Ok(phys_input);
 },

crates/polars-stream/src/physical_plan/lower_ir.rs:1215

So the sharing is not a copy of the data and not a “the second branch reads from the first branch’s output” hack. It is a single physical node with two consumers.

The cost of the pass

The pass is not free, and Polars is explicit about the trade-off.

Planning cost. Two full traversals of the plan, each of which resolves canonical ids, which means hashing every node and every expression on every path. The resolution is memoised per node, so a subtree that is shared is hashed once for the id, but the first traversal still visits every node of the tree.

Memory cost. A cache node materialises the subtree’s output. That is the whole point — the subplan is computed once — but it means the shared data is held in memory for as long as any consumer needs it. For a subplan that produces a lot of rows, sharing it can cost more than recomputing it.

Correctness cost. Sharing a subplan is only sound if the subplan is deterministic and if the consumers want the same thing from it. If one branch filters and the other does not, the filter has to be pushed below the cache, or the cache has to be widened. Polars handles this in set_cache_states, which runs after predicate and projection pushdown and re-runs pushdown on the shared subplan.

And when the estimates are available, the pass makes the trade-off explicit and quantitative:

 rust
 
 
 // Keeping the caches costs one evaluation of the subplan, plus a pass over the
 // materialized rows for every reference that reads and filters them.
 let keep_cost = if remove_caches && removal_cost.is_some() {
 // Caches block pushdown, so their children may still contain cross joins.
 let input = narrowed_shared_subplan(
 &v.children,
 &v.parents,
 pushdown_maintain_errors,
 &mut pred_pd,
 lp_arena,
 expr_arena,
 )?;
 shared_input = Some(input);
 subplan_cost(input, lp_arena, expr_arena)
 .map(|c| c.work + v.cache_nodes.len() as f64 * c.rows)
 } else {
 None
 };

 if let Some((removal_cost, keep_cost)) = removal_cost.zip(keep_cost) {
 remove_caches = removal_cost <= keep_cost;
 if verbose {
 eprintln!(
 "cache removal estimated at {removal_cost:.3e} rows against \
 {keep_cost:.3e} for sharing the subplan"
 )
 }
 }

crates/polars-plan/src/plans/optimizer/cse/cache_states.rs:417

removal_cost is the estimated work of running the subplan once per consumer; keep_cost is the estimated work of computing it once plus a pass over the materialised rows for every consumer. Whichever is smaller wins, and the caches are removed if sharing is not worth it. Without row estimates the pass falls back on the pushdown probe alone, which is conservative in the direction of keeping the cache.

The expression-level sibling

The same fingerprinting machinery is used one level down, for common subexpressions rather than common subplans, in crates/polars-plan/src/plans/optimizer/cse/csee.rs. The canonical map is the same CanonicalExprMap, and the counting pass is the same shape:

 rust
 
 
 if subtree_is_valid
 && role == NodeRole::Candidate
 && (!self.is_group_by || self.has_frame_height(node.node(), arena))
 {
 let id = self.canonical_map.resolve(node.node(), arena);
 *self.se_count.entry(id).or_insert(0) += 1;
 }

crates/polars-plan/src/plans/optimizer/cse/csee.rs:248

and the rewrite replaces the repeated expression with a reference to a temporary column:

 rust
 
 
 fn mutate(
 &mut self,
 mut node: Self::Node,
 arena: &mut Self::Arena,
 ) -> PolarsResult<Self::Node> {
 let (id, count) = self
 .candidate(node.node())
 .expect("mutated node was not a CSE candidate");
 debug_assert!(count > 1);

 node.assign(AExpr::col(cse_column_name(id)), arena);
 self.rewritten = true;

 Ok(node)
 }

crates/polars-plan/src/plans/optimizer/cse/csee.rs:363

The temporary column name is derived from the canonical id, so it is stable and unique across the plan:

 rust
 
 
fn cse_column_name(id: CanonicalExprId) -> PlSmallStr {
 format_pl_smallstr!("{}{:#x}", CSE_REPLACED, id.as_u64())
}

crates/polars-plan/src/plans/optimizer/cse/csee.rs:65

The NodeRole classification is where the safety lives. A literal series that is too long to hash cheaply, a nested dtype, a rolling window, a nondeterministic expression — none of them are candidates, and a node with a non-candidate anywhere below it invalidates its whole subtree:

 rust
 
 
/// Classifies how a visited node may participate in CSE.
fn classify(ae: &AExpr, is_group_by: bool) -> NodeRole {
 match ae {
 // Don't allow this for now, as we can get `null().cast()` in ternary expressions.
 // TODO! Add a typed null
 AExpr::Literal(LiteralValue::Scalar(sc)) if sc.is_null() => NodeRole::Refuse,
 AExpr::Literal(LiteralValue::Series(s)) => {
 let dtype = s.dtype();

 // Object and nested types are harder to hash and compare.
 let allow = !(dtype.is_nested() | dtype.is_object());

 if s.len() < CHEAP_SERIES_HASH_LIMIT && allow {
 NodeRole::Member
 } else {
 NodeRole::Refuse
 }
 },

crates/polars-plan/src/plans/optimizer/cse/csee.rs:162

The bottom line

What the fingerprint buys, concretely:

Duplicate detection is a hash lookup. Comparing two subplans structurally is O(size of the subtree) and is repeated for every pair. Interning them is O(size of the plan) once, and after that everything is integer comparison.
The detection and the rewrite share the same machinery. The same CanonicalIRMap first answers “are there duplicates?” (in the member collector, before the expensive pass is even scheduled) and then answers “which node do I cache?”.
The equality check is still there. The hash only selects a bucket; is_ir_equal_shallow plus the child-id comparison decide membership. A hash collision costs a comparison, never a wrong answer.
Determinism is a first-class property of the fingerprint. The canonical id carries is_nondeterministic_excluding_udfs, computed bottom-up, and a non-deterministic node is never shared.

The costs, stated plainly:

Two traversals and a hash of every node on every query where the cse feature is enabled and the plan has a shape that could contain duplicates. The pass is skipped entirely unless the plan has a sink with multiple inputs, a join or a union and the member collector found duplicate scans.
Materialising the shared subplan. Sharing trades compute for memory, and the memory is held until the last consumer is done with it. The pass models this with row estimates and removes the cache when the arithmetic says sharing is not worth it.
A second, similar mechanism to understand. There are two canonical maps, one for expressions and one for plan nodes, and the expression one is embedded in the plan one. They share the algorithm, not the code.

The practical takeaway: when you see IR::Cache in an optimised Polars plan, the reason it is there is that two parts of the plan fingerprinted identically, and the reason the plan does not have one is that either the fingerprints differed or the arithmetic said that recomputing was cheaper.

Polars Simplifies the Expression Tree Before It Runs Anything

Jay Hubbert — Wed, 21 Oct 2026 05:10:00 +0000

TL;DR: Polars does not have a rule set of arithmetic identities like a + 0 -> a. What it has is a rewrite pass over the expression arena that runs during DSL-to-IR conversion, interleaved with type coercion, and that rewrites the tree to a fixed point: boolean identities (x AND true -> x), constant folding (1 + 2 -> 3), ternary folding (when(true).then(a).otherwise(b) -> a) and function-level rewrites (is_null().any() -> null_count() > 0). The cleverest part is a single bit of context: inside a filter predicate, null and false are the same value, so a rule may replace a column by a scalar there and nowhere else.

I went looking for a table of algebraic identities in crates/polars-plan/src/plans/optimizer/simplify_expr/ expecting to find a + 0 -> a, x * 1 -> x and 0 * x -> 0. They are not there, and the absence is instructive: Polars does not simplify arithmetic against identities. x + 0 is not x in Polars’ semantics in the general case (it can change the dtype of the result, and for a float column x + 0 is not bit-identical to x for -0.0), so the rule does not exist.

What does exist is a small, careful set of rewrites that are always valid, applied by a generic rewrite machinery. That machinery is the interesting part, because the same machinery has to be safe under three different contexts: rewriting an arbitrary expression, rewriting a filter predicate, and rewriting an expression whose dtype is not yet decided.

The rule abstraction

Every rewrite in Polars is a method on a type implementing OptimizationRule. The trait has two hooks: one for rewriting a plan node, one for rewriting an expression node:

 rust
 
 
pub trait OptimizationRule {
 /// Optimize (subplan) in LogicalPlan
 ///
 /// * `lp_arena` - LogicalPlan memory arena
 /// * `expr_arena` - Expression memory arena
 /// * `node` - node of the current LogicalPlan node
 fn optimize_plan(
 &mut self,
 _lp_arena: &mut Arena<IR>,
 _expr_arena: &mut Arena<AExpr>,
 _node: Node,
 ) -> PolarsResult<Option<IR>> {
 Ok(None)
 }
 fn optimize_expr(
 &mut self,
 expr_arena: &mut Arena<AExpr>,
 expr_node: Node,
 schema: &Schema,
 ctx: OptimizeExprContext,
 ) -> PolarsResult<Option<AExpr>> {
 _ = (expr_arena, expr_node, schema, ctx);
 Ok(None)
 }
}

crates/polars-plan/src/plans/optimizer/stack_opt.rs:204

The contract is deliberately minimal: return Some(new_expr) to replace the node, None to leave it alone. The rule does not recurse — the machinery does. That is what makes the rules composable: a rule only has to know how to rewrite one node shape, and the driver takes care of walking the tree and re-running the rule until nothing changes.

There are two drivers. The optimizer-phase one walks the whole plan and repeats until a fixed point:

 rust
 
 
 pub fn optimize_loop(
 &self,
 rules: &mut [Box<dyn OptimizationRule>],
 expr_arena: &mut Arena<AExpr>,
 lp_arena: &mut Arena<IR>,
 lp_top: Node,
 ) -> PolarsResult<Node> {
 let mut changed = true;

 // Nodes of expressions and lp node from which the expressions are a member of.
 let mut plans = vec![];
 let mut exprs = vec![];
 let mut scratch = vec![];
 let mut children = vec![];
 let mut schema_stack: Vec<Arc<Schema>> = vec![];

 // Run loop until reaching fixed point.
 #[allow(clippy::field_reassign_with_default)]
 while changed {
 // Recurse into sub plans and expressions and apply rules.
 changed = false;

crates/polars-plan/src/plans/optimizer/stack_opt.rs:33

and the expression-level driver runs the rules in a tight loop over a single node:

 rust
 
 
 if let Some(rule) = &mut self.simplify {
 while let Some(x) =
 rule.optimize_expr(expr_arena, current_expr_node, schema, ctx)?
 {
 expr_arena.replace(current_expr_node, x);
 }
 }
 if let Some(rule) = &mut self.coerce {
 while let Some(x) =
 rule.optimize_expr(expr_arena, current_expr_node, schema, ctx)?
 {
 expr_arena.replace(current_expr_node, x);
 }
 }

crates/polars-plan/src/plans/conversion/stack_opt.rs:193

That inner while let is what makes the rules rewrite rules rather than peel rules. A rule that turns x AND true into x may expose a new opportunity for the same rule one level up, and the loop keeps going until the tree stops changing. A rule that returned a node that the same rule would immediately rewrite again would loop forever, so the rules are written to be strictly decreasing in some well-founded measure — usually the number of nodes.

Where simplification actually happens

This is the part that surprised me: SimplifyExprRule is not in the list of rules the optimizer runs. The optimizer’s rule list contains FusedArithmetic, SimpleProjectionAndCollapse, DelayRechunk, FilterConstraintRule, SimplifyBooleanRule, FlattenMergeSortedRule and FlattenUnionRule — but not SimplifyExprRule.

SimplifyExprRule runs earlier, during conversion from the DSL to the IR, in the ConversionOptimizer:

 rust
 
 
/// Applies expression simplification and type coercion during conversion to IR.
pub struct ConversionOptimizer {
 /// (expression, schema index, is filter predicate if in a filter)
 scratch: Vec<(Node, usize, bool)>,
 schemas: Vec<Schema>,

 simplify: Option<SimplifyExprRule>,
 coerce: Option<TypeCoercionRule>,
 check: Option<TypeCheckRule>,

crates/polars-plan/src/plans/conversion/stack_opt.rs:13

The order in the loop is simplify, then coerce — for the same node, over and over, until both are stable. That ordering is the whole design in one line: simplify the expression into its simplest form, then insert the casts that make it type-correct, then simplify again (a cast can create a new simplification opportunity), then coerce again.

The reason for doing it here rather than in the optimizer is that the DSL expressions are the ones users write, and the DSL is where the redundancy lives. By the time the plan is an IR, most of it is already gone.

The context bit that makes boolean rules safe

The single most important thing a simplification rule needs to know is whether the expression it is rewriting is a filter predicate, because in that position null and false are interchangeable and a column may be replaced by a scalar. Under Kleene logic, a filter keeps a row iff its predicate is true; a & b is true iff both are; a | b is true iff either is. So in a filter, x AND true really is x — including when x is null, because null AND true is null, and null and false both mean “drop the row”.

That is not true anywhere else. x AND true under a NOT, or as an argument to is_null, or inside an aggregation, has different null behaviour, and replacing a column with a scalar there would change the length of the result.

Polars encodes this in the context:

 rust
 
 
#[derive(Default, Clone, Copy)]
pub struct OptimizeExprContext {
 pub in_pyarrow_scan: bool,
 pub in_io_plugin: bool,
 /// The expression is the predicate of a filter, or is reachable from it only through AND/OR.
 ///
 /// Such an expression only matters through whether it evaluates to `true`: a filter keeps a
 /// row iff its predicate is `true`, and under Kleene logic `a & b` is `true` iff both `a` and
 /// `b` are, and `a | b` iff either is. So rewrites may treat `null` and `false` as the same
 /// value here and may replace a column by a broadcasting scalar. Neither is valid for any
 /// other sub-expression of a filter, e.g. under `NOT`, `XOR`, `is_null` or an aggregation.
 pub is_filter_predicate: bool,
 pub has_inputs: bool,
}

crates/polars-plan/src/plans/optimizer/stack_opt.rs:157

and the flag is propagated down the tree only through AND and OR:

 rust
 
 
/// Whether the inputs of `expr` are filter predicates if `expr` is one, see
/// [`OptimizeExprContext::is_filter_predicate`].
pub fn passes_on_filter_predicate(expr: &AExpr) -> bool {
 matches!(
 expr,
 AExpr::BinaryExpr {
 op: Operator::And | Operator::Or,
 ..
 }
 )
}

crates/polars-plan/src/plans/optimizer/stack_opt.rs:173

So a AND b AND c in a filter: all three are filter predicates. NOT(a AND b) in a filter: a and b are not filter predicates, because the NOT in between breaks the equivalence. This is the kind of detail that a rewrite engine gets wrong, and it is why the flag is computed by the driver rather than guessed by each rule.

The rules themselves

Boolean identities

The And and Or cases live in crates/polars-plan/src/plans/optimizer/simplify_expr/arity.rs:

 rust
 
 
 O::And => {
 let left_ae = expr_arena.get(left);
 let right_ae = expr_arena.get(right);

 // true AND x => x
 if matches!(
 left_ae,
 AExpr::Literal(lv) if lv.bool() == Some(true)
 ) && is_filter_predicate
 {
 // Only in filter as we might change the name from "literal"
 // to whatever lhs columns is.
 return Some(right_ae.clone());
 }

 // x AND true => x
 if matches!(
 right_ae,
 AExpr::Literal(lv) if lv.bool() == Some(true)
 ) {
 return Some(left_ae.clone());
 }

 // x AND false -> false
 // TODO: we need an optimizer redesign to allow x & false to be optimized
 // in general as we can forget the length of a series otherwise.
 // In filter we allow it as the length is not important there.
 if (is_scalar_ae(left, expr_arena) | is_filter_predicate)
 && matches!(
 right_ae,
 AExpr::Literal(lv) if lv.bool() == Some(false)
 )
 {
 return Some(AExpr::Literal(Scalar::from(false).into()));
 }

crates/polars-plan/src/plans/optimizer/simplify_expr/arity.rs:44

Look at the asymmetry: x AND true -> x is always valid, because AND with true propagates the left operand’s value and length. true AND x -> x is only valid in a filter, because true AND x would be a scalar true and x a column, and outside a filter the length matters.

The TODO in the third rule is worth reading twice: x AND false -> false is not valid in general, because the result would be a scalar false where the caller expected a series of the same length as x. The rule is allowed where the length does not matter — a filter, or when the left side is already a scalar.

The same file also has two rules that are pure wins. A AND NOT(A) is always false, and two comparisons on the same operands that can never both hold (col > 5 AND col <= 5) are always false:

 rust
 
 
 // `A AND NOT(A)` is always false (either operand may be the
 // `NOT`). Catches cases the earlier rewrites left alone, like
 // `NOT(col)` on a bool column or `NOT(is_in(col, values))`.
 if is_self_negation(left, left_ae, right_ae, expr_arena, maintain_errors)
 || is_self_negation(right, right_ae, left_ae, expr_arena, maintain_errors)
 {
 return Some(AExpr::Literal(Scalar::from(false).into()));
 }

 // Two comparisons on the same operands that can never both hold,
 // e.g. `(col > N) AND (col <= N)` or `(col > N) AND (col < N)`.

crates/polars-plan/src/plans/optimizer/simplify_expr/arity.rs:59

The contradiction check is done with a three-bit encoding of the comparison operators — a comparison is true in some subset of {<, ==, >} — and two comparisons contradict when their subsets are disjoint:

 rust
 
 
// Bitset positions for the three outcomes of comparing two values.
const CMP_LT: u8 = 1; // x < y
const CMP_EQ: u8 = 2; // x == y
const CMP_GT: u8 = 4; // x > y

// The cases a comparison operator is true in, as a bitset over `<` / `==` / `>`.
// `None` for non-comparison operators.
fn comparison_cases(op: Operator) -> Option<u8> {
 use Operator::*;
 Some(match op {
 Lt => CMP_LT,
 LtEq => CMP_LT | CMP_EQ,
 Gt => CMP_GT,
 GtEq => CMP_GT | CMP_EQ,
 Eq => CMP_EQ,
 NotEq => CMP_LT | CMP_GT,
 EqValidity | NotEqValidity | And | Or | Xor | LogicalAnd | LogicalOr | Plus | Minus
 | Multiply | RustDivide | TrueDivide | FloorDivide | TruncDivide | Modulus => {
 return None;
 },
 })
}

// Whether `(x op1 y) AND (x op2 y)` can never both hold: the operators share no
// case (their true-sets over `<` / `==` / `>` are disjoint). `false` if either
// is not a comparison.
fn comparisons_contradict(op1: Operator, op2: Operator) -> bool {
 match (comparison_cases(op1), comparison_cases(op2)) {
 (Some(a), Some(b)) => a & b == 0,
 _ => false,
 }
}

crates/polars-plan/src/plans/optimizer/simplify_expr/arity.rs:225

Constant folding

Constant folding lives in SimplifyExprRule::optimize_expr and is table-driven by a macro that dispatches on the runtime type of the two literals:

 rust
 
 
 // lit(left) + lit(right) => lit(left + right)
 use Operator::*;
 #[allow(clippy::manual_map)]
 let out = match op {
 Plus => {
 match eval_binary_same_type!(left_aexpr, right_aexpr, |l, r| l + r) {
 Some(new) => Some(new),
 None => {

crates/polars-plan/src/plans/optimizer/simplify_expr/mod.rs:870

The macro eval_binary_same_type! only folds when both sides have the same runtime type, and it returns the result as the same type — that is what the “same_type” in the name means, and it is why i64 + f64 does not fold to an f64 behind your back:

 rust
 
 
 (AnyValue::Int64($l), AnyValue::Int64($r)) => {
 Some(AExpr::Literal(<Scalar as From<i64>>::from($ret).into()))
 },

crates/polars-plan/src/plans/optimizer/simplify_expr/mod.rs:334

The comparisons fold the same way, and the float comparisons use total ordering so that NaN folds deterministically rather than randomly:

 rust
 
 (AnyValue::Float64(l), AnyValue::Float64(r)) => Some(AExpr::Literal({ let x: bool = l.to_total_ord() $operand r.to_total_ord(); Scalar::from(x) }.into())),

crates/polars-plan/src/plans/optimizer/simplify_expr/mod.rs:395

Ternary folding

when(...).then(...).otherwise(...) with a constant predicate collapses to one of its branches, but only when the lengths work out:

 rust
 
 
pub(super) fn simplify_ternary(
 predicate: Node,
 truthy: Node,
 falsy: Node,
 expr_arena: &mut Arena<AExpr>,
) -> Option<AExpr> {
 let predicate = expr_arena.get(predicate);

 if let AExpr::Literal(lv) = predicate
 && let Some(predicate) = lv.bool()
 {
 // Only replace if both are scalar or both are not scalar and are the same length,
 // the latter is tested by checking if they are elementwise.
 let t_is_scalar = is_scalar_ae(truthy, expr_arena);
 let f_is_scalar = is_scalar_ae(falsy, expr_arena);

 if t_is_scalar == f_is_scalar
 && (t_is_scalar
 || (is_elementwise_rec(truthy, expr_arena)
 && is_elementwise_rec(falsy, expr_arena)))
 {
 let branch = if predicate { truthy } else { falsy };
 return Some(expr_arena.get(branch).clone());
 }
 }

 None
}

crates/polars-plan/src/plans/optimizer/simplify_expr/arity.rs:169

The t_is_scalar == f_is_scalar test is the length check: you cannot replace a ternary whose branches have different lengths with one of them, because the result would no longer be elementwise.

Function-level rewrites

crates/polars-plan/src/plans/optimizer/simplify_expr/simplify_functions.rs holds the rules that change the shape of a function call rather than folding a constant:

 rust
 
 
 // is_null().any() -> null_count() > 0
 // is_not_null().any() -> ~is_empty(ignore_nulls=True)
 // CORRECTNESS: we can ignore 'ignore_nulls' since is_null/is_not_null never produces NULLS
 IRFunctionExpr::Boolean(IRBooleanFunction::Any { ignore_nulls: _ }) => {
 let input_node = expr_arena.get(input[0].node());
 match input_node {
 AExpr::Function {
 input,
 function: IRFunctionExpr::Boolean(IRBooleanFunction::IsNull),
 options: _,
 } => Some(AExpr::BinaryExpr {
 left: expr_arena.add(new_null_count(input)),
 op: Operator::Gt,
 right: expr_arena.add(AExpr::Literal(LiteralValue::new_idxsize(0))),
 }),

crates/polars-plan/src/plans/optimizer/simplify_expr/simplify_functions.rs:14

is_null().any() becomes null_count() > 0, which is a single pass over the column instead of a boolean mask followed by an any-reduction. And:

 rust
 
 
 // sort().reverse() -> sort(reverse)
 // sort_by().reverse() -> sort_by(reverse)
 IRFunctionExpr::Reverse => {
 let input = expr_arena.get(input[0].node());
 match input {
 AExpr::Sort { expr, options } if !options.maintain_order => {
 let mut options = *options;
 options.descending = !options.descending;
 options.nulls_last = !options.nulls_last;
 Some(AExpr::Sort {
 expr: *expr,
 options,
 })
 },

crates/polars-plan/src/plans/optimizer/simplify_expr/simplify_functions.rs:85

Reversing a sort is not a separate operator that has to materialise the sorted array and then walk it backwards; it is the same sort with the descending and nulls_last flags flipped. Note the !options.maintain_order guard: with maintain_order set, the sort is stable, and reversing a stable sort is not the same as an unstable sort with flipped flags.

There is also a de Morgan rewrite:

 rust
 
 
 // not(a and b) => not(a) or not(b)
 AExpr::BinaryExpr {
 left,
 op: Operator::And | Operator::LogicalAnd,
 right,
 } => {

crates/polars-plan/src/plans/optimizer/simplify_expr/simplify_functions.rs:170

which matters because the whole boolean-simplification machinery above operates on AND/OR chains: pushing a NOT down to the leaves makes more of those chains visible.

From the simplified tree to running code

The simplified IR expression is not what executes. Two more steps happen afterwards.

Type coercion. TypeCoercionRule runs in the same loop as the simplifier, immediately after it, and inserts the casts that make the expression type-correct. Because both rules loop until stable, a simplification that changes a dtype (say, is_null().any() becoming null_count() > 0) feeds back into the coercion, and the coercion’s inserted casts feed back into the simplifier.

Physical lowering. At execution-planning time the IR expression tree is turned into a tree of PhysicalExpr, which is what actually gets called per chunk:

 rust
 
 
pub fn create_physical_expr(
 expr_ir: &ExprIR,
 expr_arena: &mut Arena<AExpr>,
 schema: &SchemaRef, // Schema of the input.
 state: &mut ExpressionConversionState,
) -> PolarsResult<Arc<dyn PhysicalExpr>> {
 let phys_expr = create_physical_expr_inner(expr_ir.node(), expr_arena, schema, state)?;

 if let Some(name) = expr_ir.get_alias() {
 Ok(Arc::new(AliasExpr::new(
 phys_expr,
 name.clone(),
 node_to_expr(expr_ir.node(), expr_arena),
 )))
 } else {
 Ok(phys_expr)
 }
}

crates/polars-expr/src/planner.rs:135

The simplifier never has to know anything about the physical layer. It rewrites the logical expression, and the physical lowering just walks whatever tree it is handed.

The bottom line

The trade-offs of this design:

The rules are small and always-valid, not clever. There is no x * 1 -> x, no 0 * x -> 0, no reassociation of a + b + c. Each rule that exists is one where the rewrite is provably value-preserving in every context it is enabled in, and the rules that need a context gate get one (is_filter_predicate, is_scalar_ae, is_elementwise_rec).
The context is the hard part, not the rules. A rewrite engine that does not know whether it is inside a filter, under a NOT, or inside an aggregation will produce wrong answers on nulls. Polars computes that information once, in the driver, and hands it to every rule.
The pass is a fixed point, not a single sweep. Rules are applied until the tree stops changing, which is what lets a rule expose work for another rule. The cost is that the pass can visit the same node many times; the mitigation is that rules are written to strictly decrease the size of the tree they produce.
Simplification runs before type coercion, in the same loop. This is why simplification lives in the conversion stage rather than the optimizer: at conversion time the expressions are still the ones the user wrote, before casts have been sprinkled over them.

The order of operations, end to end:

text

 DSL expression
 |
 | ConversionOptimizer
 | loop { simplify; coerce } until stable
 v
 IR expression (AExpr in an arena)
 |
 | optimizer passes: predicate pushdown, projection pushdown, ...
 v
 optimized IR
 |
 | create_physical_expr (crates/polars-expr/src/planner.rs)
 v
 PhysicalExpr tree -> executed per chunk

The practical takeaway: when you look at a Polars plan and see an expression that looks dumber than what you wrote — a null_count() where you wrote is_null(), a sort with flipped flags where you wrote .reverse() — that is the simplifier, and it ran before the plan was even finished being built.

Lazy on Opensource internals

Polars Evaluates Expressions in an Arena

The shape you write: a tree of Arc<Expr>

The arena

The IR node: AExpr

The handle: ExprIR

From Expr to ExprIR

Lowering to physical expressions

The dispatch table

Where the dyn actually is

What the arena buys, concretely

Caching the arena across calls

The bottom line

Polars Kills Duplicate Subplans by Fingerprinting Them

The problem the pass solves

The fingerprint

The Hash impl

Finding the duplicates and rewriting them

The cost of the pass

The expression-level sibling

The bottom line

Polars Simplifies the Expression Tree Before It Runs Anything

The rule abstraction

Where simplification actually happens

The context bit that makes boolean rules safe

The rules themselves

Boolean identities

Constant folding

Ternary folding

Function-level rewrites

From the simplified tree to running code

The bottom line

The shape you write: a tree of `Arc<Expr>`

The IR node: `AExpr`

The handle: `ExprIR`

From `Expr` to `ExprIR`

Where the `dyn` actually is