Skip to main content

ScalarFnVTable

vortex_array::scalar_fn

Trait ScalarFnVTable 

Source 
pub trait ScalarFnVTable:
    'static
    + Sized
    + Clone
    + Send
    + Sync {
    type Options: 'static + Send + Sync + Clone + Debug + Display + PartialEq + Eq + Hash;


Show 17 methods    // Required methods
    fn id(&self) -> ScalarFnId;
    fn arity(&self, options: &Self::Options) -> Arity;
    fn child_name(&self, options: &Self::Options, child_idx: usize) -> ChildName;
    fn fmt_sql(
        &self,
        options: &Self::Options,
        expr: &Expression,
        f: &mut Formatter<'_>,
    ) -> Result;
    fn return_dtype(
        &self,
        options: &Self::Options,
        args: &[DType],
    ) -> VortexResult<DType>;
    fn execute(
        &self,
        options: &Self::Options,
        args: &dyn ExecutionArgs,
        ctx: &mut ExecutionCtx,
    ) -> VortexResult<ArrayRef>;

    // Provided methods
    fn serialize(
        &self,
        options: &Self::Options,
    ) -> VortexResult<Option<Vec<u8>>> { ... }
    fn deserialize(
        &self,
        _metadata: &[u8],
        _session: &VortexSession,
    ) -> VortexResult<Self::Options> { ... }
    fn coerce_args(
        &self,
        options: &Self::Options,
        args: &[DType],
    ) -> VortexResult<Vec<DType>> { ... }
    fn reduce(
        &self,
        options: &Self::Options,
        node: &dyn ReduceNode,
        ctx: &dyn ReduceCtx,
    ) -> VortexResult<Option<ReduceNodeRef>> { ... }
    fn simplify(
        &self,
        options: &Self::Options,
        expr: &Expression,
        ctx: &dyn SimplifyCtx,
    ) -> VortexResult<Option<Expression>> { ... }
    fn simplify_untyped(
        &self,
        options: &Self::Options,
        expr: &Expression,
    ) -> VortexResult<Option<Expression>> { ... }
    fn stat_falsification(
        &self,
        options: &Self::Options,
        expr: &Expression,
        catalog: &dyn StatsCatalog,
    ) -> Option<Expression> { ... }
    fn stat_expression(
        &self,
        options: &Self::Options,
        expr: &Expression,
        stat: Stat,
        catalog: &dyn StatsCatalog,
    ) -> Option<Expression> { ... }
    fn validity(
        &self,
        options: &Self::Options,
        expression: &Expression,
    ) -> VortexResult<Option<Expression>> { ... }
    fn is_null_sensitive(&self, options: &Self::Options) -> bool { ... }
    fn is_fallible(&self, options: &Self::Options) -> bool { ... }

}
Expand description

This trait defines the interface for scalar function vtables, including methods for serialization, deserialization, validation, child naming, return type computation, and evaluation.

This trait is non-object safe and allows the implementer to make use of associated types for improved type safety, while allowing Vortex to enforce runtime checks on the inputs and outputs of each function.

The ScalarFnVTable trait should be implemented for a struct that holds global data across all instances of the expression. In almost all cases, this struct will be an empty unit struct, since most expressions do not require any global state.

Required Associated Types§

Source

type Options: 'static + Send + Sync + Clone + Debug + Display + PartialEq + Eq + Hash

Options for this expression.

Required Methods§

Source

fn id(&self) -> ScalarFnId

Returns the ID of the scalar function vtable.

Source

fn arity(&self, options: &Self::Options) -> Arity

Returns the arity of this expression.

Source

fn child_name(&self, options: &Self::Options, child_idx: usize) -> ChildName

Returns the name of the nth child of the expr.

Source

