Module com.darkcollective.relix.ast

Package com.darkcollective.relix.ast

package com.darkcollective.relix.ast

Immutable AST node types for relational algebra expressions.

Overview

The package models the full vocabulary of relational algebra using three sealed interface hierarchies:

• RelNode — relational operations that consume or produce relations (tables). Implementations cover the classic unary operators (σ, π, ρ, δ), binary set and join operators (∪ ⊎ − ∩ ÷ ×, ⋈ ⨝ ⟕ ⟖ ⟗ ⋉ ▷), and extended operators (γ, τ, λ).
• Predicate — boolean conditions used in selections and join conditions. Includes comparison, logical connectives (∧ ∨ ¬), null testing (⊥), and set membership (∈ ∉).
• Operand — scalar value expressions appearing in projections and predicates. Covers attribute references, literals (string, number, boolean), arithmetic expressions, function calls, set literals, and unary negation.

Design

All node types are Java records — they are value-based, thread-safe, and structurally equal (two nodes with the same fields compare as equal). Lists inside records are defensively copied to unmodifiable views. Constructor validation throws NullPointerException for null required fields and IllegalArgumentException for semantically invalid values (e.g., blank names, empty projection attribute lists).

The RelNode.prettyPrint() default method produces a Unicode relational algebra string that can be round-tripped through the parser.

Visitor pattern

Every node type exposes an accept method typed to the corresponding visitor interface in com.darkcollective.relix.ast.visitor. Implement one of the three visitor interfaces to add new traversals without modifying the node classes.

See Also:

• RelNode
• Predicate
• Operand
• com.darkcollective.relix.ast.visitor

Related Packages

Package	Description
com.darkcollective.relix.ast.internal	Helpers over the expression tree that the engine's phases share: structural equivalence, operand walking, conjunct handling, temporal literal parsing.
com.darkcollective.relix.ast.visitor	The visitor interfaces over the expression tree: RelNodeVisitor, PredicateVisitor and OperandVisitor.

