Module com.darkcollective.relix.function
Package com.darkcollective.relix.function

Interface ScalarFunction

All Known Subinterfaces:
LazyScalarFunction, StrictScalarFunction
public sealed interface ScalarFunction permits StrictScalarFunction, LazyScalarFunction
One scalar function a library supplies: its form plus the processing behind it.

The hierarchy is sealed over exactly two ways of receiving arguments, so the engine dispatches on a switch the compiler can check for completeness:

  • StrictScalarFunction — every argument is evaluated before the call. This is what a function wants unless it has a reason not to.
  • LazyScalarFunction — arguments arrive as deferred Arguments, and one that is never asked for is never evaluated. This is what makes a conditional usable as a guard: the branch not taken may be an expression that would fail on this row.

Both are non-sealed, so implementing either is open to any library; it is the choice between them that is closed.

The engine checks the declared Arity before invoking, so an implementation may read the arguments its signature allows without counting them first.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Set<ScalarType>
    argumentTypes(int index)
    The types the argument at index may have, for analysis to accept a call before it runs.
    default Optional<Blocking>
    blocking(Blocking.Bound bound, BigDecimal threshold)
    How to find, among many values, the few that a call compared against a constant could accept — so that a join on F(left.x, right.y) >= t need not call F on every pair.
    default String
    name()
     
    default PushdownSpelling
    pushdown()
    How this function is spelled in a backend that could evaluate it itself.
    default ScalarType
    returnTypeFor(List<ScalarType> argumentTypes)
    The result type of a call with these argument types.
    FunctionSignature
    signature()
    The form of this function — name, parameters, arity, return type, properties.

  • Method Details

    • signature

      FunctionSignature signature()
      The form of this function — name, parameters, arity, return type, properties.
      Returns:
      the signature; never null

    • name

      default String name()
      Returns:
      the canonical spelling of this function's name

    • returnTypeFor

      default ScalarType returnTypeFor(List<ScalarType> argumentTypes)
      The result type of a call with these argument types.

      Defaults to the declared return type, which is the answer whenever the result type is fixed. Override it for a function whose result follows its arguments — a conditional returning whichever branch it selects, a Coalesce over a homogeneous list — and the engine's schema inference uses the narrower type.

      Parameters:
      argumentTypes - the argument types at the call site, in order
      Returns:
      the result type of that call

    • argumentTypes

      default Set<ScalarType> argumentTypes(int index)
      The types the argument at index may have, for analysis to accept a call before it runs.

      Defaults to the parameter's declared type, or every type when the parameter is declared ScalarType.ANY, or index is past the declared parameters, or the function takes a range of argument counts, where an argument's position need not be its parameter's: InStr(start, s, find) beside InStr(s, find). Override it for a parameter that takes several types but not every one — a date part that reads a DATE or a TIMESTAMP — so that a call passing any other is refused at analysis rather than when it runs. An argument whose type analysis cannot tell is always accepted.

      Parameters:
      index - the argument's position, from 0
      Returns:
      the accepted types; never empty

    • pushdown

      default PushdownSpelling pushdown()
      How this function is spelled in a backend that could evaluate it itself.

      Defaults to PushdownSpelling.NONE — no backend spelling, so the engine evaluates every call. Supplying one is how a library's own function folds into a pushed query alongside the built-ins.

      Returns:
      the pushdown spelling; never null

    • blocking

      default Optional<Blocking> blocking(Blocking.Bound bound, BigDecimal threshold)
      How to find, among many values, the few that a call compared against a constant could accept — so that a join on F(left.x, right.y) >= t need not call F on every pair.

      Defaults to empty, which leaves such a join to compare every pair. A two-argument similarity function overrides it to offer a Blocking for the comparisons it can bound; the Blocking contract says what the offer promises.

      Parameters:
      bound - how the call's result is compared with the threshold, read with the call on the left: F(a, b) bound threshold
      threshold - the constant the result is compared with
      Returns:
      a blocking for that comparison, or empty when there is none