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( vtable: ExprVTable, data: Arc<dyn Any + Send + Sync>, children: Arc<[Expression]>, ) -> VortexResult<Self>

Creates a new expression with the given encoding, metadata, and children.

Errors

Returns an error if the provided encoding is not compatible with the metadata and children or the encoding’s own validation logic fails.

pub unsafe fn new_unchecked( vtable: ExprVTable, data: Arc<dyn Any + Send + Sync>, children: Arc<[Expression]>, ) -> Self

Creates a new expression with the given encoding, metadata, and children.

Safety

The caller must ensure that the provided encoding is compatible with the metadata and children. Failure to do so may lead to undefined behavior when the expression is used.

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

Returns if the expression is an instance of the given vtable.

pub fn as_<V: VTable>(&self) -> ExpressionView<'_, V>

Returns a typed view of this expression for the given vtable.

Panics

Panics if the expression’s encoding or metadata cannot be cast to the specified vtable.

pub fn as_opt<V: VTable>(&self) -> Option<ExpressionView<'_, V>>

Returns a typed view of this expression for the given vtable, if the types match.

pub fn id(&self) -> ExprId

Returns the expression ID.

pub fn vtable(&self) -> &ExprVTable

Returns the expression’s vtable.

pub fn data(&self) -> &Arc<dyn Any + Send + Sync>

Returns the opaque data of the 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 child_name(&self, n: usize) -> ChildName

Returns the name of 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 serialize_metadata(&self) -> VortexResult<Option<Vec<u8>>>

Returns the serialized metadata for this expression.

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.

pub fn stat_falsification( &self, catalog: &mut 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_max(&self, catalog: &mut dyn StatsCatalog) -> Option<Expression>

An expression for the upper non-null bound of this expression, if available.

This function returns None if there is no upper bound, or it is difficult to compute.

The returned expression evaluates to null if the maximum value is unknown. In that case, you must not assume the array is empty nor may you assume the array only contains non-null values.

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

An expression for the lower non-null bound of this expression, if available.

See Expression::stat_max for important details.

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

An expression for the NaN count for a column, if available.

This method returns None if the NaNCount stat is unknown.

pub fn stat_field_path(&self) -> Option<FieldPath>

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 fmt_data(&self, f: &mut Formatter<'_>) -> Result

Format the instance data of the expression as a string for rendering..

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)

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 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: &Self) -> 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