Module com.darkcollective.relix.plan

Package com.darkcollective.relix.plan

Interface PhysicalNode

All Known Implementing Classes:

PhysicalNode.Aggregate, PhysicalNode.AsOfJoin, PhysicalNode.BernoulliSample, PhysicalNode.Closure, PhysicalNode.Cluster, PhysicalNode.ConstructiveCover, PhysicalNode.Cover, PhysicalNode.Distinct, PhysicalNode.Division, PhysicalNode.Downsample, PhysicalNode.Empty, PhysicalNode.Fixpoint, PhysicalNode.IntervalJoin, PhysicalNode.Iterate, PhysicalNode.Join, PhysicalNode.LateralJoin, PhysicalNode.Limit, PhysicalNode.Optimize, PhysicalNode.Path, PhysicalNode.Pivot, PhysicalNode.Project, PhysicalNode.PushedScan, PhysicalNode.RecursiveRef, PhysicalNode.Rename, PhysicalNode.ReservoirSample, PhysicalNode.Scan, PhysicalNode.Select, PhysicalNode.Sessionize, PhysicalNode.SetOp, PhysicalNode.Solve, PhysicalNode.Sort, PhysicalNode.Spool, PhysicalNode.TopK, PhysicalNode.Trace, PhysicalNode.Tree, PhysicalNode.Universal, PhysicalNode.Unnest, PhysicalNode.Unpivot, PhysicalNode.Why, PhysicalNode.Window

public sealed interface PhysicalNode
permits PhysicalNode.Scan, PhysicalNode.Empty, PhysicalNode.PushedScan, PhysicalNode.Spool, PhysicalNode.Select, PhysicalNode.Project, PhysicalNode.Rename, PhysicalNode.Distinct, PhysicalNode.Unnest, PhysicalNode.Closure, PhysicalNode.Cluster, PhysicalNode.Path, PhysicalNode.Trace, PhysicalNode.Fixpoint, PhysicalNode.Iterate, PhysicalNode.RecursiveRef, PhysicalNode.Limit, PhysicalNode.Sort, PhysicalNode.Aggregate, PhysicalNode.Universal, PhysicalNode.TopK, PhysicalNode.Window, PhysicalNode.Sessionize, PhysicalNode.Tree, PhysicalNode.Why, PhysicalNode.BernoulliSample, PhysicalNode.ReservoirSample, PhysicalNode.Solve, PhysicalNode.Optimize, PhysicalNode.Join, PhysicalNode.AsOfJoin, PhysicalNode.IntervalJoin, PhysicalNode.SetOp, PhysicalNode.Division, PhysicalNode.Cover, PhysicalNode.ConstructiveCover, PhysicalNode.Downsample, PhysicalNode.LateralJoin, PhysicalNode.Unpivot, PhysicalNode.Pivot

A node in a physical query plan — the executable form of a logical RelNode tree, produced by the Planner.

Where the logical tree describes what to compute, the physical plan fixes how: the PhysicalNode.Join node records the chosen PhysicalNode.JoinAlgorithm and PhysicalNode.BuildSide, and every node carries its already resolved output schema() so the executor never has to re-infer schemas or look them up by node identity.

