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

Record Class SortSpecification

java.lang.Object
java.lang.Record
com.darkcollective.relix.ast.SortSpecification
Record Components:
expression - the value to order by; never null
direction - ascending or descending; never null
nulls - where NULLs land in the output; never null
public record SortSpecification(Operand expression, SortDirection direction, NullPlacement nulls) extends Record
A single sort key: the Operand expression to order by, the direction (SortDirection.ASC / SortDirection.DESC), and where its NULLs go.

The expression is a full scalar expression, not merely a column reference, so a relation may be ordered by a derived value — e.g. τ to_timestamp(logged) DESC (RawLogs). The common case τ name (Users) is simply an ordering by a bare AttributeOperand.

nulls is where a missing value lands in the output, whichever way the key runs: NullPlacement.NULLS_LAST puts NULLs after every value, and NullPlacement.NULLS_FIRST before them. SQL's NULLS FIRST and NULLS LAST set it. A key written without either sorts NULL as the largest value, as PostgreSQL and Oracle do: last ascending and first descending (defaultNulls(SortDirection)), so writing the default out builds an equal key.

  • Constructor Details

    • SortSpecification

      public SortSpecification(Operand expression, SortDirection direction, NullPlacement nulls)
      Creates an instance of a SortSpecification record class.
      Parameters:
      expression - the value for the expression record component
      direction - the value for the direction record component
      nulls - the value for the nulls record component

    • SortSpecification

      public SortSpecification(Operand expression, SortDirection direction)
      A sort key with the default placement, NULL as the largest value: last ascending and first descending.
      Parameters:
      expression - the value to order by; never null
      direction - ascending or descending; never null

    • SortSpecification

      public SortSpecification(String attribute, SortDirection direction)
      Convenience constructor for a sort key over a bare column — wraps attribute as an AttributeOperand. Keeps the many call sites (and tests) that sort by a plain column name unchanged.

  • Method Details

    • defaultNulls

      public static NullPlacement defaultNulls(SortDirection direction)
      Where a key running direction puts its NULLs when it does not say: NULL is the largest value, as in PostgreSQL and Oracle, so NullPlacement.NULLS_LAST ascending and NullPlacement.NULLS_FIRST descending. MySQL, SQL Server and SQLite take NULL as the smallest, the other way in both directions.
      Parameters:
      direction - ascending or descending; never null
      Returns:
      the placement a key without NULLS FIRST or NULLS LAST has
      Since:
      1.0

    • nullsClause

      public String nullsClause()
      The NULLS clause that writes this key's placement, when it is not the default for its direction: " NULLS FIRST" on an ascending key that says so, " NULLS LAST" on such a descending one, and "" otherwise. Each printer of a key appends it, so the text parses back to an equal key.
      Returns:
      the clause with its leading space, or ""; never null
      Since:
      1.0

    • columnName

      public Optional<String> columnName()
      The input column name this key orders by, iff the key is a bare attribute reference; empty for a derived expression. Ordering-property reasoning and ORDER BY pushdown use this to distinguish a plain column from a computed key.
      Returns:
      the unqualified column name, or empty for an expression key

    • render

      public String render()
      This sort key as Relix text, as a τ writes it: the expression, then DESC for a descending key and the NULLS clause for one whose placement is not its direction's default. The same as render(Spelling.GLYPHS).
      Returns:
      the key as .relix text, such as price * qty DESC; never null
      Since:
      1.0

    • render

      public String render(Spelling spelling)
      This sort key as Relix text, as a τ writes it: the expression as Operand.prettyPrint(Spelling) renders it, then DESC for a descending key and the NULLS clause for one whose placement is not its direction's default. An ascending key is written without a direction, which is what a τ reads as ascending, so SORT <key> (T) parses back to an equal key.
      Parameters:
      spelling - glyphs or ASCII keywords for a condition the expression holds; must not be null
      Returns:
      the key as .relix text, such as price * qty DESC; never null
      Since:
      1.0

    • withExpression

      public SortSpecification withExpression(Operand expression)
      This key with expression in place of its own, keeping its direction and NULL placement.
      Parameters:
      expression - the value to order by; never null
      Returns:
      the key
      Since:
      1.0

    • nullPlacement

      public NullPlacement nullPlacement()
      Where NULLs go in this key's ascending comparator, the one a descending key reverses: nulls() for an ascending key, and the other placement for a descending one, so that reversing it lands NULLs where nulls() says.

      A comparator built from it and then reversed for SortDirection.DESC orders exactly as this key does; the sort executor and the merge-join comparator both build theirs that way.

      Returns:
      the placement before the direction is applied; 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. 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.

    • expression

      public Operand expression()
      Returns the value of the expression record component.
      Returns:
      the value of the expression record component

    • direction

      public SortDirection direction()
      Returns the value of the direction record component.
      Returns:
      the value of the direction record component

    • nulls

      public NullPlacement nulls()
      Returns the value of the nulls record component.
      Returns:
      the value of the nulls record component