Module com.darkcollective.relix.plan
Package com.darkcollective.relix.plan

Record Class PhysicalNode.Spool

java.lang.Object
java.lang.Record
com.darkcollective.relix.plan.PhysicalNode.Spool
Record Components:
schema - the output schema; always the input's schema
id - the identifier the executor buffers this sub-plan under; unique within one planned query
input - the sub-plan whose rows are shared
All Implemented Interfaces:
PhysicalNode
Enclosing interface:
PhysicalNode
public static record PhysicalNode.Spool(Schema schema, int id, PhysicalNode input) extends Record implements PhysicalNode
Marks a sub-plan whose rows are computed once and read by more than one consumer. The same Spool appears at every site that reads it, so the plan is a directed acyclic graph at this node rather than a tree.

Without it, a plan is a tree and every occurrence of a sub-expression is executed independently — which is why the symmetric difference A ∆ B, whose two branches (A − B) and (B − A) each read both inputs, would otherwise evaluate A and B twice apiece.

The executor keys its buffer on id, not on object identity, so a plan that is copied or rebuilt keeps sharing what it shared before. Ids are unique within one planned query and carry no meaning across queries.

Sharing is not free and not always allowed. Replaying rows means holding them, so the executor buffers under a row budget and falls back to re-executing the sub-plan when the budget is exceeded — never a wrong answer, only the cost that was being avoided. The planner also declines to spool a sub-expression whose two evaluations are entitled to differ: one that reads system state (a random draw, an unseeded sample), or one that names a recursive relation whose value changes with every iteration.

A spool is transparent to everything above it: it emits exactly its input's rows, in its input's order, under its input's schema, so no consumer — including a positional one — can tell a spooled sub-plan from an unspooled one.

  • Constructor Details

    • Spool

      public Spool(Schema schema, int id, PhysicalNode input)
      Creates an instance of a Spool record class.
      Parameters:
      schema - the value for the schema record component
      id - the value for the id record component
      input - the value for the input record component

  • Method Details

    • children

      public List<PhysicalNode> children()
      Description copied from interface: PhysicalNode
      Direct child plans, left-to-right; empty for a PhysicalNode.Scan.
      Specified by:
      children in interface PhysicalNode

    • deliveredOrdering

      public Ordering deliveredOrdering()
      Description copied from interface: PhysicalNode
      The Ordering that this node delivers on its output stream. The default implementation returns Ordering.none() — meaning no guaranteed row order — which is the conservative safe answer for any operator that does not propagate or establish an ordering. Individual nodes that do preserve order (PhysicalNode.Select, PhysicalNode.Limit) or establish it (PhysicalNode.Sort) override this method.
      Specified by:
      deliveredOrdering in interface PhysicalNode
      Returns:
      the delivered ordering; never null

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

    • schema

      public Schema schema()
      Returns the value of the schema record component.
      Specified by:
      schema in interface PhysicalNode
      Returns:
      the value of the schema record component

    • id

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

    • input

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