Enum Expression 

pub enum Expression {
    Scalar {
        scalar_fn: ScalarFnRef,
        children: Arc<Vec<Expression>>,
    },
    Root,
}

A node in a Vortex expression tree.

Most nodes are a scalar function applied to child expressions. Expression::Root is the scope itself: a language primitive rather than a registered function, because its dtype comes from the scope rather than from children and it is not executable. A ScalarFnVTable can answer neither of those, so Root is a variant instead.

Variants

Scalar

A scalar function applied to child expressions.

Fields

scalar_fn: ScalarFnRef

The scalar fn for this node.

children: Arc<Vec<Expression>>

Any children of this expression.

Root

The full scope of the expression evaluation.

Implementations

impl Expression

pub fn bind(&self, dtype: &DType) -> VortexResult<BoundExpression>

Bind this expression against a root dtype, type-checking every node in a single walk.

The returned tree carries a dtype on each node, so callers needing types at more than one node should bind once and read fields rather than calling return_dtype repeatedly.

pub fn bind_scope(&self, scope: &Scope) -> VortexResult<BoundExpression>

Bind this expression against an explicit Scope.

impl Expression

pub fn try_new( scalar_fn: ScalarFnRef, children: impl IntoIterator<Item = Expression>, ) -> VortexResult<Self>

Create a new expression node from a scalar_fn expression and its children.

pub fn is_root(&self) -> bool

Whether this expression is the scope root.

pub fn as_scalar(&self) -> Option<&ScalarFnRef>

Returns the scalar fn for this expression, or None if it is not a scalar node.

pub fn is<V: ScalarFnVTable>(&self) -> bool

Whether this expression’s scalar fn is of the given vtable type.

pub fn as_opt<V: ScalarFnVTable>(&self) -> Option<&V::Options>

The typed options for this expression if its scalar fn matches the given vtable type.

pub fn as_<V: ScalarFnVTable>(&self) -> &V::Options

The typed options for this expression.

Panics

Panics if the vtable type does not match.

pub fn children(&self) -> &[Expression]

Returns the children of this expression.

pub fn child(&self, n: usize) -> &Expression

Returns the n’th child of this expression.

pub fn with_children( self, children: impl IntoIterator<Item = Expression>, ) -> VortexResult<Self>

Replace the children of this expression with the provided new children.

pub fn return_dtype(&self, scope: &DType) -> VortexResult<DType>

Computes the return dtype of this expression given the input dtype.

pub fn validity(&self) -> VortexResult<Expression>

Returns a new expression representing the validity mask output of this expression.

The returned expression evaluates to a non-nullable boolean array.

