Struct Expression 

pub struct Expression { /* private fields */ }

A node in a Vortex expression tree.

Expressions represent scalar computations that can be performed on data. Each expression consists of an encoding (vtable), heap-allocated metadata, and child expressions.

Implementations

impl Expression

pub fn try_new( scalar_fn: ScalarFn, children: impl Into<Arc<[Expression]>>, ) -> VortexResult<Self>

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

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

Returns true if this expression is of the given vtable type.

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

Returns the typed options for this expression if it matches the given vtable type.

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

Returns the typed options for this expression if it matches the given vtable type.

pub fn scalar_fn(&self) -> &ScalarFn

Returns the scalar fn vtable for this expression.

pub fn children(&self) -> &Arc<[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 Into<Arc<[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 evaluate(&self, scope: &ArrayRef) -> VortexResult<ArrayRef>

Evaluates the expression in the given scope, returning an array.

pub fn stat_falsification( &self, catalog: &dyn StatsCatalog, ) -> Option<Expression>

An expression over zone-statistics which implies all records in the zone evaluate to false.

Given an expression, e, if e.stat_falsification(..) evaluates to true, it is guaranteed that e evaluates to false on all records in the zone. However, the inverse is not necessarily true: even if the falsification evaluates to false, e need not evaluate to true on all records.

The StatsCatalog can be used to constrain or rename stats used in the final expr.

Examples

• An expression over one variable: x > 0 is false for all records in a zone if the maximum value of the column x in that zone is less than or equal to zero: max(x) <= 0.
• An expression over two variables: x > y becomes max(x) <= min(y).
• A conjunctive expression: x > y AND z < x becomes `max(x) <= min(y) OR min(z) >= max(x).

Some expressions, in theory, have falsifications but this function does not support them such as x < (y < z) or x LIKE "needle%".

pub fn stat_expression( &self, stat: Stat, catalog: &dyn StatsCatalog, ) -> Option<Expression>

Returns an expression representing the zoned statistic for the given stat, if available.

The StatsCatalog returns expressions that can be evaluated using the zone map as a scope. Expressions can implement this function to propagate such statistics through the expression tree. For example, the a + 10 expression could propagate min: min(a) + 10.

NOTE(gatesn): we currently cannot represent statistics over nested fields. Please file an issue to discuss a solution to this.

pub fn stat_min(&self, catalog: &dyn StatsCatalog) -> Option<Expression>

Returns an expression representing the zoned maximum statistic, if available.

pub fn stat_max(&self, catalog: &dyn StatsCatalog) -> Option<Expression>

Returns an expression representing the zoned maximum statistic, if available.

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)

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/ReduceCtx

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

Try to optimize the root expression node only, returning None if no optimizations applied.

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.

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

👎Deprecated: Use Expression::optimize_recursive instead

Simplify the expression, returning a potentially new expression.

Deprecated: Use Expression::optimize_recursive instead, which iterates to convergence.

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

👎Deprecated: Use Expression::optimize_recursive instead

Simplify the expression without type information.

Deprecated: Use Expression::optimize_recursive instead.

Methods from Deref<Target = ScalarFn>

pub fn vtable(&self) -> &ExprVTable

The vtable for this expression.

pub fn id(&self) -> ExprId

Returns the ID of this expression.

pub fn options(&self) -> ExpressionOptions<'_>

The type-erased options for this expression.

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

Returns whether the scalar function is of the given vtable type.

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

Returns the typed options for this expression if it matches the given vtable type.

pub fn signature(&self) -> ExpressionSignature<'_>

Signature information for this expression.

pub fn return_dtype(&self, arg_types: &[DType]) -> VortexResult<DType>

Compute the return DType of this expression given the input argument types.

pub fn evaluate( &self, expr: &Expression, scope: &ArrayRef, ) -> VortexResult<ArrayRef>

Evaluate the expression, returning an ArrayRef.

NOTE: this function will soon be deprecated as all expressions will evaluate trivially into an ExprArray.

pub fn execute(&self, ctx: ExecutionArgs) -> VortexResult<Datum>

Execute the expression given the input arguments.

pub fn reduce( &self, node: &dyn ReduceNode, ctx: &dyn ReduceCtx, ) -> VortexResult<Option<ReduceNodeRef>>

Perform abstract reduction on this scalar function node.

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 Deref for Expression

type Target = ScalarFn

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

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 ExprBuiltins for Expression

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

Cast to the given data type.

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

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl VortexExprExt for Expression

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

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

impl Eq for Expression

impl StructuralPartialEq for Expression