Package dev.vortex.api

Class Expression

java.lang.Object
dev.vortex.api.Expression
public final class Expression extends Object
A Vortex expression node backed by a native pointer.

Expressions are composed via the static factories (root(), getItem(String, Expression), etc.). Each returned Expression owns its native pointer; the pointer is released automatically when the Expression is no longer reachable. Passing an expression as an input to a builder does not transfer ownership — the resulting expression is an independent copy on the native side.

  • Method Details

    • root

      public static Expression root()
      The root expression: applying it to an array yields the array itself.

    • rowIdx

      public static Expression rowIdx()
      The row-index expression. When evaluated as part of a Vortex scan it yields, as a non-nullable u64, each row's index in the file before filtering: the index is assigned to the unfiltered rows, so filtered-out rows leave gaps and the surviving rows keep their original positions rather than being renumbered. It cannot be evaluated outside of a scan.

    • getItem

      public static Expression getItem(String fieldName, Expression child)
      Access a named field from a struct expression.

    • column

      public static Expression column(String fieldName)
      Shortcut for getItem(fieldName, root()).

    • column

      public static Expression column(String[] fieldNames)
      Access a nested field by walking fieldNames starting from the root of the array. With a single name this is equivalent to column(String).

    • select

      public static Expression select(String[] fieldNames, Expression child)
      Project a subset of fields out of a struct expression.

    • pack

      public static Expression pack(String[] fieldNames, Expression[] expressions, boolean nullable)
      Creates an expression that packs values into a struct with named fields.

    • merge

      public static Expression merge(Expression.DuplicateHandling duplicateHandling, Expression... expressions)
      Merge struct expressions into a single struct, combining their fields in order.

      Every input must evaluate to a non-nullable struct. When the same field name appears in more than one input, duplicateHandling decides the result. Fields are not merged recursively — a later field replaces an earlier one with the same name. Merging zero expressions yields an empty struct.

    • merge

      public static Expression merge(Expression... expressions)
      Merge struct expressions, failing if any field name is duplicated. Equivalent to merge(DuplicateHandling, Expression...) with Expression.DuplicateHandling.ERROR.

    • and

      public static Expression and(Expression... operands)
      Logical AND. Requires at least one operand.

    • or

      public static Expression or(Expression... operands)
      Logical OR. Requires at least one operand.

    • binary

      public static Expression binary(Expression.BinaryOp op, Expression lhs, Expression rhs)

    • not

      public static Expression not(Expression child)

    • isNull

      public static Expression isNull(Expression child)

    • isNotNull

      public static Expression isNotNull(Expression child)

    • like

      public static Expression like(Expression child, Expression pattern, boolean negated, boolean caseInsensitive)
      SQL LIKE pattern match.
      Parameters:
      negated - whether to invert the result (i.e. NOT LIKE)
      caseInsensitive - whether to perform case-insensitive matching (ILIKE)

    • between

      public static Expression between(Expression value, Expression lower, Expression upper, boolean lowerStrict, boolean upperStrict)
      value BETWEEN lower AND upper.
      Parameters:
      lowerStrict - true for lower < value; false for lower <= value.
      upperStrict - true for value < upper; false for value <= upper.

    • listContains

      public static Expression listContains(Expression list, Expression needle)
      Whether the list list evaluates to contains needle, with Vortex's null rules: a null element never matches anything, so a needle that matches no element is false. A null needle is null, except against an empty list, where the result is false.

      list must evaluate to a Vortex list whose element type matches needle's type, ignoring nullability. With a list literal on the left and a column on the right this is a set-membership test that a constant-set kernel answers in one pass over the column, however large the set.

      See Also:

    • listContains

      public static Expression listContains(Expression list, Expression needle, boolean sqlNullSemantics)
      listContains(Expression, Expression) with a choice of null rules.
      Parameters:
      sqlNullSemantics - false for Vortex's rules, where a null element never matches; true for SQL's three-valued IN, where a null element is an unknown value, so a needle that matches no element is null rather than false whenever the list holds a null. A null needle is null, except against an empty list with Vortex's default rules, where the result is false.

    • in

      public static Expression in(Expression value, Expression list)
      SQL value IN (list): listContains(Expression, Expression, boolean) with SQL null semantics and the operands in SQL order. A null value is null, and so is a non-match against a list that holds a null; both filter the row out of a scan.

    • notIn

      public static Expression notIn(Expression value, Expression list)
      SQL value NOT IN (list): the negation of in(Expression, Expression). Under SQL's rules a null value, or a list that holds a null, makes a non-match null rather than true, so such a row is never admitted.

    • literal

      public static Expression literal(boolean value)

    • nullLiteralBool

      public static Expression nullLiteralBool()

    • literal

      public static Expression literal(byte value)

    • literal

      public static Expression literal(short value)

    • literal

      public static Expression literal(int value)

    • literal

      public static Expression literal(long value)

    • literal

      public static Expression literal(float value)

    • literal

      public static Expression literal(double value)

    • literal

      public static Expression literal(String value)

    • literal

      public static Expression literal(byte[] value)

    • literalList

      public static Expression literalList(Expression... elements)
      Create a list literal out of literal element expressions, for example the right-hand side of an IN set.

      Every element must itself be a literal and the elements must share a type, ignoring nullability; the list's element type is that shared type, made nullable if any element is. The list itself is non-null.

      Parameters:
      elements - at least one element; use literalEmptyList(DType) for an empty list, which has no element to take a type from

    • literalEmptyList

      public static Expression literalEmptyList(Expression.DType elementType)
      Create an empty list literal with the given nullable element type. It contains nothing, so nothing is in it.

    • nullLiteralList

      public static Expression nullLiteralList(Expression.DType elementType)
      Create a null list literal with the given nullable element type.

    • literalDecimal

      public static Expression literalDecimal(BigInteger unscaledValue, int precision, int scale)
      Create a decimal literal from its unscaled two's-complement big-endian byte representation (i.e. the value returned by BigInteger.toByteArray()).

    • nullLiteralDecimal

      public static Expression nullLiteralDecimal(int precision, int scale)
      Create a null decimal literal with the specified precision and scale.

    • literalDate

      public static Expression literalDate(long value, Expression.TimeUnit unit)
      Create a Date literal. The value is the number of unit units since the Unix epoch.
      Parameters:
      unit - only Expression.TimeUnit.DAYS and Expression.TimeUnit.MILLISECONDS are valid for Date.

    • nullLiteralDate

      public static Expression nullLiteralDate(Expression.TimeUnit unit)
      Null Date literal. See literalDate(long, TimeUnit) for the unit constraints.

    • literalTimestamp

      public static Expression literalTimestamp(long value, Expression.TimeUnit unit, String timezone)
      Create a Timestamp literal. The value is the number of unit units since the Unix epoch.
      Parameters:
      timezone - optional IANA timezone identifier (e.g. "UTC", "America/Los_Angeles"). Pass null for a local (zone-naive) timestamp.

    • nullLiteralTimestamp

      public static Expression nullLiteralTimestamp(Expression.TimeUnit unit, String timezone)
      Null Timestamp literal. See literalTimestamp(long, TimeUnit, String) for parameter semantics.

    • literal

      public static Expression literal(UUID value)
      Create a UUID literal, enabling predicate pushdown over UUID columns. The value is stored as its 16-byte big-endian (network order) representation, matching Vortex's UUID extension type and Arrow's canonical UUID type.

    • literalUuid

      public static Expression literalUuid(byte[] bigEndianBytes)
      Create a UUID literal from its 16-byte big-endian (network order) representation, for example the bytes of Arrow's canonical UUID type or a UUID serialized most-significant-bits first.
      Parameters:
      bigEndianBytes - exactly 16 bytes; use nullLiteralUuid() for a null literal

    • nullLiteralUuid

      public static Expression nullLiteralUuid()
      Create a null UUID literal.

    • nullLiteral

      public static Expression nullLiteral(Expression.DType dtype)
      Create a typed null literal of the given primitive Expression.DType.