pub fn fmt_sql(&self, f: &mut Formatter<'_>) -> Result

Format the expression as a compact string.

Since this is a recursive formatter, it is exposed on the public Expression type. See fmt_data that is only implemented on the vtable trait.

pub fn display_tree(&self) -> impl Display

Display the expression as a formatted tree structure.

This provides a hierarchical view of the expression that shows the relationships between parent and child expressions, making complex nested expressions easier to understand and debug.

Example

// Build a complex nested expression
let complex_expr = select(
    ["result"],
    and(
        not(eq(get_item("status", root()), lit("inactive"))),
        and(
            Like.new_expr(LikeOptions::default(), [get_item("name", root()), lit("%admin%")]),
            gt(
                cast(get_item("score", root()), DType::Primitive(PType::F64, Nullability::NonNullable)),
                lit(75.0)
            )
        )
    )
);

println!("{}", complex_expr.display_tree());

This produces output like:

Select(include): {result}
└── Binary(and)
    ├── lhs: Not
    │   └── Binary(=)
    │       ├── lhs: GetItem(status)
    │       │   └── Root
    │       └── rhs: Literal(value: "inactive", dtype: utf8)
    └── rhs: Binary(and)
        ├── lhs: Like
        │   ├── child: GetItem(name)
        │   │   └── Root
        │   └── pattern: Literal(value: "%admin%", dtype: utf8)
        └── rhs: Binary(>)
            ├── lhs: Cast(target: f64)
            │   └── GetItem(score)
            │       └── Root
            └── rhs: Literal(value: 75f64, dtype: f64)

pub fn contains<E: ScalarFnVTable>(&self) -> VortexResult<bool>

Returns true if this expression contains expression E inside.

Example

let expression = &eq(root(), lit(3u64));
assert!(expression.contains::<Literal>().unwrap());
let expression = root();
assert!(!expression.contains::<Literal>().unwrap());

impl Expression

pub fn optimize(&self, scope: &DType) -> VortexResult<Expression>

Optimize the root expression node only, iterating to convergence.

This applies optimization rules repeatedly until no more changes occur:

1. simplify_untyped - type-independent simplifications
2. simplify - type-aware simplifications
3. reduce - abstract reduction rules via ReduceNode

pub fn optimize_recursive(&self, scope: &DType) -> VortexResult<Expression>

Optimize the entire expression tree recursively.

Optimizes children first (bottom-up), then optimizes the root.

pub fn try_optimize_recursive( &self, scope: &DType, ) -> VortexResult<Option<Expression>>

Try to optimize the entire expression tree recursively.

impl Expression

pub fn from_proto( expr: &Expr, session: &VortexSession, ) -> VortexResult<Expression>

Trait Implementations

impl Clone for Expression

fn clone(&self) -> Expression

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Expression

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Expression

The default display implementation for expressions uses the ‘SQL’-style format.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Expression

Iterative drop for expression to avoid stack overflows.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Eq for Expression

impl ExprBuiltins for Expression

fn cast(&self, dtype: DType) -> VortexResult<Expression>

Cast to the given data type.

fn fill_null(&self, fill_value: Expression) -> VortexResult<Expression>

Replace null values with the given fill value.

fn get_item(&self, field_name: impl Into<FieldName>) -> VortexResult<Expression>

Get item by field name (for struct types).

fn is_null(&self) -> VortexResult<Expression>

Is null check.

fn is_not_null(&self) -> VortexResult<Expression>

Is not null check.

fn mask(&self, mask: Expression) -> VortexResult<Expression>

Mask the expression using the given boolean mask. The resulting expression’s validity is the intersection of the original expression’s validity.

fn not(&self) -> VortexResult<Expression>

Boolean negation.

fn list_contains(&self, value: Expression) -> VortexResult<Expression>

Check if a list contains a value.

fn zip( &self, if_true: Expression, if_false: Expression, ) -> VortexResult<Expression>

Conditional selection: result[i] = if mask[i] then if_true[i] else if_false[i].

fn binary(&self, rhs: Expression, op: Operator) -> VortexResult<Expression>

Apply a binary operator to this expression and another.

impl ExprDisplay for Expression

fn display_child(&self, index: usize) -> &dyn ExprDisplay

Return the child at index.

fn display_children_count(&self) -> usize

Return the number of children in this node.

impl ExprSerializeProtoExt for Expression

fn serialize_proto(&self) -> VortexResult<Expr>

Serialize the expression to its protobuf representation.

impl Hash for Expression

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Node for Expression

fn apply_children<'a, F: FnMut(&'a Self) -> VortexResult<TraversalOrder>>( &'a self, f: F, ) -> VortexResult<TraversalOrder>

Walk the node’s children by applying f to them.

fn map_children<F: FnMut(Self) -> VortexResult<Transformed<Self>>>( self, f: F, ) -> VortexResult<Transformed<Self>>

Rewrite the node’s children by applying f to them.

fn iter_children<T>( &self, f: impl FnOnce(&mut dyn Iterator<Item = &Self>) -> T, ) -> T

This is a lower level API that other functions rely on for their implementation.

fn children_count(&self) -> usize

This is a lower level API that other functions rely on for their implementation.

impl<'a> NodeContainer<'a, Expression> for Expression

fn apply_elements<F: FnMut(&'a Self) -> VortexResult<TraversalOrder>>( &'a self, f: F, ) -> VortexResult<TraversalOrder>

Applies f to all elements of the container, accepting them by reference

fn map_elements<F: FnMut(Self) -> VortexResult<Transformed<Self>>>( self, f: F, ) -> VortexResult<Transformed<Self>>

Consumes all the children of the node, replacing them with the result of f.

impl PartialEq for Expression

fn eq(&self, other: &Expression) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Expression

impl VortexExprExt for Expression

fn field_references(&self) -> HashSet<FieldName>

Accumulate all field references from this expression and its children in a set