All Classes and Interfaces
Class
Description
The running state of one aggregate over one group.
Represents an aggregate function in an aggregation operation.
One aggregate a library supplies: its form plus the
Accumulator that reduces a group.Aggregate function operators used in
AggregateFunction.A contract an aggregate makes with the optimizer, in the way
FunctionProperty does for scalar functions.The form of an aggregate — what the engine needs to plan a grouping before any row
is read.
Represents an aggregation operation (γ) in relational algebra.
Allen's interval algebra relations used in
IntervalJoinNode.A candidate row paired with its continuous LP allocation value, as returned by
SubsetOptimizer.allocate(com.darkcollective.relix.ast.ObjectiveSense, com.darkcollective.relix.ast.Operand, java.util.List<com.darkcollective.relix.ast.OptimizeConstraint>, double, double, java.util.List<com.darkcollective.relix.processor.Row>, java.lang.String).Specifies the continuous LP (linear-programming) allocation mode for the
OPTIMIZE ALLOCATE operator.Logical conjunction (∧) — true when both
left and right are
true.A tuple paired with its provenance annotation — the side-channel carrier of the
K-relation model.
A K-relation: a relation in which every distinct tuple carries an annotation
drawn from a
Semiring (after Green, Karvounarakis & Tannen,
PODS 2007).Represents an anti-join operation (▷).
API-key authentication: the connector sends a named key either as a request
header or as a URL query parameter.
Where an
ApiKeyAuth key is placed in the request.One argument of a
LazyScalarFunction call, not yet evaluated.Binary arithmetic operators used in
BinaryArithmeticExpression.How many arguments a function accepts — an inclusive range, with
Arity.UNBOUNDED standing for "no upper limit".Constructs a nested array value in a projection —
[ expr, expr, … ].A nested array type — an ordered collection of elements of a single
element type (which may itself be nested).A runtime array value — an ordered list of
Value elements.One downloadable JAR — a URL and its expected SHA-256 (lower-case hex) — shared by
the connector-plugin catalog (
ConnectorCatalog) and the JDBC driver catalog
a connector provider keeps (DriverCatalog, in relix-connectors-std).AS-OF join (
ASOF) — a temporal "pick the nearest right row by time"
join.Sealed interface for the right-hand side of an assignment statement.
An assignment statement — gives a name to a relational algebra expression or
an inline table.
The AST authoring surface — one factory per node kind, for tests and embedders that
build a tree directly rather than parsing one.
Structural equality over the AST — "are these two fragments the same
expression?", asked without regard to where each was written.
Utilities for working with possibly relation-qualified attribute names.
A column reference operand, optionally relation-qualified.
Sealed root for an HTTP source's authentication shorthand.
A materialised relation that preserves insertion order and allows duplicate
rows — the
Bag type in the IBM flat-collection taxonomy.Assigns the provenance annotation of a base-tuple occurrence — the
K value a ProvenanceEvaluator lifts each leaf row to before the
positive operators thread ⊕/⊗ above it.A base tuple as a
Semiring can read it — the engine's row reduced to the two
things an annotation can be built from: which tuple this is, and what it
weighs.HTTP basic authentication: the connector sends
Authorization: Basic <base64(username:password)>.Bearer-token authentication: the connector sends
Authorization: Bearer <token>.A binary arithmetic expression (
left op right) used in projections
and predicates.A boolean literal operand (
true or false).The boolean semiring
(𝔹, ∨, ∧, false, true) — plain set semantics
(a tuple is present or absent).A runtime boolean value.
Whether a relation is guaranteed finite — a logical property propagated
bottom-up over a
RelNode tree.Materialisation-safety check: a blocking operator —
one that must buffer its whole input before emitting any row — over a provably
unbounded input is a plan-time error.
Thrown at plan time when a query would materialise a provably-unbounded relation
— a blocking operator over an unbounded input, or a
hash join with no boundable build side.
Supplies the
Boundedness of a leaf relation by name — the one
piece of boundedness that is not structural but depends on what the leaf
actually is.The functions relix ships with: the scalars — string, numeric, temporal, conditional,
type-check, conversion and nested-data — and the eight aggregates.
Hook for registering built-in symbols into the symbol table before any
user-defined symbols are processed.
The semirings this module ships: boolean existence, ℕ multiplicity, tropical
shortest-path, the security lattice,
ℕ[X] lineage and cheapest-route.Builds the read-only system catalog relations — the
relix.* namespace that lets a script query the engine's own knowledge about
itself (the information_schema analogue; see ADR-0007).Supplies table metadata for database connections during semantic analysis.
Table metadata captured once and replayed later, so a session composes and
costs a query with no database in reach.
One observation of one table.
Where one entry's knowledge came from.
Transitive closure (least fixpoint) of a binary relation — the recursive
"reachability" operator.
Connected-components labelling of an undirected graph — the entity-resolution /
network-island operator.
Strings as sequences of code points — the unit relix counts, slices and orders
a string by.
Sealed interface describing how a column maps to the underlying transport.
A single column in a relation schema — its name,
Type, and optional
source-relation ColumnProvenance.Indicates whether a column spec describes an input parameter or an output value.
The source-relation origin of a schema
ColumnDefinition — which
relation a column came from, and under what name, so that a
relation-qualified reference (rooms.name) can be resolved
precisely even after a join has renamed the physical column to disambiguate a
collision.Column pruning (
PROJ-004) — narrows the rows flowing out of every base
relation to the columns the query actually reads.One entry of a
references: block on a database or connection-table
source — a foreign-key style arrow from columns of the declaring
source to columns of another relation:Describes one column in a source declaration's schema.
Per-column statistics used by the cost model to refine cardinality estimates.
Binary comparison operators used in
ComparisonPredicate.A binary comparison predicate (
left op right).What is installed in this process, for the parts of it the engine cannot see.
One installed thing.
Relational composition (∘) — composes two relations on their shared columns,
like function composition.
The uniform shape shared by every condition-carrying binary join:
(left, right, condition, location).A boolean-valued operand: a
Predicate used in operand position.A top-level
connection NAME from <type> { … } declaration.A small pool of reusable JDBC
Connections, keyed by
DatabaseConnectionConfig, so repeated scans and queries against the
same connection avoid the cost of opening a fresh physical connection each time.Turns a declared connection into a live JDBC
Connection.Configuration for a source bound to a table within a named
connection, e.g.A catalog of downloadable connector plugins — the SPI-side analogue of the JDBC
DriverCatalog.A connector plugin: the type token it provides and the artifacts to download.
A
CatalogProvider that asks the connector to describe its own tables.The raw, type-agnostic configuration for one connector-backed relation —
the key/value pairs from a
connection or source declaration,
already environment-substituted.Loads external
RelixConnector plugins from JAR files in a connector
directory — ~/.relix/connectors/ by default, overridable via
RELIX_CONNECTORS.Provisions a connector plugin on demand: when a connection names a
connectorType for which no RelixConnector is registered, this
looks the plugin up in the ConnectorCatalog, downloads its artifacts
(the connector JAR + its driver/runtime JARs, each checksum-verified) into the
connector directory, and reports the outcome — the caller then rebuilds its
ConnectorRegistry to pick up the new plugin.The result of a provisioning attempt (the caller checks the registry for "already present").
A provisioning outcome plus a human-readable explanation.
The open dispatch point for connectors — it replaces the hardcoded
CompositeDataSourceConnector switch.Consolidation functions for the
DownsampleNode time-series aggregation operator.Estimates the relative I/O cost of a
RelNode expression by
inspecting the types of its leaf relation symbols.Ordinal cost tier for a relation or sub-expression, used by
CostEstimator to rank data sources from cheapest to most expensive.The counting semiring
(ℕ, +, ×, 0, 1) — bag semantics (row
multiplicity) and, over a weighted closure, path counting.Covering-reduction node —
COVER [EXACT] t (R).Built-in
RelixConnector for local CSV files — the reference
implementation of the connector SPI.A
DataSourceConnector that reads data from local CSV files.Extracts tabular data from a CSV response body.
Configuration for a local CSV file source.
An inline table in comma-delimited CSV format.
Configuration for a named database connection — the JDBC coordinates
shared by every table referenced through it.
A relation symbol backed by an external data store — typically a database table
or view.
Configuration for a database-backed source (JDBC table or view).
Plug-in boundary between the query executor and an external data source.
Binds connection names to live JDBC
DataSource handles, so a
program can hand the engine a database it already has open.A typed calendar-date literal operand, written
DATE '2026-06-15'.A runtime calendar-date value with no time zone, backed by
LocalDate (e.g.A
def … : relation statement — defines a table-valued (relation-returning)
user-defined function.A
def statement — defines a scalar user-defined function.Answers, for a pipeline rule, whether an expression evaluates to the same relation
every time it is run.
One thing wrong with a query, as data rather than as an exception.
A SQL dialect — the database-specific surface syntax used when the planner
pushes work down as SQL.
Set difference (−) — returns tuples that appear in
left but not in
right.Shared rendering for the sub-expressions that appear inside a node label.
Optimization pass for the two
δ (DISTINCT) elimination rules: one looks
down from the δ (DIST-001), the other looks up
from it (DIST-002).Supplies whether a leaf relation is inherently duplicate-free — the one
piece of distinctness that is not structural but depends on what the leaf actually
is.
Distinct (δ) — eliminates duplicate tuples from
input.Relational division (÷) — returns tuples from
left that are associated
with every tuple in right (the relational analogue of "for all").A
Row backed by a nested StructValue document — the row shape
produced by an open (schema-on-read) source such as the JSON file
connector.Which columns a
DOWNSAMPLE consolidates, and what each one is called.One consolidated output column, and the input column reduced into it.
Time-series downsampling (DOWNSAMPLE) — groups input rows into fixed-width time
buckets and consolidates numeric columns within each bucket using the chosen
ConsolidationFunction.A catalog of downloadable JDBC drivers — the manifest that lets relix fetch a
driver it does not have locally, complementing the external driver directory.
A driver: a JDBC scheme prefix it satisfies and the artifacts to download.
Downloads driver
Artifacts into the driver directory,
verifying each against its SHA-256 before it is trusted.Provisions a JDBC driver on demand: when a connection references a database for
which no driver is registered, this looks the driver up in the
DriverCatalog, downloads it (with checksum verification) into the driver
directory, and registers it — so a database relix has never seen before just
works.The result of a provisioning attempt.
A provisioning outcome plus a human-readable explanation.
A typed duration literal operand, written
DURATION 'PT30M'.A runtime duration value — an exact elapsed span of seconds and nanoseconds,
backed by
Duration (e.g.How a
Relationship entered the schema graph.Represents element-of predicates: element ∈ set_expression or element ∉ set_expression
Used for set membership testing (equivalent to SQL IN/NOT IN).
The relation with no rows and the heading of another expression — the
∅ that a provably-unsatisfiable query collapses to.One side of a
Relationship: a relation plus the ordered columns
joined at this side, carrying numeric multiplicity bounds.One endpoint of a
RelateStatement — a relation reference plus the
ordered columns joined at this side, with optional multiplicity bounds.An
env statement — declares the environment file and active profile
used for credential and configuration variable resolution.Fills the single unknown column of a row by inverting a goal-seek equation
left = right (the engine side of the SOLVE operator).Thrown when a query cannot be evaluated at run time.
A bounded, in-memory
QueryEventListener that retains what it observes
so the feed can be read back instead of only printed.The numbers an observed decision can carry — what a
QueryEvent's text cannot say.Shared execution state threaded through all operators during query evaluation.
The readable spelling of
AstBuilders — comparisons by name, n-ary
connectives, and literals built from Java values rather than
from their source spelling.A query target that holds an inline relational algebra expression.
Binds an
OUT column to a JSONPath expression within the response body.Sealed interface describing how to extract tabular data from an HTTP response.
Fetches the bytes at a URI — the network seam for
DriverDownloader.The one answer to give me a local file for this connection, for every
connector that reads a file.
General monotone recursion — the least-fixpoint binder
FIX.Full outer join (⟗) — returns all tuples from both
left and
right; unmatched tuples on either side are padded with nulls.Represents a function call in an expression.
Every function available to a run, indexed by name.
The ambient state a function implementation may read while it runs.
A collection of functions offered to the engine — the unit that is installed,
discovered and versioned.
Optimizer hint flags that may be attached to a function symbol.
The form of a scalar function — everything the engine reasons about
before anything is evaluated.
Sealed sub-interface of
Symbol for all function-typed symbols.Reads a GEDCOM genealogy file as a pair of relations.
A code-backed leaf relation — its rows are produced by engine code rather than
read from a file or database.
A
BoundednessSource backed by a model's sources and the generator registry: a leaf
relation is Boundedness.UNBOUNDED iff it is a generator
source whose generator declares Generator.unbounded(); every other leaf
(CSV/JSON/JDBC/inline/finite generator) is Boundedness.BOUNDED.Supplies the schema of a generator source during semantic analysis
— the seam through which the analyzer learns a generator's
heading without the script declaring it (generator-owned schema).
A
DataSourceConnector that serves generator relations — leaves whose rows
are produced by engine code.A
DistinctnessSource backed by a model's sources and the generator registry: a leaf
relation is duplicate-free iff it is a generator source whose
generator declares Generator.duplicateFree() (e.g.A
MonotoneGeneratorSource backed by a model's sources and the generator registry: a leaf
relation reports an ascending value column iff it is a generator
source whose generator declares one via Generator.ascendingColumn() (the unbounded
Naturals/Primes).Configuration for a generator source — a leaf relation whose rows are
produced by engine code rather than read from a file or database.
A single grouping key of an aggregation (
γ): the Operand
expression the rows are grouped by, with an optional alias for the output
column.Binds an
IN column to an HTTP request header.Executes
source … from http { … } relations: it issues the configured
HTTP request, parses the JSON response, and yields one Row per record.The result of an HTTP exchange: the status code and the response body.
The fully-resolved request the connector wants to send.
The I/O boundary — sends a request and returns the response.
The production
Fetcher: an HTTPS-only download over
HttpClient.HTTP request method for an
HttpSourceConfig.Configuration for an HTTP/REST API source.
Delimited-identifier rendering for round-trippable pretty-printing.
Directed dependency graph of all
.relix files reachable from a root.Classifies the kind of symbol being imported in an
ImportStatement.An
import statement — brings symbols from another .relix
file into the current namespace.A materialised relation whose rows are partitioned into groups by a
composite key — the
Relation type in the IBM flat-collection
taxonomy (Key, Element Equality, Unordered, Multiple).A relation whose rows are declared inline in a
.relix source file,
typically as a Markdown table.Sealed root interface for inline relation data embedded in a script.
An assignment body that holds an inline data table (Markdown or CSV format).
A
ScriptLoader that serves pre-parsed Scripts from an
in-memory map, keyed by path string.An in-memory implementation of
SymbolTable suitable for single-session,
in-process use.Set intersection (∩) — returns tuples that appear in both
left and
right.Interval join (
IJOIN) — a temporal join over two interval-valued
relations using an Allen's interval algebra relation.Produces a concise human-readable IR report from a
SemanticModel.Replace-each-round iteration — the binder
ITERATE.When an
IterateNode stops.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.ROUNDS n — apply the step exactly n times; ROUNDS 0
is the base unchanged.UNTIL STABLE MAX n ROUNDS — stop at the first round whose output
equals its input.A
CatalogProvider that introspects table schemas from a live database
over JDBC, used when a connection.table reference declares no schema.A
DataSourceConnector that reads connection-backed tables over JDBC.Learns provisional
EdgeOrigin.LEARNED schema-graph edges from the
joins a user actually writes.One connected join path through the
SchemaGraph: an ordered set of
Relationship edges spanning a set of terminal relations, plus the
relations those edges touch.Assembles the join a request needs from the schema graph instead of trusting
the model's guess — the first producer of a
JoinResolution.What resolving the joins in an expression over a
SchemaGraph came to: the
engine's own assembly of the join from the relationships the graph records, rather
than the conditions the expression was written with.One enumerated join, distinguished by relationship name — the ambiguity is
speakable only because edges are named.
Several equally minimal paths; each
JoinResolution.Alternative is a runnable program.Multiplicity facts of a chosen path: whether the join fans
out (an endpoint admits more than one match, repeating rows) and whether an
inner join may drop rows (an endpoint's
min is zero).The graph could not improve on the model's program; it stands unchanged.
A unique path was assembled into
program with its bounds.Optimization pass that converts Cartesian products with selections into
theta joins, and pushes one-sided selections into join inputs
(
JOIN-001 and JOIN-002).Which input of a binary join owns an attribute reference.
Extracts tabular data from a JSON response body.
A
DataSourceConnector that reads rows from a local JSON file as
open (schema-on-read) documents — the first native nested-data source.Transport configuration for a local JSON file source.
A minimal, dependency-free JSON parser producing plain Java objects — the
reading counterpart to
JsonWriter, for callers that want a document
back rather than a typed domain object.JSON string-literal escaping — the single source of truth for turning a Java
String into a quoted, correctly-escaped JSON string.Parses JSON text into the relix
Value hierarchy — the boundary at which
a nested document becomes native relix data:
object → StructValue
array → ArrayValue
string → StringValue
number → NumberValue (a BigDecimal)
true/false → BooleanValue
null → NullValue
Thrown when the input is not well-formed JSON.
A minimal, dependency-free streaming writer for JSON text.
Thrown when the
ScriptParser encounters a syntax error in a
.relix source file.A single token produced by the
LangLexer.All token types produced by the
LangLexer for the relix scripting language.Optimization pass that decorrelates an uncorrelated
LATERAL join —
one whose table-valued-function arguments never reference the outer row
(LATERAL-001).A correlated / lateral table-valued function application that produces one
sub-relation per row of its left input.
A scalar function that decides which of its arguments to evaluate — a special form.
Left outer join (⟕) — returns all tuples from
left, paired with
matching tuples from right; unmatched left tuples are padded with
nulls.Tokenizes a relational algebra expression string into a stream of
Tokens consumed by RelAlgebraParser.Translation of a SQL
LIKE pattern into an anchored regular expression.Represents a limit operation (λ) in relational algebra.
One linear program: an objective to maximise or minimise over a list of decision
variables, subject to a list of linear constraints over the same variables.
One linear constraint:
Σ coefficients[i]·x[i] related to bound.How a constraint's weighted sum relates to its bound.
Whether the objective is to be maximised or minimised.
One decision variable: a value in
[lower, upper] contributing
weight per unit to the objective.Reads a web server's access log as a relation:
connection X from log { … }.Serializes a logical relational-algebra tree to JSON, annotating every node
with its inferred
Schema.An inline table in pipe-delimited Markdown format.
Describes the output materialisation strategy of a relational algebra node.
A relation that has been fully materialised into an in-memory collection.
A monomial in the polynomial-lineage semiring
ℕ[X] — a
product of provenance variables with positive integer
exponents (a multiset of variables).Supplies, for a leaf relation, the column on which it is a
monotone-ascending unbounded generator — the one fact the optimizer needs to
decide that an upper-bound selection (
n < k) can be folded into the
producer as a termination stop (GEN-001).A query target that references a previously declared symbol by name.
A
Semiring together with the names it answers to and a line describing it —
one entry in the registry a --provenance request is resolved against.Natural join (⋈) — joins two relations on all attributes with the same name,
projecting away the duplicate join columns.
Naturals — the canonical infinite leaf: the
natural numbers ℕ₀ 0, 1, 2, 3, … in a single column n:NUMBER.Which of a join's two inputs a dotted reference reaches into.
Which side of a join a nested path belongs to.
Thrown at plan time when a query needs a mathematical-programming solver and none
is installed.
Logical negation (¬) — true when
predicate is false.Controls where
NULL values appear when a column is used as a sort key.Represents a null predicate (IS NULL or IS NOT NULL) in relational algebra.
The absent (SQL
NULL) value, compatible with all scalar types.A numeric literal operand, stored as its original string representation.
A runtime numeric value, stored as an arbitrary-precision
BigDecimal.The optimisation direction of an
OptimizeNode: whether the objective is
to be maximised or minimised.Row counts a previous run actually produced, keyed by the expression that produced
them.
The offset window functions carried by a
WindowFunction.OffsetWindow.The shipped
MathProgrammingSolver: ojAlgo's deterministic branch-and-bound.Root sealed interface for scalar value expressions used in projections and
predicates.
Formats an
Operand expression as a
Unicode relational algebra string.Visitor over the
Operand sealed hierarchy.Centralised operator-property classification consulted by
PropertyDeriver, OrderDeriver, BoundednessChecker,
and CostEstimator.Enumeration of every transformation rule the query optimizer can apply.
Mutable accumulator for
TransformationRecords produced during a
query optimization run.The optimizer's rule registry and its bounded fixpoint driver.
One group of rules, applied in order and re-applied while they keep making
progress.
The immutable result of optimizing a single query's
RelNode tree.A single query-optimization transformation rule.
A single linear constraint of an
OptimizeNode:
SUM(expr) op bound.Declarative optimisation (OPTIMIZE) — the goal-seeking sibling of
γ.A sort ordering — the sequence of (column, direction) keys by which a relation's
rows are ordered.
Logical disjunction (∨) — true when at least one of
left or
right is true.Outer-join demotion (
JOIN-004) — turning an outer join into a less outer one
when a filter above it makes the padded rows unreachable.Outer-union (⊔) — a schema-reconciling merge of two relations that need
not be union-compatible.
Maps a logical pagination concept to a URL query parameter.
Declares how an HTTP source's pagination maps to URL parameters.
Represents a pairwise universal semi-join (USEMI), the ∀ dual of semi-join (⋉).
A single parameter in a function signature: a scalar, or — for a table-valued
function only — a relation.
Thrown by
RelAlgebraParser when the input does not conform to the
relational algebra grammar.The registry entry for one optimizer pass — an
OptimizationRule whose
PassRule.apply(com.darkcollective.relix.ast.RelNode, java.lang.String, com.darkcollective.relix.semantic.SchemaAnnotations, com.darkcollective.relix.optimizer.internal.OptimizationContext) delegates to that pass.An element of the cheapest-route semiring
PathCostSemiring — a path's
minimum cost and the set of co-cheapest routes
that achieve it.The cheapest-route semiring
((ℝ ∪ {+∞}) × ℘(Route), ⊕, ⊗, (+∞, ∅), (0, {ε}))
— the combined cost-and-witness algebra: a single weighted
closure run carries both a path's
cheapest cost and the route(s) achieving it.Bounded variable-length path reachability — the RA-native graph-traversal
operator.
Binds an
IN column to a URL path segment.The outcome of a
SchemaGraphSearch over a set of terminal relations, one of three shapes:
Unique (PathSearchResult.unique()) — exactly one minimal path spans the
terminals, and no terminal was unreachable.Represents a pattern-matching predicate:
operand LIKE pattern or
operand NOT LIKE pattern.Aggregation (γ) — groups by
groupingKeys and reduces each group
with aggregates.AS-OF join — a temporal "pick the nearest right row by time" join.
Bernoulli sampling (SAMPLE p [SEED n]): keeps each row of
input
independently with probability probability.Which input a join materialises (hashes, or buffers for nested-loop).
Transitive closure (least fixpoint) of the
input edge relation over
PhysicalNode.Closure.fromColumn()/PhysicalNode.Closure.toColumn().Connected-components labelling (CLUSTER) of the
input edge relation,
read as undirected edges over PhysicalNode.Cluster.fromColumn()/PhysicalNode.Cluster.toColumn().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.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.Distinct (δ) — eliminates duplicate rows.
Time-series downsampling (DOWNSAMPLE): groups input rows into fixed-width
time buckets and consolidates numeric columns using the chosen
ConsolidationFunction.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.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.Interval join — tests each pair of rows against an Allen interval
algebra relation.
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.A join of any kind, carrying the chosen physical strategy.
How a join is executed.
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.The join flavour.
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.Limit (λ) — takes a prefix of the input; preserves the input's delivered ordering.
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).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().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).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 enclosing
PhysicalNode.Fixpoint or PhysicalNode.Iterate.Relation/column rename — a metadata-only relabel to
PhysicalNode.Rename.schema().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).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 (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.The set-operation flavour.
Goal-seek (SOLVE): for each row of
input, fills the single NULL
column participating in the equation left = right by 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 (by
groupingAttributes) keeps
the count rows highest by sortSpecs, after skipping
offset.Optimal-path extraction (TRACE) over the
input weighted edge relation, read
as directed edges or, when PhysicalNode.Trace.undirected(), as undirected ones.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).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).Unnest (μ) — explodes the array-valued
column into one row per
element; outer keeps 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 in
nameColumn (STRING) and the cell value in valueColumn
(ANY).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.Window (ROLLING / WINDOW): adds one computed column (
outputColumn) to
every input row, partitioned by partitionKeys and ordered within each
partition by sortSpecs.Callback that receives one query's planned
PhysicalNode, without
executing it.Serializes a physical
PhysicalNode plan to JSON.Renders a
PhysicalNode plan as an ASCII tree for --explain.Row-pivoting operator (PIVOT) — spreads distinct values of a key column into
new columns.
Callback that receives one query's physical plan, rendered as text.
The estimated row count the planner computed for each node of a physical plan —
the numbers behind
Planner.buildSide and the merge-versus-hash choice,
kept so :explain can show them.A physical plan together with the row estimates the planner computed for it.
Translates an optimised logical
RelNode tree into an executable
PhysicalNode plan, fixing every physical decision up front:
Join algorithm — PhysicalNode.JoinAlgorithm.MERGE when at least one input
already delivers an ordering satisfying the join keys (the other gets a
PhysicalNode.Sort enforcer inserted); PhysicalNode.JoinAlgorithm.HASH
when an equi-join key exists but neither input is sorted; otherwise
PhysicalNode.JoinAlgorithm.NESTED_LOOP.A provenance polynomial — an element of the lineage semiring
ℕ[X].The provenance-polynomial semiring
ℕ[X] — full why-provenance
(which input tuples produced a result, and how they were combined), after Green,
Karvounarakis & Tannen (PODS 2007).Root sealed interface for boolean filter conditions.
Utility that collects all
AttributeOperand names referenced anywhere
in a Predicate tree.Formats a
Predicate as a Unicode
relational algebra string.Utilities for taking a
Predicate tree apart and putting it back
together.Validates attribute references and function calls within a predicate tree.
Visitor over the
Predicate sealed hierarchy.Serialises a
RelNode tree to a Unicode
relational algebra string.Primes — the conceptual driver of the generator story: the prime
numbers 2, 3, 5, 7, 11, … in a single column n:NUMBER, in ascending
order.A production stop folded into a monotone generator leaf by the optimizer's
SelectionIntoGeneratorPass (GEN-001).Cartesian product (×) — returns every combination of a tuple from
left
with a tuple from right.Represents a projected attribute in a projection operation.
Projection (π) — selects a subset of attributes from
input,
optionally computing new expressions or renaming columns.Derives
RelationProperties for a RelNode tree bottom-up,
purely structurally — from each operator's semantics and its children's
properties — with no schema or symbol-table lookup.Records whether a symbol was provided by the runtime or declared by a user.
Callback that receives one query's result as an annotated
K-relation.Evaluates a logical
RelNode tree as a K-relation,
threading a chosen Semiring through the positive-algebra operators
This is the bridge from the engine's ordinary Stream<Row> evaluation
to the annotated model.A provenance variable — the token identifying one base-tuple occurrence in the
polynomial-lineage semiring
ℕ[X] (after Green,
Karvounarakis & Tannen, PODS 2007).What a renderer needs to know about functions: which ones exist, and — for the ones
that are constant for a run — what this run's ambient state says they are.
How a function call is written in a backend that could evaluate it itself.
The backend a call is being rendered for, named in a way the SPI can carry without
knowing anything about query planning.
A read-only positional view over a left row concatenated with a right row, used
to evaluate a join condition with correct handling of qualified
attribute references.
The relation names an expression's columns answer to as qualifiers.
An assignment body that holds a parsed relational algebra expression.
One observed decision in the query pipeline — a rule that fired in the
optimizer, or a physical choice the planner made.
Which part of the pipeline an event came from.
Receives
QueryEvents as the optimizer and planner make decisions.Thrown when a query started and did not finish.
Top-level orchestrator that drives query execution against a validated
SemanticModel.Entry point for the Relix query optimizer.
Binds an
IN column to a URL query parameter.A named relational algebra expression — essentially a stored view.
The fully-materialised result of executing a single
query statement.A
query statement — produces output from a named symbol or an
inline relational algebra expression.Sealed interface for the argument of a
query statement.Range(lo, hi[, step]) — a finite arithmetic series, the generate_series
workhorse.The ranking window functions carried by a
WindowFunction.RankingWindow.An occurrence of a
FIX-bound recursive relation name inside the body of
its enclosing FixpointNode.Optimization pass that eliminates a redundant outer aggregation stacked
directly on top of another aggregation (
AGG-001).One page of the language reference, as
Relix.referencePages() lists it.The outcome of a
SymbolTable.register(com.darkcollective.relix.symbol.Symbol)
call.Recursive-descent parser for relational algebra expressions.
Validates structural and semantic constraints over a single relational
algebra expression tree.
A standalone schema relationship declaration:
A relation — an expression together with the analysis it resolves against.
Answers one question about a named relation: is it finite? — the
extent of
relix.relations.boundedness.Answers one question about a relational expression: would evaluating it twice
necessarily give the same relation?
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.
A table-valued function symbol — a relation-returning user-defined function.
Fluent builder for
RelationFunctionSymbol.A base relation (table) reference — a leaf node in the relational algebra tree.
Logical properties of a relation, derived bottom-up over a
RelNode tree and consumed by the optimizer
and planner.A named relationship edge of the
SchemaGraph.Optimizer-facing statistics about a relation — cardinality and structural
metadata gathered from a data source (e.g.
Sealed sub-interface of
Symbol for all relation-typed symbols.A Relix session — the environment relations resolve against, and the entry point to
the embedding API.
Assembles a
Relix session.The plug-in boundary for an external data source — the open seam that replaces
the closed CSV/JSON/JDBC dispatch.
Loads JDBC drivers from JAR files in an external driver directory,
rather than bundling them into the executable at build time.
Thrown when text will not parse, or a relation will not analyse against its session.
Root sealed interface for all relational algebra operation nodes.
Executes a logical relational algebra
RelNode tree.The operand-level counterpart of
RelNode.children(): a single, exhaustive
registration point for the Operand and Predicate expressions each
RelNode carries directly.Visitor over the
RelNode sealed hierarchy.Rename elimination (
RENAME-001 … RENAME-004) — the cleanup pass that
runs immediately after ViewInliner.Rename (ρ) — renames a relation and optionally reassigns its attribute names.
A single
old → new column rename within the pair form.Reservoir (fixed-count) sampling (SAMPLE … ROWS) — keeps exactly
count
rows of input, chosen uniformly at random without replacement.What a call site's function name resolved to — the symbols visible to the rest of
the pipeline, and the catalogue definition behind them when there is one.
Right outer join (⟖) — returns all tuples from
right, paired with
matching tuples from left; unmatched right tuples are padded with
nulls.One derivation (path) carried by the cheapest-route semiring
PathCostSemiring — the set of edge tokens traversed.The result of one run — the rows, their heading, and what the engine did to produce
them.
Callback that receives one query's result as a lazy
Stream of rows.Bernoulli sampling (SAMPLE) — independently keeps each row of
input
with probability probability (a fraction in [0, 1]).What a session lets its users reach, and how much work one query may do.
Assembles a closed sandbox.
A closed
Sandbox refused what a session was given: an external declaration
the sandbox does not permit, or text longer than its input limit.One scalar function a library supplies: its form plus
the processing behind it.
A scalar function symbol — a function that accepts zero or more scalar arguments
and returns a single scalar value.
Fluent builder for
ScalarFunctionSymbol.The scalar-value type lattice used for column types, function parameter types,
and function return types.
The structural description of a relation — an ordered list of named, typed columns.
How the analyser records a node's schema in a
SchemaAnnotations.Records
schema as node's schema in annotations.The schema graph: an immutable set of
Relationship edges between
relations.Minimal-path (Steiner-tree) search over a
SchemaGraph.Public facade for running schema inference over an arbitrary
RelNode tree outside the full five-phase analysis pipeline.Orchestrates the schema-inference pass (Phase 4 of semantic analysis).
Infers the output
Schema of every node in a relational algebra tree.Serializes a
Schema to JSON, shared by the logical-plan
(LogicalPlanJson) and physical-plan
(relix-plan's PhysicalPlanJson) serializers so the encoding is
defined once.The root AST node for a parsed
.relix script file.The
Script authoring surface — the statement-level half of the AST contract,
for tests and embedders that assemble a whole script without the .relix grammar.Strategy for resolving a path to a
Script — the engine's pluggable
"where does a Script come from" seam.Thrown when a frontend cannot turn its input into a
Script.Recursive-descent parser for
.relix scripting language source files.The security / access-control lattice semiring over
SecurityLevel
(min, max) — propagates a confidentiality (clearance) level through a
query so each output tuple carries the level at which it may be released.A confidentiality / clearance level, ordered from least to most restrictive —
the carrier of the
SecurityLattice semiring.The predicate that keeps exactly the rows a selection drops.
Partition-pruning pass (ADR-0020) for the two time-series operators
(
SESSION-001 / DOWNSAMPLE-001).Cleanup pass that puts selections back together — the two rules that turn several
filters into one.
Selection (σ) — filters the tuples of
input to those satisfying
predicate.Optimization pass that moves selections (
σ) closer to their source
relations, reducing the number of tuples flowing through intermediate
operators (SEL-003..009).Optimization pass that decomposes every conjunctive selection predicate into
two stacked selections, enabling each factor to be pushed independently
(
SEL-001).Entry point for semantic analysis — the engine's front door.
A single diagnostic produced during semantic analysis of a
.relix script.The validated in-memory representation produced by a successful (or
partially-successful) semantic analysis run.
The outcome of a semantic analysis run.
Orchestrates the validation pass (Phase 5 of semantic analysis).
Represents a semi-join operation (⋉).
A commutative semiring
(K, ⊕, ⊗, 0, 1) — the pluggable extension point
of the provenance / K-relation framework.Which semirings are installed — the bundled six plus every one a discovered
SemiringLibrary offers, resolved by name.A provider of semirings — the extension point through which an
annotation algebra the engine has never heard of becomes something a query can ask for
by name.
Resolves a
Semiring by name — the lookup the surfacing layer uses to turn a
--provenance=<name> request into a concrete semiring without the caller
hard-wiring the singletons.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.Represents a set literal like {1, 2, 3} or {"active", "pending"}
Used in element-of predicates for set membership testing.
A materialised relation that contains only unique rows, preserving the
order in which rows were first inserted — the
Set type in the
IBM flat-collection taxonomy (No Key, Element Equality, Unordered, Unique).Severity level of a
SemanticError.Governs what happens when a new symbol is registered under a name that is
already occupied in the same namespace.
Goal-seek (SOLVE) — a per-row operator that fills a single unknown column by
inverting a declared arithmetic equation
left = right.The installed
MathProgrammingSolvers, discovered with
ServiceLoader.What a solver has to say about a
LinearProgram: it found an optimum, it
proved there is none, or it did not decide.The program is proved infeasible — no assignment satisfies its
constraints.
An optimal assignment.
The search did not decide: it failed, hit a limit, found the program
unbounded or malformed, or stopped for any other reason short of an answer.
Sort direction used in a
SortSpecification.A materialised relation whose rows are kept in a stable sorted order and
may contain duplicates — the
Sorted bag type in the IBM
flat-collection taxonomy (No Key, No Element Equality required, Sorted,
Multiple).Represents a sort operation (τ) in relational algebra.
A single sort key: the
Operand expression to order by, the direction
(SortDirection.ASC / SortDirection.DESC), and the implicit
NULL placement.Sealed root interface for the transport configuration of a source declaration.
A
source declaration — names a virtual relation backed by an
external data source.The source location of an AST node — file path, 1-based line, and 1-based
column of the first character of the construct.
A structured, machine-readable identity for one base-tuple occurrence — the
data a
ProvenanceVariable carries so a consuming tool can pinpoint
which row of which relation a lineage variable stands for.A relation symbol backed by an external data source whose transport details
(HTTP, CSV file, etc.) are held outside the symbol table.
Sealed root interface for every top-level declaration in a
.relix script.A
DistinctnessSource that reads duplicate-freeness off a leaf relation's
declared keys — the base-relation half of the seam, complementing the
generator-backed source that covers Range/Naturals/Primes.Supplies
RelationStatistics for a leaf relation by name, the seam
through which the CostEstimator obtains cardinality metadata.A scalar function whose arguments are all evaluated before it is called — the
ordinary kind.
A string literal operand.
A runtime string value.
Constructs a nested struct value in a projection —
{ name: expr, … }.A single struct field: a name paired with its value expression.
A nested struct type — an ordered set of named, typed
StructType.Fields.A single named, typed field of a
StructType.A runtime struct (nested object) value — an ordered map of field name to
Value.Chooses the optimal subset of a group's rows under a linear objective
and linear constraints — the 0/1 knapsack / portfolio-selection problem behind
the
OPTIMIZE operator.Root sealed interface for every named entity registered in a
SymbolTable.Performs the symbol-collection pass over all files reachable from the root.
A non-fatal diagnostic produced during symbol registration.
Classification of symbol registration errors.
Persistence contract for symbol storage — the extension point for a durable
back-end (relational database, document store, etc.).
A mutable, namespace-scoped registry of
Symbol instances.Symmetric difference (∆) — returns tuples that appear in exactly one of
left or right, but not in both, eliminating duplicates.A read-only system catalog relation in the reserved
relix.* namespace.The absolute temporal distance between two values — the metric that
complements
ValueComparator's order, for the operators that bound how
far apart two rows may be (the AS-OF join's WITHIN tolerance).Parses the ISO-8601 payloads of the typed temporal literals
(
DATE '…', TIME '…', TIMESTAMP '…',
DURATION '…') into the java.time values carried by
DateOperand, TimeOperand, TimestampOperand, and
DurationOperand.Theta join (⨝) — inner join that keeps only tuples satisfying
condition.Tie-break rule for AS-OF join (
ASOF) when multiple right rows
share the nearest match value.A typed wall-clock time-of-day literal operand, written
TIME '13:40:00'.A typed timestamp literal operand, written
TIMESTAMP '2026-06-15T13:40:00Z'.A runtime timestamp value — an absolute point on the timeline, UTC-normalised,
backed by
Instant (e.g.A runtime wall-clock time-of-day value with no time zone, backed by
LocalTime (e.g.A run of
.relix text and what kind of token it is, as Relix.tokens(java.lang.String)
reports it.An immutable token produced by the
Lexer.What a
Token is, in the handful of categories a syntax highlighter colours.Syntactic categories recognised by the
Lexer.Top-k per group (TOP) — partitions
input by groupingAttributes
and, within each group, keeps the count highest rows by
sortSpecs (after skipping offset rows).Physical algorithm choice for a
PhysicalNode.Trace optimal-path operator.Optimal-path extraction over a directed, weighted graph — the cheapest (or longest)
path finder.
An immutable record of a single optimization transformation applied during
query planning.
Transitive equality propagation (
EQ-001) — the law that turns a one-sided
filter into a filter on both sources.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.The tropical (min-plus) semiring
(ℝ ∪ {+∞}, min, +, +∞, 0) — the
cheapest-derivation algebra, i.e.A nullary truth relation literal — a leaf node denoting one of the two
relations whose heading is the empty (closed, zero-column) schema.
One row of a result, read as Java types.
The type of a value in relix — a scalar, a nested struct, or an array.
Represents a unary operation applied to an operand.
Thrown when a terminal that must collect every row is asked for one that never ends.
Multiset union (⊎) — returns all tuples from both
left and
right, preserving duplicates (equivalent to SQL UNION ALL).Set union (∪) — returns tuples that appear in
left, right,
or both, eliminating duplicates.Group-wise universal quantification (∀) — partitions
input by the
groupingAttributes and keeps the grouping-key tuple of each group in
which every row satisfies predicate.Unnest (μ) — explodes an array-valued column into one row per element,
carrying the other columns through (≈ SQL
LATERAL UNNEST, Mongo
$unwind).Column-folding operator (UNPIVOT) — transforms selected columns into rows.
A runtime scalar value produced or consumed during query execution.
Total ordering over
Value instances for use in sort and
aggregation operators.Null-propagating navigation into nested
Values — the runtime engine
behind path access like user.name or items[0].price.A single navigation step: into a named struct field, or an array index.
Navigate into the struct field named
name (case-insensitive).Navigate into the array element at zero-based
index.Expands references to named views into the views' bodies, so that the rule
passes can optimise across former view boundaries (e.g.
Why (ω) — reifies the lineage provenance of
input as queryable data.The scope of rows fed to a
WindowFunction within a partition.A trailing
n-row sliding window — OVER n ROWS — equivalent to
SQL's ROWS BETWEEN n-1 PRECEDING AND CURRENT ROW.The cumulative (running) frame —
OVER ALL ROWS — equivalent to SQL's
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW.The full-partition frame used implicitly by ranking and offset functions —
equivalent to SQL's
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED
FOLLOWING.The computation a
WindowNode performs per row.A sliding / cumulative aggregate over an
Operand argument — the same
AggregateOperator + Operand pair used by γ.An offset function (slice 4).
A ranking function (slice 3).
Window operator — a non-collapsing per-partition computation that
adds one column to every input row without removing or merging any.