Module com.darkcollective.relix.processor

Package com.darkcollective.relix.processor.provenance.internal

Interface BaseAnnotator<K>

Type Parameters:

K - the semiring annotation type

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface BaseAnnotator<K>

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.

Which annotation a tuple lifts to is the semiring's answer, not this interface's: forSemiring(com.darkcollective.relix.provenance.Semiring<K>, java.lang.String) reduces the row to a BaseTuple and asks Semiring.base(com.darkcollective.relix.provenance.BaseTuple). For the cheap semirings that is one for every tuple, so a base relation embeds with each row "present" (boolean) or multiplicity one (ℕ). The lineage semiring ℕ[X] instead mints a distinct provenance variable per occurrence (e.g. Orders#1, Orders#2), which is what makes it the free, most-informative semiring: two structurally-equal source rows receive different variables, and the merged tuple's annotation becomes x₁ ⊕ x₂.

The ordinal is a 1-based per-leaf occurrence counter, so (source, ordinal) uniquely names each base-tuple occurrence. This seam is also the natural home for future source-level annotations (e.g. a security level per source).

Method Summary

Modifier and Type	Method	Description
K	annotate(String source, long ordinal, Row row)	Returns the annotation for one base-tuple occurrence.
static <K> BaseAnnotator<K>	forSemiring(Semiring<K> semiring, String weightColumn)	Returns the annotator semiring wants, given an optional per-edge weightColumn.
static BaseAnnotator<Polynomial>	lineage()	Returns the lineage annotator.

Method Details

annotate

K annotate(String source,
 long ordinal,
 Row row)

Returns the annotation for one base-tuple occurrence.

Parameters:

source - a label for the leaf the row came from (e.g. a relation name)

ordinal - the 1-based occurrence index within that leaf

row - the base row

Returns:

the tuple's base annotation

forSemiring

static <K> BaseAnnotator<K> forSemiring(Semiring<K> semiring,
 String weightColumn)

Returns the annotator semiring wants, given an optional per-edge weightColumn.

Which shape of annotation a base tuple lifts to is a property of the semiring rather than a choice the caller makes, and it is the semiring that states it: this reduces each row to a BaseTuple — its leaf, its occurrence index, its weight and, on demand, its columns — and hands that to Semiring.base(com.darkcollective.relix.provenance.BaseTuple). So a constant, a cost, a multiplicity, a route token and a lineage variable are all the same call here, and an installed semiring reaches every one of those shapes without the engine recognising it.

A row lacking the weight column, or carrying a null or non-numeric value, has no weight; the semiring decides what that means for it.

Type Parameters:

K - the annotation type

Parameters:

semiring - the annotation semiring; must not be null

weightColumn - the per-edge weight column, or null for no weight

Returns:

the annotator semiring wants, given an optional per-edge weightColumn

lineage

static BaseAnnotator<Polynomial> lineage()

Returns the lineage annotator. Each base-tuple occurrence becomes a fresh ℕ[X] variable named <source>#<ordinal>, carrying that occurrence's column values — which is what makes a lineage variable addressable back to the row that produced it, rather than merely nameable.

Returns:

the lineage annotator