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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Expression.BinaryOp	Binary operator codes; must match the Rust parse_op table.
static enum	Expression.DType	Primitive Expression.DTypes that can be used to construct typed null literals via nullLiteral(DType).
static enum	Expression.DuplicateHandling	Strategy for resolving duplicate field names in merge(DuplicateHandling, Expression...).
static enum	Expression.TimeUnit	Time units for Date/Timestamp literals.

Method Summary

Modifier and Type	Method	Description
static Expression	and(Expression... operands)	Logical AND.
static Expression	between(Expression value, Expression lower, Expression upper, boolean lowerStrict, boolean upperStrict)	value BETWEEN lower AND upper.
static Expression	binary(Expression.BinaryOp op, Expression lhs, Expression rhs)
static Expression	column(String fieldName)	Shortcut for getItem(fieldName, root()).
static Expression	column(String[] fieldNames)	Access a nested field by walking fieldNames starting from the root of the array.
static Expression	getItem(String fieldName, Expression child)	Access a named field from a struct expression.
static Expression	isNotNull(Expression child)
static Expression	isNull(Expression child)
static Expression	like(Expression child, Expression pattern, boolean negated, boolean caseInsensitive)	SQL LIKE pattern match.
static Expression	literal(boolean value)
static Expression	literal(byte value)
static Expression	literal(byte[] value)
static Expression	literal(double value)
static Expression	literal(float value)
static Expression	literal(int value)
static Expression	literal(long value)
static Expression	literal(short value)
static Expression	literal(String value)
static Expression	literal(UUID value)	Create a UUID literal, enabling predicate pushdown over UUID columns.
static Expression	literalDate(long value, Expression.TimeUnit unit)	Create a Date literal.
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.
static Expression	literalTimestamp(long value, Expression.TimeUnit unit, String timezone)	Create a Timestamp literal.
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.
static Expression	merge(Expression... expressions)	Merge struct expressions, failing if any field name is duplicated.
static Expression	merge(Expression.DuplicateHandling duplicateHandling, Expression... expressions)	Merge struct expressions into a single struct, combining their fields in order.
static Expression	not(Expression child)
static Expression	nullLiteral(Expression.DType dtype)	Create a typed null literal of the given primitive Expression.DType.
static Expression	nullLiteralBool()
static Expression	nullLiteralDate(Expression.TimeUnit unit)	Null Date literal.
static Expression	nullLiteralDecimal(int precision, int scale)	Create a null decimal literal with the specified precision and scale.
static Expression	nullLiteralTimestamp(Expression.TimeUnit unit, String timezone)	Null Timestamp literal.
static Expression	nullLiteralUuid()	Create a null UUID literal.
static Expression	or(Expression... operands)	Logical OR.
static Expression	pack(String[] fieldNames, Expression[] expressions, boolean nullable)	Creates an expression that packs values into a struct with named fields.
static Expression	root()	The root expression: applying it to an array yields the array itself.
static Expression	rowIdx()	The row-index expression.
static Expression	select(String[] fieldNames, Expression child)	Project a subset of fields out of a struct expression.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

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)

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.