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

Record Class SourceRef

java.lang.Object
java.lang.Record
com.darkcollective.relix.provenance.SourceRef
Record Components:
source - the producing leaf's label — a relation name or operator label; never null or blank
ordinal - the 1-based occurrence index within that leaf
columns - the base tuple's column → display-value map (a null value is a SQL null); copied defensively, never null
public record SourceRef(String source, long ordinal, SortedMap<String,String> columns) extends Record
A structured, machine-readable identity for one base-tuple occurrence — the data a ProvenanceVariable carries so a consuming tool can pinpoint which row of which relation a lineage variable stands for.

The bare <source>#<ordinal> label that a variable renders as is convenient for humans but opaque to tooling: it names the producing leaf and a per-run occurrence counter, nothing more. A SourceRef additionally captures the occurrence's columns — the base tuple's column values at lift time — so the variable becomes addressable: a consumer can match columns against a key (or the full row) to locate the exact source tuple.

The values are captured as their display strings (a null value marks a SQL null), keeping this module free of the data-layer Value type. The producing leaf is identified by source (a relation name for a true base relation, else the opaque operator's label, e.g. Aggregation) and a 1-based per-leaf occurrence ordinal; together they form the canonical name that identifies the variable.

  • Constructor Details

    • SourceRef

      public SourceRef(String source, long ordinal, SortedMap<String,String> columns)
      Canonicalises the reference: validates source and defensively copies columns into an unmodifiable sorted map (preserving null values, which mark SQL nulls).
      Parameters:
      source - the producing leaf's label; never null or blank
      ordinal - the 1-based occurrence index
      columns - the captured column values; never null (may be empty)

  • Method Details

    • canonicalName

      public String canonicalName()
      Returns the canonical <source>#<ordinal> label for this occurrence. This is the variable's identity — two references with the same source and ordinal name the same variable, regardless of captured columns.
      Returns:
      the canonical <source>#<ordinal> label for this occurrence

    • detailedLabel

      public String detailedLabel()
      Returns a detailed label, the canonical name followed by the captured columns. e.g. Orders#1{id: 42, status: OPEN}. Falls back to the bare canonical name when no columns were captured.
      Returns:
      a detailed label, the canonical name followed by the captured columns

    • toString

      public final 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

    • hashCode

      public final 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

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • source

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

    • ordinal

      public long ordinal()
      Returns the value of the ordinal record component.
      Returns:
      the value of the ordinal record component

    • columns

      public SortedMap<String,String> columns()
      Returns the value of the columns record component.
      Returns:
      the value of the columns record component