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<V: VTable>( vtable: V, data: V::Instance, children: impl Into<Arc<[Expression]>>, ) -> VortexResult<Self>

Create a new expression from a vtable.

pub fn new_static<V: VTable>( vtable: &'static V, data: V::Instance, children: impl Into<Arc<[Expression]>>, ) -> Self

Create a new expression from a static vtable.

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 execute(&self, vector: &Vector, dtype: &DType) -> VortexResult<Vector>

Executes the expression over the given vector input scope.

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.

See Self::stat_expression for details.

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

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

See Self::stat_expression for details.

pub fn is_null_sensitive(&self) -> bool

Returns whether this expression itself is null-sensitive. See VTable::is_null_sensitive.

pub fn is_fallible(&self) -> bool

Returns whether this expression itself is fallible. See VTable::is_fallible.

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