Module com.darkcollective.relix.ast

Package com.darkcollective.relix.ast.internal

Class RelNodeOperands

java.lang.Object

com.darkcollective.relix.ast.internal.RelNodeOperands

public final class RelNodeOperands
extends Object

The operand-level counterpart of RelNode.children(): a single, exhaustive registration point for the Operand and Predicate expressions each RelNode carries directly.

children() answers "what relations feed this node"; this answers "what expressions does this node evaluate". The second question had no single answer before — every analysis that needed it either wrote its own partial switch or, more often, missed the expressions entirely. Two node kinds are the classic blind spot, because they carry expressions that are not relational children and therefore do not show up in any structural traversal at all: RelationFunctionCall.arguments() (a leaf, so children() is empty) and LateralJoinNode.arguments() (children() reports only the left input).

Like children(), the implementation is an exhaustive switch over the sealed hierarchy with no default arm, so a new RelNode does not compile until its expressions are registered here. That is the point: an analysis built on this walker cannot silently go stale when the AST grows.

The walk comes in two forms — forEach(com.darkcollective.relix.ast.RelNode, java.util.function.Consumer<com.darkcollective.relix.ast.Operand>, java.util.function.Consumer<com.darkcollective.relix.ast.Predicate>) reads the expressions, and map(com.darkcollective.relix.ast.RelNode, java.util.function.UnaryOperator<com.darkcollective.relix.ast.Operand>, java.util.function.UnaryOperator<com.darkcollective.relix.ast.Predicate>) rewrites them, returning the rebuilt node. Both are exhaustive, so the "which expressions does this node carry" and "how is this node rebuilt around new expressions" knowledge sits in one place rather than being re-derived per consumer.

What it does and does not recurse

This is a shallow walk: it reports the expressions of node itself and does not descend into its children. Compose it with RelNode.children() to walk a whole tree, and with OperandWalker to descend within a reported operand or predicate:

 static void walkTree(RelNode node, Consumer<FunctionCall> onCall) {
     RelNodeOperands.forEach(node,
             operand   -> OperandWalker.walk(operand,   attr -> { }, onCall),
             predicate -> OperandWalker.walk(predicate, attr -> { }, onCall));
     node.children().forEach(child -> walkTree(child, onCall));
 }
 

EmptyRelationNode.heading() is deliberately not reported. It is an inert carrier for a replaced sub-expression rather than something the node evaluates — the same reason children() omits it.

This module carries no dependencies beyond the JDK, so the walker is safe to reuse from any module that depends on the AST.

Method Summary

Modifier and Type	Method	Description
static void	forEach(RelNode node, Consumer<Operand> onOperand, Consumer<Predicate> onPredicate)	Reports every Operand and Predicate that node carries directly, in no particular order.
static RelNode	map(RelNode node, UnaryOperator<Operand> onOperand, UnaryOperator<Predicate> onPredicate)	The rewriting counterpart of forEach(com.darkcollective.relix.ast.RelNode, java.util.function.Consumer<com.darkcollective.relix.ast.Operand>, java.util.function.Consumer<com.darkcollective.relix.ast.Predicate>): replaces every Operand and Predicate that node carries directly with the result of applying onOperand / onPredicate, and returns the rebuilt node.
static boolean	usesSystemState(RelNode node)	Whether node produces a result that depends on state outside the query — the clock, a random source — ignoring the expressions forEach(com.darkcollective.relix.ast.RelNode, java.util.function.Consumer<com.darkcollective.relix.ast.Operand>, java.util.function.Consumer<com.darkcollective.relix.ast.Predicate>) reports and its children.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

forEach

public static void forEach(RelNode node,
 Consumer<Operand> onOperand,
 Consumer<Predicate> onPredicate)

Reports every Operand and Predicate that node carries directly, in no particular order.

Parameters:

node - the node to inspect; must not be null

onOperand - invoked for each operand expression the node evaluates

onPredicate - invoked for each predicate the node evaluates

usesSystemState

public static boolean usesSystemState(RelNode node)

Whether node produces a result that depends on state outside the query — the clock, a random source — ignoring the expressions forEach(com.darkcollective.relix.ast.RelNode, java.util.function.Consumer<com.darkcollective.relix.ast.Operand>, java.util.function.Consumer<com.darkcollective.relix.ast.Predicate>) reports and its children.

An unseeded SAMPLE / RESERVOIR draws from a fresh random source on each execution, so running it twice over the same input can give two different relations. A seeded one is reproducible and therefore not system-dependent.

Exhaustive over the sealed hierarchy for the same reason forEach(com.darkcollective.relix.ast.RelNode, java.util.function.Consumer<com.darkcollective.relix.ast.Operand>, java.util.function.Consumer<com.darkcollective.relix.ast.Predicate>) is: a new node kind that reads system state must be classified here rather than defaulting, silently, to "reproducible".

Parameters:

node - the node to classify; must not be null

Returns:

true when the node itself reads system state

map

public static RelNode map(RelNode node,
 UnaryOperator<Operand> onOperand,
 UnaryOperator<Predicate> onPredicate)

The rewriting counterpart of forEach(com.darkcollective.relix.ast.RelNode, java.util.function.Consumer<com.darkcollective.relix.ast.Operand>, java.util.function.Consumer<com.darkcollective.relix.ast.Predicate>): replaces every Operand and Predicate that node carries directly with the result of applying onOperand / onPredicate, and returns the rebuilt node.

Like forEach this is shallow — the node's children are left untouched. Compose it with RelNode.mapChildren(java.util.function.UnaryOperator<com.darkcollective.relix.ast.RelNode>) to rewrite a whole tree:

 static RelNode rewrite(RelNode node) {
     RelNode withChildren = node.mapChildren(RelNodeOperands::rewrite);
     return RelNodeOperands.map(withChildren, Simplifier::operand, Simplifier::predicate);
 }
 

Following the same convention as mapChildren, node itself is returned when every mapped expression comes back identical by reference, so a caller can use reference inequality as a "something changed" signal. A mapping function that rebuilds an unchanged expression therefore defeats that signal — return the argument unchanged when no rule fires.

Exhaustive over the sealed hierarchy with no default arm, for the same reason forEach is.

Parameters:

node - the node to rewrite; must not be null

onOperand - applied to each operand expression the node evaluates

onPredicate - applied to each predicate the node evaluates

Returns:

the rebuilt node, or node when no expression changed