The hierarchy is sealed; the permitted operators are declared as nested records. Operators with no physical choice (PhysicalNode.Select, PhysicalNode.Project, PhysicalNode.Rename, PhysicalNode.Aggregate, PhysicalNode.Sort, PhysicalNode.Limit, PhysicalNode.Distinct, PhysicalNode.SetOp, PhysicalNode.Division) mirror their logical counterparts one-to-one; PhysicalNode.Join consolidates every join flavour (including Cartesian product) plus the physical strategy; PhysicalNode.Scan is the leaf that reads a base relation. Views are inlined by the planner, so they never appear as a node.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	PhysicalNode.Aggregate	Aggregation (γ) — groups by groupingKeys and reduces each group with aggregates.
static final record	PhysicalNode.AsOfJoin	AS-OF join — a temporal "pick the nearest right row by time" join.
static final record	PhysicalNode.BernoulliSample	Bernoulli sampling (SAMPLE p [SEED n]): keeps each row of input independently with probability probability.
static enum	PhysicalNode.BuildSide	Which input a join materialises (hashes, or buffers for nested-loop).
static final record	PhysicalNode.Closure	Transitive closure (least fixpoint) of the input edge relation over PhysicalNode.Closure.fromColumn()/PhysicalNode.Closure.toColumn().
static final record	PhysicalNode.Cluster	Connected-components labelling (CLUSTER) of the input edge relation, read as undirected edges over PhysicalNode.Cluster.fromColumn()/PhysicalNode.Cluster.toColumn().
static final record	PhysicalNode.ConstructiveCover	Constructive covering reduction (COVER, constructive mode): builds candidate rows value-by-value over the PhysicalNode.ConstructiveCover.factors domains, using PhysicalNode.ConstructiveCover.conjuncts as a validity oracle, never materialising the full Cartesian product.
static final record	PhysicalNode.Cover	Covering reduction (COVER): keeps a near-minimal subset of input rows such that every distinct t-column value combination (PhysicalNode.Cover.strength-way tuple) occurring in the input occurs in the output.
static final record	PhysicalNode.Distinct	Distinct (δ) — eliminates duplicate rows.
static final record	PhysicalNode.Division
static final record	PhysicalNode.Downsample	Time-series downsampling (DOWNSAMPLE): groups input rows into fixed-width time buckets and consolidates numeric columns using the chosen ConsolidationFunction.
static final record	PhysicalNode.Empty	Produces no rows at all, under schema's heading — the physical form of EmptyRelationNode, planted by the optimizer where a sub-tree was proved unsatisfiable.
static final record	PhysicalNode.Fixpoint	General monotone recursion (FIX): computes the semi-naïve least-fixpoint of PhysicalNode.Fixpoint.step() seeded by PhysicalNode.Fixpoint.base(), with the relation named PhysicalNode.Fixpoint.name() bound to the current delta during each step evaluation.
static final record	PhysicalNode.IntervalJoin	Interval join — tests each pair of rows against an Allen interval algebra relation.
static final record	PhysicalNode.Iterate	Replace-each-round iteration (ITERATE): evaluates PhysicalNode.Iterate.base(), then evaluates PhysicalNode.Iterate.step() with the relation named PhysicalNode.Iterate.name() bound to the previous round's whole output, replacing it each round, until PhysicalNode.Iterate.stop() is satisfied.
static final record	PhysicalNode.Join	A join of any kind, carrying the chosen physical strategy.
static enum	PhysicalNode.JoinAlgorithm	How a join is executed.
static final record	PhysicalNode.JoinKeys	Equi-join key columns: left.get(i) and right.get(i) are the positions, in the left and right inputs, of the i-th equated column pair.
static enum	PhysicalNode.JoinKind	The join flavour.
static final record	PhysicalNode.LateralJoin	Lateral / correlated table-valued function join: for each row of PhysicalNode.LateralJoin.left(), evaluates the PhysicalNode.LateralJoin.arguments() in that row's context, binds them into the function body via PhysicalNode.LateralJoin.bodyBuilder(), plans the instantiated body, and concatenates the left row with each row the body produces.
static final record	PhysicalNode.Limit	Limit (λ) — takes a prefix of the input; preserves the input's delivered ordering.
static final record	PhysicalNode.Optimize	Declarative optimisation (OPTIMIZE): within each group (by groupingKeys) either selects the optimal subset (MIP, when allocation is empty) or assigns continuous allocations (LP, when allocation is present).
static final record	PhysicalNode.Path	Bounded variable-length path reachability (PATH) over the input edge relation, read over PhysicalNode.Path.fromColumn()/PhysicalNode.Path.toColumn() as directed edges, or as undirected ones when PhysicalNode.Path.undirected().
static final record	PhysicalNode.Pivot	Rows-to-columns rotation (PIVOT): groups the input by the optional groupKeys, then turns each distinct value of keyColumn into a new output column whose cell is the corresponding valueColumn cell (NULL when the group has no row for that key).
static final record	PhysicalNode.Project
static final record	PhysicalNode.PushedScan	A leaf that pushes a relational sub-expression down to a connector as a single native query.
static final record	PhysicalNode.RecursiveRef	A reference to the relation bound by an enclosing PhysicalNode.Fixpoint or PhysicalNode.Iterate.
static final record	PhysicalNode.Rename	Relation/column rename — a metadata-only relabel to PhysicalNode.Rename.schema().
static final record	PhysicalNode.ReservoirSample	Reservoir (fixed-count) sampling (SAMPLE … ROWS [SEED n]): keeps exactly count rows of input, chosen uniformly at random without replacement (or the whole input when it has fewer rows).
static final record	PhysicalNode.Scan	Reads a base relation: inline rows, or an external source/database via the connector.
static final record	PhysicalNode.Select	Selection (σ) — streaming row filter; preserves the input's delivered ordering.
static final record	PhysicalNode.Sessionize	Gap-and-island / sessionization (SESSIONIZE): within each partition (by partitionKeys) orders rows ascending by orderColumn and appends a 1-based session-id column (sessionColumn), incremented whenever the gap to the prior row exceeds threshold.
static enum	PhysicalNode.SetKind	The set-operation flavour.
static final record	PhysicalNode.SetOp
static final record	PhysicalNode.Solve	Goal-seek (SOLVE): for each row of input, fills the single NULL column participating in the equation left = right by inverting the arithmetic.
static final record	PhysicalNode.Sort	Sort (τ) — establishes ordering on its sort keys.
static final record	PhysicalNode.Spool	Marks a sub-plan whose rows are computed once and read by more than one consumer.
static final record	PhysicalNode.TopK	Top-k per group: within each partition (by groupingAttributes) keeps the count rows highest by sortSpecs, after skipping offset.
static final record	PhysicalNode.Trace	Optimal-path extraction (TRACE) over the input weighted edge relation, read as directed edges or, when PhysicalNode.Trace.undirected(), as undirected ones.
static final record	PhysicalNode.Tree	Adjacency-to-forest nesting (TREE): folds the adjacency relation input (with node key keyColumn and parent key parentColumn) into a forest of nested documents — one output row per root, each carrying its subtree in the appended childrenColumn array (siblings ordered by orderSpecs, empty = input order).
static final record	PhysicalNode.Universal	Group-wise universal quantification (∀): keeps the grouping-key tuple of each group in which every row of input satisfies predicate (strict NULL semantics — an UNKNOWN row disqualifies its group).
static final record	PhysicalNode.Unnest	Unnest (μ) — explodes the array-valued column into one row per element; outer keeps a NULL-bound row when the array is empty/missing.
static final record	PhysicalNode.Unpivot	Column-to-rows rotation (UNPIVOT): folds the listed columns into rows — each input row fans out to one output row per listed column, with the column name placed in nameColumn (STRING) and the cell value in valueColumn (ANY).
static final record	PhysicalNode.Why	Lineage reification (WHY): emits every result tuple of its input unchanged plus the reserved provenance:ANY column holding that tuple's lineage polynomial as a nested document.
static final record	PhysicalNode.Window	Window (ROLLING / WINDOW): adds one computed column (outputColumn) to every input row, partitioned by partitionKeys and ordered within each partition by sortSpecs.

