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

Record Class SolveNode

java.lang.Object
java.lang.Record
com.darkcollective.relix.ast.SolveNode
Record Components:
equations - the equations, in source order; never empty
groupingKeys - the PER columns a fit is made per; empty to solve row by row
tolerance - the WITHIN convergence tolerance, positive; empty for the default
maxRounds - the MAX … ROUNDS iteration cap, at least 1; empty for the default
starts - the START values, at most one per column; empty to start at 1
input - the relation whose rows are completed; must not be null
location - the source location of this node; never null
All Implemented Interfaces:
RelNode
public record SolveNode(List<SolveEquation> equations, List<String> groupingKeys, Optional<BigDecimal> tolerance, Optional<Integer> maxRounds, List<SolveStart> starts, RelNode input, SourceLocation location) extends Record implements RelNode
Goal-seek (SOLVE) — fills the unknown columns of a row by solving one or more declared arithmetic equations left = right.

For each input row, the participating columns are the distinct attribute references appearing anywhere in the equations. Those that are NULL in that row are its unknowns, so the direction is per row — the same equation fills principal in one row and rate in another, depending on which is blank. A row is solved when it has exactly as many unknowns as there are equations, by the cheapest strategy that applies: a single equation whose unknown appears once is inverted by rearranging it; equations linear in the unknowns are solved by elimination; anything else is solved by Newton's method, every unknown starting at 1 unless starts says otherwise. A row that cannot be posed — the wrong number of unknowns, or a singular linear system — passes through unchanged; a row that is posed but on which the iteration does not converge is an error.

With groupingKeys (PER k, …) the equations are fitted across each group of rows rather than solved row by row: the unknowns are the participating columns that are NULL in every row of the group, every row in which the other participating columns are all present is an observation, and the unknowns are chosen to minimise the sum of squared residuals over the observations — directly when the equations are linear in them, by Gauss–Newton otherwise. The fitted values are written into every row of the group. Grouping makes the operator blocking.

tolerance (WITHIN ε) and maxRounds (MAX n ROUNDS) govern the iteration, and are left empty for the engine's defaults; an iteration stops when no unknown moves by more than the tolerance in a round. starts (START u = e, …) gives an unknown's first estimate as an expression over the row's known columns, so a query can choose which root a search reaches; over a PER group it must be a constant.

The output schema equals the input schema — solve fills holes, it never adds or removes columns. The sides are restricted to arithmetic (column references, numeric literals, + − × ÷, unary minus, and calls to user-defined scalar functions whose bodies are such arithmetic). This operator runs in-engine and never pushes down.

Example: SOLVE total = principal * rate (Loans) fills whichever of total, principal, or rate is blank in each loan row.

  • Constructor Details

  • Method Details

    • 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. All components in this record class are compared with Objects::equals(Object,Object).
      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.

    • equations

      public List<SolveEquation> equations()
      Returns the value of the equations record component.
      Returns:
      the value of the equations record component

    • groupingKeys

      public List<String> groupingKeys()
      Returns the value of the groupingKeys record component.
      Returns:
      the value of the groupingKeys record component

    • tolerance

      public Optional<BigDecimal> tolerance()
      Returns the value of the tolerance record component.
      Returns:
      the value of the tolerance record component

    • maxRounds

      public Optional<Integer> maxRounds()
      Returns the value of the maxRounds record component.
      Returns:
      the value of the maxRounds record component

    • starts

      public List<SolveStart> starts()
      Returns the value of the starts record component.
      Returns:
      the value of the starts record component

    • input

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