Class	Description
AggregateFunction	Represents an aggregate function in an aggregation operation.
AggregateOperator	Aggregate function operators used in AggregateFunction.
AggregationNode	Represents an aggregation operation (γ) in relational algebra.
AllenRelation	Allen's interval algebra relations used in IntervalJoinNode.
AllocationSpec	Specifies the continuous LP (linear-programming) allocation mode for the OPTIMIZE ALLOCATE operator.
AndPredicate	Logical conjunction (∧) — true when both left and right are true.
AntiJoinNode	Represents an anti-join operation (▷).
ArithmeticOperator	Binary arithmetic operators used in BinaryArithmeticExpression.
ArrayConstruction	Constructs a nested array value in a projection — [ expr, expr, … ].
AsOfJoinNode	AS-OF join (ASOF) — a temporal "pick the nearest right row by time" join.
AstBuilders	The AST authoring surface — one factory per node kind, for tests and embedders that build a tree directly rather than parsing one.
AttributeOperand	A column reference operand, optionally relation-qualified.
BinaryArithmeticExpression	A binary arithmetic expression (left op right) used in projections and predicates.
BooleanOperand	A boolean literal operand (true or false).
ClosureNode	Transitive closure (least fixpoint) of a binary relation — the recursive "reachability" operator.
ClusterNode	Connected-components labelling of an undirected graph — the entity-resolution / network-island operator.
ComparisonOperator	Binary comparison operators used in ComparisonPredicate.
ComparisonPredicate	A binary comparison predicate (left op right).
CompositionNode	Relational composition (∘) — composes two relations on their shared columns, like function composition.
ConditionalJoinNode	The uniform shape shared by every condition-carrying binary join: (left, right, condition, location).
ConditionOperand	A boolean-valued operand: a Predicate used in operand position.
ConsolidationFunction	Consolidation functions for the DownsampleNode time-series aggregation operator.
CoverNode	Covering-reduction node — COVER [EXACT] t (R).
DateOperand	A typed calendar-date literal operand, written DATE '2026-06-15'.
DifferenceNode	Set difference (−) — returns tuples that appear in left but not in right.
DistinctNode	Distinct (δ) — eliminates duplicate tuples from input.
DivisionNode	Relational division (÷) — returns tuples from left that are associated with every tuple in right (the relational analogue of "for all").
DownsampleNode	Time-series downsampling (DOWNSAMPLE) — groups input rows into fixed-width time buckets and consolidates numeric columns within each bucket using the chosen ConsolidationFunction.
DurationOperand	A typed duration literal operand, written DURATION 'PT30M'.
ElementOfPredicate	Represents element-of predicates: element ∈ set_expression or element ∉ set_expression Used for set membership testing (equivalent to SQL IN/NOT IN).
EmptyRelationNode	The relation with no rows and the heading of another expression — the ∅ that a provably-unsatisfiable query collapses to.
Expr	The readable spelling of AstBuilders — comparisons by name, n-ary connectives, and literals built from Java values rather than from their source spelling.
FixpointNode	General monotone recursion — the least-fixpoint binder FIX.
FullOuterJoinNode	Full outer join (⟗) — returns all tuples from both left and right; unmatched tuples on either side are padded with nulls.
FunctionCall	Represents a function call in an expression.
GroupingKey	A single grouping key of an aggregation (γ): the Operand expression the rows are grouped by, with an optional alias for the output column.
IntersectionNode	Set intersection (∩) — returns tuples that appear in both left and right.
IntervalJoinNode	Interval join (IJOIN) — a temporal join over two interval-valued relations using an Allen's interval algebra relation.
IterateNode	Replace-each-round iteration — the binder ITERATE.
IterateStop	When an IterateNode stops.
IterateStop.Converged	UNTIL c, … WITHIN ε PER k, … MAX n ROUNDS — stop when, for every key, every named column changed by at most tolerance since the previous round, and no key appeared or disappeared.
IterateStop.Rounds	ROUNDS n — apply the step exactly n times; ROUNDS 0 is the base unchanged.
IterateStop.Stable	UNTIL STABLE MAX n ROUNDS — stop at the first round whose output equals its input.
LateralJoinNode	A correlated / lateral table-valued function application that produces one sub-relation per row of its left input.
LeftOuterJoinNode	Left outer join (⟕) — returns all tuples from left, paired with matching tuples from right; unmatched left tuples are padded with nulls.
LimitNode	Represents a limit operation (λ) in relational algebra.
MaterializationMode	Describes the output materialisation strategy of a relational algebra node.
NaturalJoinNode	Natural join (⋈) — joins two relations on all attributes with the same name, projecting away the duplicate join columns.
NotPredicate	Logical negation (¬) — true when predicate is false.
NullPlacement	Controls where NULL values appear when a column is used as a sort key.
NullPredicate	Represents a null predicate (IS NULL or IS NOT NULL) in relational algebra.
NumberOperand	A numeric literal operand, stored as its original string representation.
ObjectiveSense	The optimisation direction of an OptimizeNode: whether the objective is to be maximised or minimised.
OffsetFunction	The offset window functions carried by a WindowFunction.OffsetWindow.
Operand	Root sealed interface for scalar value expressions used in projections and predicates.
OptimizeConstraint	A single linear constraint of an OptimizeNode: SUM(expr) op bound.
OptimizeNode	Declarative optimisation (OPTIMIZE) — the goal-seeking sibling of γ.
Ordering	A sort ordering — the sequence of (column, direction) keys by which a relation's rows are ordered.
OrPredicate	Logical disjunction (∨) — true when at least one of left or right is true.
OuterUnionNode	Outer-union (⊔) — a schema-reconciling merge of two relations that need not be union-compatible.
PairwiseUniversalNode	Represents a pairwise universal semi-join (USEMI), the ∀ dual of semi-join (⋉).
PathNode	Bounded variable-length path reachability — the RA-native graph-traversal operator.
PatternPredicate	Represents a pattern-matching predicate: operand LIKE pattern or operand NOT LIKE pattern.
PivotNode	Row-pivoting operator (PIVOT) — spreads distinct values of a key column into new columns.
Predicate	Root sealed interface for boolean filter conditions.
ProduceBound	A production stop folded into a monotone generator leaf by the optimizer's SelectionIntoGeneratorPass (GEN-001).
ProductNode	Cartesian product (×) — returns every combination of a tuple from left with a tuple from right.
ProjectedAttribute	Represents a projected attribute in a projection operation.
ProjectionNode	Projection (π) — selects a subset of attributes from input, optionally computing new expressions or renaming columns.
RankingFunction	The ranking window functions carried by a WindowFunction.RankingWindow.
RecursiveRefNode	An occurrence of a FIX-bound recursive relation name inside the body of its enclosing FixpointNode.
RelationFunctionCall	A reference to a table-valued (relation-returning) user-defined function, used wherever a relation is expected — a leaf node in the relational algebra tree.
RelationNode	A base relation (table) reference — a leaf node in the relational algebra tree.
RelNode	Root sealed interface for all relational algebra operation nodes.
RenameNode	Rename (ρ) — renames a relation and optionally reassigns its attribute names.
RenameNode.RenamePair	A single old → new column rename within the pair form.
ReservoirSampleNode	Reservoir (fixed-count) sampling (SAMPLE … ROWS) — keeps exactly count rows of input, chosen uniformly at random without replacement.
RightOuterJoinNode	Right outer join (⟖) — returns all tuples from right, paired with matching tuples from left; unmatched right tuples are padded with nulls.
SampleNode	Bernoulli sampling (SAMPLE) — independently keeps each row of input with probability probability (a fraction in [0, 1]).
SelectionNode	Selection (σ) — filters the tuples of input to those satisfying predicate.
SemiJoinNode	Represents a semi-join operation (⋉).
SessionizeNode	Gap-and-island / sessionization operator — groups an ordered stream into sessions separated by an idle gap, the famous SQL LAG/running-sum incantation expressed as a single algebraic operator.
SetLiteralOperand	Represents a set literal like {1, 2, 3} or {"active", "pending"} Used in element-of predicates for set membership testing.
SolveNode	Goal-seek (SOLVE) — a per-row operator that fills a single unknown column by inverting a declared arithmetic equation left = right.
SortDirection	Sort direction used in a SortSpecification.
SortNode	Represents a sort operation (τ) in relational algebra.
SortSpecification	A single sort key: the Operand expression to order by, the direction (SortDirection.ASC / SortDirection.DESC), and the implicit NULL placement.
SourceLocation	The source location of an AST node — file path, 1-based line, and 1-based column of the first character of the construct.
StringOperand	A string literal operand.
StructConstruction	Constructs a nested struct value in a projection — { name: expr, … }.
StructConstruction.Field	A single struct field: a name paired with its value expression.
SymmetricDifferenceNode	Symmetric difference (∆) — returns tuples that appear in exactly one of left or right, but not in both, eliminating duplicates.
ThetaJoinNode	Theta join (⨝) — inner join that keeps only tuples satisfying condition.
TieBreak	Tie-break rule for AS-OF join (ASOF) when multiple right rows share the nearest match value.
TimeOperand	A typed wall-clock time-of-day literal operand, written TIME '13:40:00'.
TimestampOperand	A typed timestamp literal operand, written TIMESTAMP '2026-06-15T13:40:00Z'.
TopKNode	Top-k per group (TOP) — partitions input by groupingAttributes and, within each group, keeps the count highest rows by sortSpecs (after skipping offset rows).
TraceNode	Optimal-path extraction over a directed, weighted graph — the cheapest (or longest) path finder.
TreeNode	Adjacency-to-forest nesting operator — folds a self-referential adjacency relation into a forest of nested documents, one output row per root, each carrying its whole subtree as a nested ANY document.
TruthRelationNode	A nullary truth relation literal — a leaf node denoting one of the two relations whose heading is the empty (closed, zero-column) schema.
UnaryOperand	Represents a unary operation applied to an operand.
UnionAllNode	Multiset union (⊎) — returns all tuples from both left and right, preserving duplicates (equivalent to SQL UNION ALL).
UnionNode	Set union (∪) — returns tuples that appear in left, right, or both, eliminating duplicates.
UniversalNode	Group-wise universal quantification (∀) — partitions input by the groupingAttributes and keeps the grouping-key tuple of each group in which every row satisfies predicate.
UnnestNode	Unnest (μ) — explodes an array-valued column into one row per element, carrying the other columns through (≈ SQL LATERAL UNNEST, Mongo $unwind).
UnpivotNode	Column-folding operator (UNPIVOT) — transforms selected columns into rows.
WhyNode	Why (ω) — reifies the lineage provenance of input as queryable data.
WindowFrame	The scope of rows fed to a WindowFunction within a partition.
WindowFrame.BoundedFrame	A trailing n-row sliding window — OVER n ROWS — equivalent to SQL's ROWS BETWEEN n-1 PRECEDING AND CURRENT ROW.
WindowFrame.CumulativeFrame	The cumulative (running) frame — OVER ALL ROWS — equivalent to SQL's ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW.
WindowFrame.PartitionFrame	The full-partition frame used implicitly by ranking and offset functions — equivalent to SQL's ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING.
WindowFunction	The computation a WindowNode performs per row.
WindowFunction.AggregateWindow	A sliding / cumulative aggregate over an Operand argument — the same AggregateOperator + Operand pair used by γ.
WindowFunction.OffsetWindow	An offset function (slice 4).
WindowFunction.RankingWindow	A ranking function (slice 3).
WindowNode	Window operator — a non-collapsing per-partition computation that adds one column to every input row without removing or merging any.