Package com.darkcollective.relix.plan
package com.darkcollective.relix.plan
The physical plan: what the engine will run.
PhysicalNode is the plan tree, one record per
physical operator. PlanEstimates carries each
node's estimated row count beside the tree rather than inside it, and
PlannedQuery pairs the two, as
Relation.plan() returns them.
-
ClassDescriptionAggregation (γ) — groups by
groupingKeysand reduces each group withaggregates.AS-OF join — a temporal "pick the nearest right row by time" join.Bernoulli sampling (SAMPLE p [SEED n]): keeps each row ofinputindependently with probabilityprobability.Which input a join materialises (hashes, or buffers for nested-loop).Transitive closure (least fixpoint) of theinputedge relation overPhysicalNode.Closure.fromColumn()/PhysicalNode.Closure.toColumn().Connected-components labelling (CLUSTER) of theinputedge relation, read as undirected edges overPhysicalNode.Cluster.fromColumn()/PhysicalNode.Cluster.toColumn().Constructive covering reduction (COVER, constructive mode): builds candidate rows value-by-value over thePhysicalNode.ConstructiveCover.factorsdomains, usingPhysicalNode.ConstructiveCover.conjunctsas a validity oracle, never materialising the full Cartesian product.Covering reduction (COVER): keeps a near-minimal subset ofinputrows such that every distinct t-column value combination (PhysicalNode.Cover.strength-way tuple) occurring in the input occurs in the output.Distinct (δ) — eliminates duplicate rows.Time-series downsampling (DOWNSAMPLE): groups input rows into fixed-width time buckets and consolidates numeric columns using the chosenConsolidationFunction.Produces no rows at all, underschema's heading — the physical form ofEmptyRelationNode, planted by the optimizer where a sub-tree was proved unsatisfiable.General monotone recursion (FIX): computes the semi-naïve least-fixpoint ofPhysicalNode.Fixpoint.step()seeded byPhysicalNode.Fixpoint.base(), with the relation namedPhysicalNode.Fixpoint.name()bound to the current delta during each step evaluation.Interval join — tests each pair of rows against an Allen interval algebra relation.Replace-each-round iteration (ITERATE): evaluatesPhysicalNode.Iterate.base(), then evaluatesPhysicalNode.Iterate.step()with the relation namedPhysicalNode.Iterate.name()bound to the previous round's whole output, replacing it each round, untilPhysicalNode.Iterate.stop()is satisfied.A join of any kind, carrying the chosen physical strategy.How a join is executed.Equi-join key columns:left.get(i)andright.get(i)are the positions, in the left and right inputs, of thei-th equated column pair.The join flavour.Lateral / correlated table-valued function join: for each row ofPhysicalNode.LateralJoin.left(), evaluates thePhysicalNode.LateralJoin.arguments()in that row's context, binds them into the function body viaPhysicalNode.LateralJoin.bodyBuilder(), plans the instantiated body, and concatenates the left row with each row the body produces.Limit (λ) — takes a prefix of the input; preserves the input's delivered ordering.Declarative optimisation (OPTIMIZE): within each group (bygroupingKeys) either selects the optimal subset (MIP, whenallocationis empty) or assigns continuous allocations (LP, whenallocationis present).Bounded variable-length path reachability (PATH) over theinputedge relation, read overPhysicalNode.Path.fromColumn()/PhysicalNode.Path.toColumn()as directed edges, or as undirected ones whenPhysicalNode.Path.undirected().Rows-to-columns rotation (PIVOT): groups the input by the optionalgroupKeys, then turns each distinct value ofkeyColumninto a new output column whose cell is the correspondingvalueColumncell (NULL when the group has no row for that key).A leaf that pushes a relational sub-expression down to a connector as a single native query.A reference to the relation bound by an enclosingPhysicalNode.FixpointorPhysicalNode.Iterate.Relation/column rename — a metadata-only relabel toPhysicalNode.Rename.schema().Reservoir (fixed-count) sampling (SAMPLE … ROWS [SEED n]): keeps exactlycountrows ofinput, chosen uniformly at random without replacement (or the whole input when it has fewer rows).Reads a base relation: inline rows, or an external source/database via the connector.Selection (σ) — streaming row filter; preserves the input's delivered ordering.Gap-and-island / sessionization (SESSIONIZE): within each partition (bypartitionKeys) orders rows ascending byorderColumnand appends a 1-based session-id column (sessionColumn), incremented whenever the gap to the prior row exceedsthreshold.The set-operation flavour.Goal-seek (SOLVE): for each row ofinput, fills the single NULL column participating in the equationleft = rightby inverting the arithmetic.Sort (τ) — establishes ordering on its sort keys.Marks a sub-plan whose rows are computed once and read by more than one consumer.Top-k per group: within each partition (bygroupingAttributes) keeps thecountrows highest bysortSpecs, after skippingoffset.Optimal-path extraction (TRACE) over theinputweighted edge relation, read as directed edges or, whenPhysicalNode.Trace.undirected(), as undirected ones.Adjacency-to-forest nesting (TREE): folds the adjacency relationinput(with node keykeyColumnand parent keyparentColumn) into a forest of nested documents — one output row per root, each carrying its subtree in the appendedchildrenColumnarray (siblings ordered byorderSpecs, empty = input order).Group-wise universal quantification (∀): keeps the grouping-key tuple of each group in which every row ofinputsatisfiespredicate(strict NULL semantics — an UNKNOWN row disqualifies its group).Unnest (μ) — explodes the array-valuedcolumninto one row per element;outerkeeps a NULL-bound row when the array is empty/missing.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 innameColumn(STRING) and the cell value invalueColumn(ANY).Lineage reification (WHY): emits every result tuple of its input unchanged plus the reservedprovenance:ANYcolumn holding that tuple's lineage polynomial as a nested document.Window (ROLLING / WINDOW): adds one computed column (outputColumn) to every input row, partitioned bypartitionKeysand ordered within each partition bysortSpecs.The estimated row count the planner computed for each node of a physical plan — the numbers behindPlanner.buildSideand the merge-versus-hash choice, kept so:explaincan show them.A physical plan together with the row estimates the planner computed for it.Physical algorithm choice for aPhysicalNode.Traceoptimal-path operator.