Module com.darkcollective.relix.ast
Package com.darkcollective.relix.ast

Record Class TraceNode

java.lang.Object
java.lang.Record
com.darkcollective.relix.ast.TraceNode
Record Components:
input - the edge relation; must not be null
fromColumn - the origin node column; must not be blank
toColumn - the destination node column; must not be blank
undirected - true reads the two endpoint columns as an undirected edge, so the relation is followed both ways from one edge set (a ↔ b); false reads a directed edge (a, b)
weightColumn - the edge-weight column (must be NUMBER or ANY); must not be blank
sense - whether to minimise or maximise total path weight; must not be null
pathColumn - the name of the appended ordered-path array column; must not be blank
boundSource - optional literal bound on the fromColumn endpoint (single-source); never null, possibly empty
boundTarget - optional literal bound on the toColumn endpoint (single-target); never null, possibly empty
location - the source location of this node; never null
All Implemented Interfaces:
RelNode
public record TraceNode(RelNode input, String fromColumn, String toColumn, boolean undirected, String weightColumn, ObjectiveSense sense, String pathColumn, Optional<Operand> boundSource, Optional<Operand> boundTarget, SourceLocation location) extends Record implements RelNode
Optimal-path extraction over a directed, weighted graph — the cheapest (or longest) path finder.

The input() relation is read as a set of directed edges, each carrying a numeric weight in weightColumn(). The operator computes, for every reachable (origin, destination) pair, the path that minimises (or maximises, per sense()) the total edge weight, and returns the traversed node sequence as a first-class ordered array value in the pathColumn().

Output schema: (fromColumn : T, toColumn : T, weightColumn : NUMBER, pathColumn : ARRAY), where T is the type of the endpoint columns and ARRAY is an ordered array<T> holding the sequence of nodes from origin to destination inclusive.

Evaluation is a Bellman-Ford–style all-pairs fixpoint: each iteration extends known paths by one hop and keeps the optimal so far. The operator materialises the complete edge set before iterating, so it is blocking ([bag] mode) and is subject to the boundedness check. It never pushes down to a source.

MAXIMIZE over a graph with positive-weight cycles will not converge; the --max-fixpoint-rounds guard applies (consistent with FIX and weighted CLOSURE).

Surface syntax: TRACE from, to VIA weight MINIMIZE|MAXIMIZE AS path (Edges)

Pushed endpoint bounds

boundSource() and boundTarget() are optional constant endpoint bounds folded in by the optimizer's SelectionIntoTracePass (TRACE-001) when a selection above the trace fixes the origin and/or destination to a literal. They turn the all-pairs path search into single-source / single-target / single-pair search — the magic-sets / sideways-information-passing rewrite specialised to optimal paths. They are always Optional.empty() on a parsed tree (no surface syntax); they carry a literal Operand and never change the output schema, so schema inference is unaffected.

  • Constructor Details

    • TraceNode

      public TraceNode(RelNode input, String fromColumn, String toColumn, boolean undirected, String weightColumn, ObjectiveSense sense, String pathColumn, Optional<Operand> boundSource, Optional<Operand> boundTarget, SourceLocation location)
      Creates an instance of a TraceNode record class.
      Parameters:
      input - the value for the input record component
      fromColumn - the value for the fromColumn record component
      toColumn - the value for the toColumn record component
      undirected - the value for the undirected record component
      weightColumn - the value for the weightColumn record component
      sense - the value for the sense record component
      pathColumn - the value for the pathColumn record component
      boundSource - the value for the boundSource record component
      boundTarget - the value for the boundTarget record component
      location - the value for the location record component

    • TraceNode

      public TraceNode(RelNode input, String fromColumn, String toColumn, String weightColumn, ObjectiveSense sense, String pathColumn, SourceLocation location)
      Constructor without endpoint bounds (the parsed form): both bounds empty.
      Parameters:
      input - the edge relation; must not be null
      fromColumn - the origin node column; must not be blank
      toColumn - the destination node column; must not be blank
      weightColumn - the edge-weight column; must not be blank
      sense - the objective sense; must not be null
      pathColumn - the appended path-array column; must not be blank
      location - the source location of this node; never null

    • TraceNode

      public TraceNode(RelNode input, String fromColumn, String toColumn, String weightColumn, ObjectiveSense sense, String pathColumn)
      Convenience constructor for tests: SourceLocation.UNKNOWN.

  • Method Details

    • withBounds

      public TraceNode withBounds(Optional<Operand> newSource, Optional<Operand> newTarget)
      Returns a copy of this trace with the given endpoint bounds, preserving all other fields.
      Parameters:
      newSource - the source-endpoint bound; must not be null
      newTarget - the target-endpoint bound; must not be null
      Returns:
      a bounded copy

    • accept

      public <R> R accept(RelNodeVisitor<R> visitor)
      Specified by:
      accept in interface RelNode

    • 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.

    • input

      public RelNode input()
      Returns the value of the input record component.
      Returns:
      the value of the input record component

    • fromColumn

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

    • toColumn

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

    • undirected

      public boolean undirected()
      Returns the value of the undirected record component.
      Returns:
      the value of the undirected record component

    • weightColumn

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

    • sense

      public ObjectiveSense sense()
      Returns the value of the sense record component.
      Returns:
      the value of the sense record component

    • pathColumn

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

    • boundSource

      public Optional<Operand> boundSource()
      Returns the value of the boundSource record component.
      Returns:
      the value of the boundSource record component

    • boundTarget

      public Optional<Operand> boundTarget()
      Returns the value of the boundTarget record component.
      Returns:
      the value of the boundTarget record component

    • location

      public SourceLocation location()
      Returns the value of the location record component.
      Specified by:
      location in interface RelNode
      Returns:
      the value of the location record component