fn fmt_sql( &self, options: &Self::Options, expr: &Expression, f: &mut Formatter<'_>, ) -> Result

Format this expression in a nice human-readable SQL-style format

The implementation should recursively format child expressions by calling expr.child(i).fmt_sql(f).

Source

fn return_dtype( &self, options: &Self::Options, args: &[DType], ) -> VortexResult<DType>

Compute the return DType of the expression if evaluated over the given input types.

§Preconditions

The length of args must match the Arity of this function. Callers are responsible for validating this (e.g., Expression::try_new checks arity at construction time). Implementations may assume correct arity and will panic or return nonsensical results if violated.

Source

fn execute( &self, options: &Self::Options, args: &dyn ExecutionArgs, ctx: &mut ExecutionCtx, ) -> VortexResult<ArrayRef>

Execute the expression over the input arguments.

Implementations are encouraged to check their inputs for constant arrays to perform more optimized execution.

If the input arguments cannot be directly used for execution (for example, an expression may require canonical input arrays), then the implementation should perform a single child execution and return a new crate::arrays::ScalarFnArray wrapping up the new child.

This provides maximum opportunities for array-level optimizations using execute_parent kernels.

Provided Methods§

Source

fn serialize(&self, options: &Self::Options) -> VortexResult<Option<Vec<u8>>>

Serialize the options for this expression.

Should return Ok(None) if the expression is not serializable, and Ok(vec![]) if it is serializable but has no metadata.

Source

fn deserialize( &self, _metadata: &[u8], _session: &VortexSession, ) -> VortexResult<Self::Options>

Deserialize the options of this expression.

Source

fn coerce_args( &self, options: &Self::Options, args: &[DType], ) -> VortexResult<Vec<DType>>

Coerce the arguments of this function.

This is optionally used by Vortex users when performing type coercion over a Vortex expression. Note that direct Vortex query engine integrations (e.g. DuckDB, DataFusion, etc.) do not perform type coercion and rely on the engine’s own logical planner.

Note that the default implementation simply returns the arguments without coercion, and it is expected that the ScalarFnVTable::return_dtype call may still fail.

Source

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

Implement an abstract reduction rule over a tree of scalar functions.

The ReduceNode can be used to traverse children, inspect their types, and construct the result expression.

Return Ok(None) if no reduction is possible.

Source

fn simplify( &self, options: &Self::Options, expr: &Expression, ctx: &dyn SimplifyCtx, ) -> VortexResult<Option<Expression>>

Simplify the expression if possible.

Source

fn simplify_untyped( &self, options: &Self::Options, expr: &Expression, ) -> VortexResult<Option<Expression>>

Simplify the expression if possible, without type information.

Source

fn stat_falsification( &self, options: &Self::Options, expr: &Expression, catalog: &dyn StatsCatalog, ) -> Option<Expression>

See Expression::stat_falsification.

Source

fn stat_expression( &self, options: &Self::Options, expr: &Expression, stat: Stat, catalog: &dyn StatsCatalog, ) -> Option<Expression>

See Expression::stat_expression.

Source

fn validity( &self, options: &Self::Options, expression: &Expression, ) -> VortexResult<Option<Expression>>

Returns an expression that evaluates to the validity of the result of this expression.

If a validity expression cannot be constructed, returns None and the expression will be evaluated as normal before extracting the validity mask from the result.

This is essentially a specialized form of a reduce_parent

Source

fn is_null_sensitive(&self, options: &Self::Options) -> bool

Returns whether this expression itself is null-sensitive. Conservatively default to true.

An expression is null-sensitive if it directly operates on null values, such as is_null. Most expressions are not null-sensitive.

The property we are interested in is if the expression (e) distributes over mask. Define a mask(a, m) expression that applies the boolean array m to the validity of the array a.

A unary expression e is not null-sensitive iff forall arrays a and masks m, e(mask(a, m)) == mask(e(a), m).

This can be extended to an n-ary expression.

This method only checks the expression itself, not its children.

Source

fn is_fallible(&self, options: &Self::Options) -> bool

Returns whether this expression is semantically fallible. Conservatively defaults to true.

An expression is semantically fallible if there exists a set of well-typed inputs that causes the expression to produce an error as part of its defined behavior. For example, checked_add is fallible because integer overflow is a domain error, and division is fallible because of division by zero.

This does not include execution errors that are incidental to the implementation, such as canonicalization failures, memory allocation errors, or encoding mismatches. Those can happen to any expression and are not what this method captures.

This property is used by optimizations that speculatively evaluate an expression over values that may not appear in the actual input. For example, pushing a scalar function down to a dictionary’s values array is only safe when the function is infallible or all values are referenced, since a fallible function might error on a value left unreferenced after slicing that would never be encountered during normal evaluation.

Note: this is only applicable to expressions that pass type-checking via ScalarFnVTable::return_dtype.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§