Method Summary

Modifier and Type	Method	Description
List<PhysicalNode>	children()	Direct child plans, left-to-right; empty for a PhysicalNode.Scan.
default Ordering	deliveredOrdering()	The Ordering that this node delivers on its output stream.
default PhysicalNode	mapChildren(UnaryOperator<PhysicalNode> f)	Returns this node with each direct child replaced by the result of applying f to it, preserving every other component — schema, join algorithm, predicates, keys, bounds.
Schema	schema()	The output schema of this node; resolved at planning time.

Method Details

schema

Schema schema()

The output schema of this node; resolved at planning time.

children

List<PhysicalNode> children()

Direct child plans, left-to-right; empty for a PhysicalNode.Scan.

mapChildren

default PhysicalNode mapChildren(UnaryOperator<PhysicalNode> f)

Returns this node with each direct child replaced by the result of applying f to it, preserving every other component — schema, join algorithm, predicates, keys, bounds.

The structural-rewrite helper RelNode has had all along, and the same contract: this node is returned reference-identical when f returns the same reference for every child, so a rewrite can detect "nothing changed" with a == check, and a sub-tree nothing touched is shared rather than copied.

It exists because a plan is otherwise only readable, not rewritable: asking what the same query answers under a different join algorithm means rebuilding the spine above the join that changed, and the alternative is a reconstruction switch per caller — which is the shape that has twice been found silently dropping a component.

"Child" means what children() means, so the two cannot disagree: a Why's logical sub-tree and a LateralJoin's per-row body are not children of the physical plan and are carried through untouched.

Parameters:

f - the transformation to apply to each direct child; must not be null

Returns:

the rewritten node, or this if no child changed

deliveredOrdering

default Ordering deliveredOrdering()

The Ordering that this node delivers on its output stream. The default implementation returns Ordering.none() — meaning no guaranteed row order — which is the conservative safe answer for any operator that does not propagate or establish an ordering. Individual nodes that do preserve order (PhysicalNode.Select, PhysicalNode.Limit) or establish it (PhysicalNode.Sort) override this method.

Returns:

the delivered ordering; never null