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)

    • spatial

      public static Expression spatial(Expression.SpatialFunction function, Expression... operands)
      Apply a spatial function to native geometry operands, each a column or a geometry literal (see literalGeometry(byte[])). The number of operands must match the function's arity.

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

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

    • literalU8

      public static Expression literalU8(int value)
      Create an unsigned 8-bit integer literal. value must be in [0, 255].

    • literalU16

      public static Expression literalU16(int value)
      Create an unsigned 16-bit integer literal. value must be in [0, 65535].

    • literalU32

      public static Expression literalU32(long value)
      Create an unsigned 32-bit integer literal. value must be in [0, 2^32 - 1].

    • literalU64

      public static Expression literalU64(long bits)
      Create an unsigned 64-bit integer literal from its bit pattern, so values above Long.MAX_VALUE are passed as negative longs (for example via Long.parseUnsignedLong(String)).

    • literalU64

      public static Expression literalU64(BigInteger value)
      Create an unsigned 64-bit integer literal. value must be in [0, 2^64 - 1].

    • literalF16

      public static Expression literalF16(float value)
      Create a half-precision float literal, rounding value to the nearest representable half.

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

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

    • literalTime

      public static Expression literalTime(long value, Expression.TimeUnit unit)
      Create a Time (time-of-day) literal. The value is the number of unit units since midnight.
      Parameters:
      unit - any unit except Expression.TimeUnit.DAYS. Expression.TimeUnit.SECONDS and Expression.TimeUnit.MILLISECONDS values must fit in an int.

    • nullLiteralTime

      public static Expression nullLiteralTime(Expression.TimeUnit unit)
      Null Time literal. See literalTime(long, TimeUnit) for the unit constraints.

    • literalGeometry

      public static Expression literalGeometry(byte[] wkb)
      Create a geometry literal from its OGC Well-Known Binary (WKB) encoding, for use with Vortex's spatial functions and predicate pushdown over geometry columns.

      The value is decoded into the native Vortex geometry type matching its kind: Point, LineString, Polygon, MultiPoint, MultiLineString or MultiPolygon, in XY with no coordinate reference system. Geometry collections and malformed WKB are rejected.

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

    • literalList

      public static Expression literalList(Expression elementType, boolean elementsNullable, Expression... elements)
      Create a list literal.

      Composite literals are assembled from other literal expressions. The element dtype is the dtype of the elementType literal (typically a typed null such as nullLiteral(DType.I32)) with nullability elementsNullable, and every element, which must itself be a literal, is cast to it.

    • nullLiteralList

      public static Expression nullLiteralList(Expression elementType, boolean elementsNullable)
      Null list literal. See literalList(Expression, boolean, Expression...) for the element dtype.

    • literalFixedSizeList

      public static Expression literalFixedSizeList(Expression elementType, boolean elementsNullable, Expression... elements)
      Create a fixed-size list literal whose size is the number of elements. The element dtype follows literalList(Expression, boolean, Expression...).

    • nullLiteralFixedSizeList

      public static Expression nullLiteralFixedSizeList(Expression elementType, boolean elementsNullable, int size)
      Null fixed-size list literal of size elements.

    • literalStruct

      public static Expression literalStruct(String[] fieldNames, Expression[] fields)
      Create a struct literal. Each field must be a literal expression; its dtype becomes the field's dtype.

    • nullLiteralStruct

      public static Expression nullLiteralStruct(String[] fieldNames, Expression[] fieldTypes)
      Create a null struct literal. fieldTypes are literals (typically typed nulls) whose dtypes become the struct's field dtypes.

    • literalMap

      public static Expression literalMap(Expression keyType, Expression valueType, boolean valuesNullable, Expression[] keys, Expression[] values)
      Create a map literal from parallel arrays of literal keys and values.

      Keys are cast to the non-nullable dtype of the keyType literal, and values to the dtype of the valueType literal with nullability valuesNullable. Keys are not asserted to be sorted.

    • nullLiteralMap

      public static Expression nullLiteralMap(Expression keyType, Expression valueType, boolean valuesNullable)
      Null map literal. See literalMap(dev.vortex.api.Expression, dev.vortex.api.Expression, boolean, dev.vortex.api.Expression[], dev.vortex.api.Expression[]) for how the key and value dtypes are derived.