Module com.darkcollective.relix.processor
Package com.darkcollective.relix.processor.generator

Interface Generator

All Known Implementing Classes:
NaturalsGenerator, PrimesGenerator, RangeGenerator
public interface Generator
A code-backed leaf relation — its rows are produced by engine code rather than read from a file or database.

A generator owns its schema: schema(Map) returns the heading the relation will have (used by semantic analysis), and rows(Map, Schema) lazily produces the tuples (used by execution). Both take the generator's raw string arguments (e.g. lo/hi/step for Range); a generator interprets and validates the args it understands.

Layer 0 covers only finite generators, which need no boundedness machinery. Boundedness/distinctness declaration is added in a later slice and consumed by the boundedness check.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Optional<String>
    ascendingColumn()
    The single column on which this generator emits values in strictly ascending order, when it is an unbounded generator — the seam the optimizer's GEN-001 pass consults to fold an upper-bound selection into a production stop.
    default OptionalLong
    cardinality(Map<String,String> args)
    The generator's exact cardinality for the given arguments, when known — fed to the cost model as an exact row count (a finite generator like Range knows it precisely).
    default boolean
    duplicateFree()
    Whether this generator is inherently duplicate-free (every row distinct).
    String
    name()
     
    Stream<Row>
    rows(Map<String,String> args, Schema schema)
    Lazily produces the generator's rows.
    Schema
    schema(Map<String,String> args)
    The schema (heading) this generator produces for the given arguments.
    default boolean
    unbounded()
    Whether this generator is provably infinite.

  • Method Details

    • name

      String name()
      Returns:
      the registered generator name (e.g. "Range"); case-insensitive at lookup

    • schema

      Schema schema(Map<String,String> args)
      The schema (heading) this generator produces for the given arguments. Implementations should keep this total where possible — argument validation that only affects the rows belongs in rows(java.util.Map<java.lang.String, java.lang.String>, com.darkcollective.relix.symbol.Schema).
      Parameters:
      args - the raw generator arguments
      Returns:
      the output schema

    • rows

      Stream<Row> rows(Map<String,String> args, Schema schema)
      Lazily produces the generator's rows.
      Parameters:
      args - the raw generator arguments (e.g. lo/hi/step)
      schema - the schema returned by schema(Map) for the same args
      Returns:
      a lazy stream of rows; the caller closes it
      Throws:
      EvaluationException - if the arguments are missing or invalid

    • cardinality

      default OptionalLong cardinality(Map<String,String> args)
      The generator's exact cardinality for the given arguments, when known — fed to the cost model as an exact row count (a finite generator like Range knows it precisely). Returns OptionalLong.empty() when unknown or unbounded; the default is empty.
      Parameters:
      args - the raw generator arguments
      Returns:
      the exact row count, or empty when unknown/unbounded

    • unbounded

      default boolean unbounded()
      Whether this generator is provably infinite. Read by GeneratorBoundednessSource; finite generators (the default) report false.
      Returns:
      true if the generator has no last row

    • duplicateFree

      default boolean duplicateFree()
      Whether this generator is inherently duplicate-free (every row distinct). Read by GeneratorDistinctnessSource, which feeds distinctness-driven δ elimination (DIST-001).
      Returns:
      true if the generator never emits a duplicate row

    • ascendingColumn

      default Optional<String> ascendingColumn()
      The single column on which this generator emits values in strictly ascending order, when it is an unbounded generator — the seam the optimizer's GEN-001 pass consults to fold an upper-bound selection into a production stop. Returning a column declares "an upper bound on this column is a sound termination condition" (a takeWhile).

      The default is empty: finite generators terminate on their own, and a non-monotone generator cannot be safely stopped by a value threshold.

      Returns:
      the ascending value column, or empty when not an ascending unbounded generator