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

Record Class ProvenanceVariable

java.lang.Object
java.lang.Record
com.darkcollective.relix.provenance.ProvenanceVariable
Record Components:
name - the variable's label; never null or blank
source - the structured source identity, or Optional.empty() when minted from a bare label; never null
All Implemented Interfaces:
Comparable<ProvenanceVariable>
public record ProvenanceVariable(String name, Optional<SourceRef> source) extends Record implements Comparable<ProvenanceVariable>
A provenance variable — the token identifying one base-tuple occurrence in the polynomial-lineage semiring ℕ[X] (after Green, Karvounarakis & Tannen, PODS 2007).

Each occurrence of a tuple in a base relation is lifted to its own distinct variable (so two structurally-equal source rows still receive different variables, and the merged tuple's annotation becomes x₁ ⊕ x₂). The name is a human-readable label for that occurrence — by convention <relation>#<ordinal>, e.g. Orders#1 — chosen at lift time, not by the algebra.

A variable may additionally carry a structured source: the producing leaf, occurrence ordinal, and the base tuple's captured column values. This is what makes lineage machine-actionable — a consuming tool can use source() to locate the exact source row a variable stands for, rather than parsing the bare name. Variables minted from a raw label (e.g. in tests, or the cheap weighted-closure path) simply have an empty source.

Variables are compared, and considered equal, by name alone, so two variables with the same label are the same variable regardless of their captured source — the canonical name is the identity that the ⊕/⊗ algebra keys on.

  • Constructor Details

    • ProvenanceVariable

      public ProvenanceVariable(String name, Optional<SourceRef> source)
      Creates a provenance variable, validating its label and source.
      Parameters:
      name - the variable's label; never null or blank
      source - the structured source identity; never null (may be empty)

    • ProvenanceVariable

      public ProvenanceVariable(String name)
      Creates a bare provenance variable from a label, with no structured source.
      Parameters:
      name - the variable's label; never null or blank

  • Method Details

    • of

      public static ProvenanceVariable of(SourceRef ref)
      Returns a provenance variable carrying the structured ref. The variable's name is the reference's canonical name, so its identity is unchanged from a bare <source>#<ordinal> variable while it now carries the captured columns.
      Parameters:
      ref - the structured source identity; never null
      Returns:
      a provenance variable carrying the structured ref

    • label

      public String label(boolean detailed)
      Returns this variable's label, optionally enriched with its captured source columns. When detailed and a source with columns is present, returns e.g. Orders#1{id: 42}; otherwise the bare name.
      Parameters:
      detailed - whether to append the captured source columns when available
      Returns:
      this variable's label, optionally enriched with its captured source columns

    • compareTo

      public int compareTo(ProvenanceVariable other)
      Orders variables by name — the canonical order used to render monomials.
      Specified by:
      compareTo in interface Comparable<ProvenanceVariable>

    • equals

      public boolean equals(Object obj)
      Two variables are equal iff their names are equal (source is not part of identity).
      Specified by:
      equals in class Record

    • hashCode

      public int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • toString

      public String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • name

      public String name()
      Returns the value of the name record component.
      Returns:
      the value of the name record component

    • source

      public Optional<SourceRef> source()
      Returns the value of the source record component.
      Returns:
      the value of the source record component