Module com.darkcollective.relix.provenance
Package com.darkcollective.relix.provenance

Interface BaseTuple

public interface BaseTuple
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.

It exists so that Semiring.base(com.darkcollective.relix.provenance.BaseTuple) can be answered by a semiring that has never heard of a row, a schema or a value. That is what keeps this module free of engine dependencies, and it is what makes an installed semiring able to do everything a built-in one can: the four shapes of base annotation that ship — a constant, a numeric weight, a weight carrying a route token, and a freshly minted lineage variable — are each derivable from the four accessors below, so none of them needs the engine to recognise the semiring by name.

Cost

columns() materialises a map per call and most semirings never ask for one, so an implementation is expected to build it on demand rather than up front. The other three are cheap.

  • Method Summary

    Modifier and Type
    Method
    Description
    SortedMap<String,String>
    columns()
    Returns this tuple's column values, as a sorted name → display-string map.
    long
    ordinal()
    Returns the 1-based occurrence index of this tuple within its leaf.
    String
    source()
    Returns a label for the leaf this tuple came from.
    Optional<BigDecimal>
    weight()
    Returns this tuple's per-edge weight, or empty when it has none.

  • Method Details

    • source

      String source()
      Returns a label for the leaf this tuple came from. Typically a relation name.
      Returns:
      a label for the leaf this tuple came from

    • ordinal

      long ordinal()
      Returns the 1-based occurrence index of this tuple within its leaf. Distinct occurrences of an identical row have distinct ordinals, which is what lets an annotation address the occurrence rather than the value.
      Returns:
      the 1-based occurrence index of this tuple within its leaf

    • weight

      Optional<BigDecimal> weight()
      Returns this tuple's per-edge weight, or empty when it has none.

      Empty covers every way a weight can fail to be a number: no weight column was requested, the row does not carry it, or its value is null or non-numeric. A semiring that reads a weight therefore states its own no-weight answer rather than relying on the engine to have picked one.

      Returns:
      this tuple's per-edge weight, or empty when it has none

    • columns

      SortedMap<String,String> columns()
      Returns this tuple's column values, as a sorted name → display-string map. A SQL-null column is present with a null value, which is why this is not a Map.of. Materialised per call — ask only if the annotation needs it.
      Returns:
      this tuple's column values, as a sorted name → display-string map