Struct ScalarUDF

pub struct ScalarUDF { /* private fields */ }

Logical representation of a Scalar User Defined Function.

A scalar function produces a single row output for each row of input. This struct contains the information DataFusion needs to plan and invoke functions you supply such name, type signature, return type, and actual implementation.

1. For simple use cases, use create_udf (examples in simple_udf.rs).

2. For advanced use cases, use ScalarUDFImpl which provides full API access (examples in advanced_udf.rs).

See Self::call to invoke a ScalarUDF with arguments.

API Note

This is a separate struct from ScalarUDFImpl to maintain backwards compatibility with the older API.

Implementations

impl ScalarUDF

pub fn new_from_impl<F>(fun: F) -> ScalarUDF

where F: ScalarUDFImpl + 'static,

Create a new ScalarUDF from a [ScalarUDFImpl] trait object

Note this is the same as using the From impl (ScalarUDF::from)

pub fn inner(&self) -> &Arc<dyn ScalarUDFImpl>

Return the underlying ScalarUDFImpl trait object for this function

pub fn with_aliases( self, aliases: impl IntoIterator<Item = &'static str>, ) -> Self

Adds additional names that can be used to invoke this function, in addition to name

If you implement ScalarUDFImpl directly you should return aliases directly.

pub fn call(&self, args: Vec<Expr>) -> Expr

Returns a Expr logical expression to call this UDF with specified arguments.

This utility allows easily calling UDFs

Example

use datafusion_expr::{col, lit, ScalarUDF};
let my_func: ScalarUDF = my_udf();
// Create an expr for `my_func(a, 12.3)`
let expr = my_func.call(vec![col("a"), lit(12.3)]);

pub fn name(&self) -> &str

Returns this function’s name.

See ScalarUDFImpl::name for more details.

pub fn display_name(&self, args: &[Expr]) -> Result<String>

Returns this function’s display_name.

See ScalarUDFImpl::display_name for more details

pub fn schema_name(&self, args: &[Expr]) -> Result<String>

Returns this function’s schema_name.

See ScalarUDFImpl::schema_name for more details

pub fn aliases(&self) -> &[String]

Returns the aliases for this function.

See ScalarUDF::with_aliases for more details

pub fn signature(&self) -> &Signature

Returns this function’s Signature (what input types are accepted).

See ScalarUDFImpl::signature for more details.

pub fn return_type_from_exprs( &self, args: &[Expr], schema: &dyn ExprSchema, arg_types: &[DataType], ) -> Result<DataType>

The datatype this function returns given the input argument input types. This function is used when the input arguments are Exprs.

See ScalarUDFImpl::return_type_from_exprs for more details.

pub fn simplify( &self, args: Vec<Expr>, info: &dyn SimplifyInfo, ) -> Result<ExprSimplifyResult>

Do the function rewrite

See ScalarUDFImpl::simplify for more details.

pub fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue>

👎Deprecated since 42.1.0: Use invoke_batch instead

Invoke the function on args, returning the appropriate result.

See ScalarUDFImpl::invoke for more details.

pub fn is_nullable(&self, args: &[Expr], schema: &dyn ExprSchema) -> bool

pub fn invoke_batch( &self, args: &[ColumnarValue], number_rows: usize, ) -> Result<ColumnarValue>

Invoke the function with args and number of rows, returning the appropriate result.

See ScalarUDFImpl::invoke_batch for more details.

pub fn invoke_no_args(&self, number_rows: usize) -> Result<ColumnarValue>

👎Deprecated since 42.1.0: Use invoke_batch instead

Invoke the function without args but number of rows, returning the appropriate result.

See ScalarUDFImpl::invoke_no_args for more details.

pub fn fun(&self) -> ScalarFunctionImplementation

👎Deprecated since 42.0.0: Use invoke_batch instead

Returns a ScalarFunctionImplementation that can invoke the function during execution

pub fn short_circuits(&self) -> bool

Get the circuits of inner implementation

pub fn evaluate_bounds(&self, inputs: &[&Interval]) -> Result<Interval>

Computes the output interval for a ScalarUDF, given the input intervals.

Parameters

• inputs are the intervals for the inputs (children) of this function.

Example

If the function is ABS(a), and the input interval is a: [-3, 2], then the output interval would be [0, 3].

pub fn propagate_constraints( &self, interval: &Interval, inputs: &[&Interval], ) -> Result<Option<Vec<Interval>>>

Updates bounds for child expressions, given a known interval for this function. This is used to propagate constraints down through an expression tree.

Parameters

• interval is the currently known interval for this function.
• inputs are the current intervals for the inputs (children) of this function.

Returns

A Vec of new intervals for the children, in order.

If constraint propagation reveals an infeasibility for any child, returns None. If none of the children intervals change as a result of propagation, may return an empty vector instead of cloning children. This is the default (and conservative) return value.

Example

If the function is ABS(a), the current interval is [4, 5] and the input a is given as [-7, 3], then propagation would return [-5, 3].

pub fn output_ordering( &self, inputs: &[ExprProperties], ) -> Result<SortProperties>

Calculates the SortProperties of this function based on its children’s properties.

pub fn coerce_types(&self, arg_types: &[DataType]) -> Result<Vec<DataType>>

See ScalarUDFImpl::coerce_types for more details.

pub fn documentation(&self) -> Option<&Documentation>

Returns the documentation for this Scalar UDF.

Documentation can be accessed programmatically as well as generating publicly facing documentation.

Trait Implementations

impl Clone for ScalarUDF

fn clone(&self) -> ScalarUDF

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ScalarUDF

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

Formats the value using the given formatter.

impl<F> From<F> for ScalarUDF

where F: ScalarUDFImpl + Send + Sync + 'static,

fn from(fun: F) -> Self

Converts to this type from the input type.

impl Hash for ScalarUDF

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 PartialEq for ScalarUDF

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 PartialOrd for ScalarUDF

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for ScalarUDF