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

Record Class PathNode

java.lang.Object
java.lang.Record
com.darkcollective.relix.ast.PathNode
Record Components:
input - the edge relation; must not be null
fromColumn - the source-endpoint column; also names the output source column; must not be blank
toColumn - the target-endpoint 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)
minHops - the inclusive lower bound of the hop window; must be >= 1
maxHops - the inclusive upper bound of the hop window; must be >= minHops
depthColumn - the name of the appended hop-distance 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 PathNode(RelNode input, String fromColumn, String toColumn, boolean undirected, int minHops, int maxHops, String depthColumn, Optional<Operand> boundSource, Optional<Operand> boundTarget, SourceLocation location) extends Record implements RelNode
Bounded variable-length path reachability — the RA-native graph-traversal operator.

The input() relation is read as a set of directed edges over two columns, fromColumn() and toColumn(). The operator emits one row (a, b, d) for every pair connected by a directed path whose length d lies within the inclusive hop window [minHops, maxHops], where d is the shortest such length. It is therefore the bounded sibling of ClosureNode (unbounded transitive closure) that also reports the hop distance — the "everything within N hops" traversal investigators and analysts need, which SQL expresses only with a WITH RECURSIVE CTE plus a depth guard.

The start node is not baked into the operator: scope a traversal to a particular origin by composing an ordinary σ on the output (RA-native), e.g. σ from = 1001 (PATH …).

Output is a ternary relation: the source-endpoint column (keeping the fromColumn() name and type), the target-endpoint column (keeping the toColumn() name and type), and the hop-distance column (depthColumn(), type NUMBER). Because d is the minimal length, (from, to) is a candidate key of the result (no pair appears at two depths).

Evaluation is an in-engine bounded breadth-first traversal over the whole edge set — a blocking operator (it must see every edge), so it never pushes down to a source and is subject to the boundedness check over unbounded inputs. Null endpoints are skipped; cyclic graphs terminate because the window caps the path length.

Surface syntax: PATH from, to HOPS m..n AS depth (Edges).

  • Constructor Details

    • PathNode

      public PathNode(RelNode input, String fromColumn, String toColumn, boolean undirected, int minHops, int maxHops, String depthColumn, Optional<Operand> boundSource, Optional<Operand> boundTarget, SourceLocation location)
      Creates an instance of a PathNode 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
      minHops - the value for the minHops record component
      maxHops - the value for the maxHops record component
      depthColumn - the value for the depthColumn 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

    • PathNode

      public PathNode(RelNode input, String fromColumn, String toColumn, boolean undirected, int minHops, int maxHops, String depthColumn, SourceLocation location)
      Constructor without endpoint bounds (the parsed form): both bounds empty.
      Parameters:
      input - the edge relation; must not be null
      fromColumn - the source-endpoint column; must not be blank
      toColumn - the target-endpoint column; must not be blank
      undirected - true to read the edges both ways
      minHops - the inclusive lower bound of the hop window
      maxHops - the inclusive upper bound of the hop window
      depthColumn - the name of the appended hop-distance column
      location - the source location of this node; never null

    • PathNode

      public PathNode(RelNode input, String fromColumn, String toColumn, int minHops, int maxHops, String depthColumn)
      Convenience constructor for tests: SourceLocation.UNKNOWN.

  • Method Details

    • withBounds

      public PathNode withBounds(Optional<Operand> newSource, Optional<Operand> newTarget)
      Returns a copy of this path 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

    • minHops

      public int minHops()
      Returns the value of the minHops record component.
      Returns:
      the value of the minHops record component

    • maxHops

      public int maxHops()
      Returns the value of the maxHops record component.
      Returns:
      the value of the maxHops record component

    • depthColumn

      public String depthColumn()
      Returns the value of the depthColumn record component.
      Returns:
      the value of the depthColumn 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