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

Record Class TopKNode

java.lang.Object
java.lang.Record
com.darkcollective.relix.ast.TopKNode
Record Components:
groupingAttributes - the partition keys; empty means one global group
sortSpecs - within-group ordering; at least one required
offset - rows to skip within each group before taking count
count - number of rows to keep per group; non-negative
withTies - whether rows tied with the last one kept are kept too; needs a sort key
leadingDirectionImplied - whether the first sort key was written with neither ASC nor DESC, so that it is ascending by default rather than by request; validation warns about it, since "top" reads as the highest
input - the source relation; never null
location - the source location of this node; never null
All Implemented Interfaces:
RelNode
public record TopKNode(List<String> groupingAttributes, List<SortSpecification> sortSpecs, Optional<Long> offset, long count, boolean withTies, boolean leadingDirectionImplied, RelNode input, SourceLocation location) extends Record implements RelNode
Top-k per group (TOP) — partitions input by groupingAttributes and, within each group, keeps the first count rows in sortSpecs order (after skipping offset rows). A key with no direction is ascending, so TOP 1 x keeps the row with the lowest x.

This is the "N highest rows per group" operation — top 3 orders by amount per customer — that SQL forces into a ROW_NUMBER() OVER (PARTITION BY … ORDER BY …) ≤ k plus an outer filter, or a lateral join. Unlike a global LimitNode it cannot push down and buffers each group; unlike an AggregationNode it returns whole rows.

The output schema is the input schema (it is a windowed filter — a row subset). At least one sort specification is required.

The surface syntax always names a partition key (TOP … PER …), but the grouping list may be empty: that is the global top-N — one group containing every row — which the optimizer produces by fusing a λ over a τ (LIM-003). It has no spelling of its own because λ/τ already is one.

withTies keeps, past the count-th row of a group, every further row that ties with it on all the sort keys, as SQL's WITH TIES does: rows the order cannot tell apart are kept or dropped together. A tie is equality under the sort's own comparison, so two NULLs tie and 5 ties with 5.0. TOP 2 WITH TIES over scores 9, 8, 8, 7 keeps three rows.

Example: TOP 3 amount DESC PER customer_id (Orders).

  • Constructor Details

    • TopKNode

      public TopKNode(List<String> groupingAttributes, List<SortSpecification> sortSpecs, Optional<Long> offset, long count, boolean withTies, boolean leadingDirectionImplied, RelNode input, SourceLocation location)
      Creates an instance of a TopKNode record class.
      Parameters:
      groupingAttributes - the value for the groupingAttributes record component
      sortSpecs - the value for the sortSpecs record component
      offset - the value for the offset record component
      count - the value for the count record component
      withTies - the value for the withTies record component
      leadingDirectionImplied - the value for the leadingDirectionImplied record component
      input - the value for the input record component
      location - the value for the location record component

    • TopKNode

      public TopKNode(List<String> groupingAttributes, List<SortSpecification> sortSpecs, Optional<Long> offset, long count, boolean withTies, RelNode input, SourceLocation location)
      A top-k whose sort directions are all taken as requested, as one the optimizer or a builder makes rather than one a person wrote.
      Parameters:
      groupingAttributes - the partition keys; empty means one global group
      sortSpecs - within-group ordering; at least one required
      offset - rows to skip within each group before taking count
      count - number of rows to keep per group; non-negative
      withTies - whether rows tied with the last one kept are kept too; needs a sort key
      input - the source relation; never null
      location - the source location of this node; never null

    • TopKNode

      public TopKNode(List<String> groupingAttributes, List<SortSpecification> sortSpecs, Optional<Long> offset, long count, RelNode input, SourceLocation location)
      A top-k that cuts ties wherever the count falls.
      Parameters:
      groupingAttributes - the partition keys; empty means one global group
      sortSpecs - within-group ordering; at least one required
      offset - rows to skip within each group before taking count
      count - number of rows to keep per group; non-negative
      input - the source relation; never null
      location - the source location of this node; never null

    • TopKNode

      public TopKNode(List<String> groupingAttributes, List<SortSpecification> sortSpecs, long count, RelNode input)
      Convenience constructor for tests; no offset, SourceLocation.UNKNOWN.

  • Method Details

    • withInput

      public TopKNode withInput(RelNode input)
      This node over input, every other component kept.
      Parameters:
      input - the new input; never null
      Returns:
      the node
      Since:
      1.0

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

    • groupingAttributes

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

    • sortSpecs

      public List<SortSpecification> sortSpecs()
      Returns the value of the sortSpecs record component.
      Returns:
      the value of the sortSpecs record component

    • offset

      public Optional<Long> offset()
      Returns the value of the offset record component.
      Returns:
      the value of the offset record component

    • count

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

    • withTies

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

    • leadingDirectionImplied

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