Module com.darkcollective.relix.function

Package com.darkcollective.relix.function

package com.darkcollective.relix.function

The function SPI — how a library of scalar functions and aggregates is described to the engine, and how the engine finds one.

The split this package draws is between a function's form and its processing. The form — name, parameters, arity, return type, purity, the spelling a backend would understand — is what the engine reasons about while it is checking a script, rewriting it and planning it. The processing is the lambda that turns arguments into a value. Sin and Cos have the same form; nothing in analysis or planning is served by knowing which of them a call names.

So the engine holds the form and a library supplies the processing:

• FunctionSignature and AggregateSignature describe a function; Arity is how many arguments it takes, checked by the engine so an implementation never counts its own.
• ScalarFunction pairs a signature with an implementation — StrictScalarFunction for the ordinary kind, LazyScalarFunction for a special form that chooses which arguments to evaluate. AggregateFunction does the same for a reduction, through an Accumulator per group.
• PushdownSpelling is how a call is written for a backend that could evaluate it itself, so a library ships its implementation and its SQL together and declining is always safe.
• FunctionLibrary is the unit that is installed and discovered; FunctionCatalog indexes what was found.

Nothing here is privileged. The library the engine ships with is discovered by the same mechanism, described by the same records and reached through the same catalogue as one written elsewhere, so anything a built-in function does is available to any function.

What the SPI deliberately does not open is the set of value types: a library adds functions over Value, not new kinds of value. A domain type is carried as a struct with a discriminating field, with the library's own functions over it.

Related Packages

Module	Package	Description
com.darkcollective.relix.function.builtin	com.darkcollective.relix.function.builtin	The default function library: one definition per built-in scalar function, carrying its form and its processing together.

Class	Description
Accumulator	The running state of one aggregate over one group.
AggregateFunction	One aggregate a library supplies: its form plus the Accumulator that reduces a group.
AggregateProperty	A contract an aggregate makes with the optimizer, in the way FunctionProperty does for scalar functions.
AggregateSignature	The form of an aggregate — what the engine needs to plan a grouping before any row is read.
Argument	One argument of a LazyScalarFunction call, not yet evaluated.
Arity	How many arguments a function accepts — an inclusive range, with Arity.UNBOUNDED standing for "no upper limit".
FunctionCatalog	Every function available to a run, indexed by name.
FunctionContext	The ambient state a function implementation may read while it runs.
FunctionLibrary	A collection of functions offered to the engine — the unit that is installed, discovered and versioned.
FunctionSignature	The form of a scalar function — everything the engine reasons about before anything is evaluated.
LazyScalarFunction	A scalar function that decides which of its arguments to evaluate — a special form.
PushdownSpelling	How a function call is written in a backend that could evaluate it itself.
PushdownTarget	The backend a call is being rendered for, named in a way the SPI can carry without knowing anything about query planning.
ScalarFunction	One scalar function a library supplies: its form plus the processing behind it.
StrictScalarFunction	A scalar function whose arguments are all evaluated before it is called — the ordinary kind.