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 as 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 create an Expr which invokes 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 new_from_shared_impl(fun: Arc<dyn ScalarUDFImpl>) -> ScalarUDF

Create a new ScalarUDF from a [ScalarUDFImpl] trait object

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>, ) -> ScalarUDF

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, DataFusionError>

👎Deprecated since 50.0.0: This method is unused and will be removed in a future release

Returns this function’s display_name.

See ScalarUDFImpl::display_name for more details

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

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( &self, arg_types: &[DataType], ) -> Result<DataType, DataFusionError>

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

Notes

If a function implement ScalarUDFImpl::return_field_from_args, its ScalarUDFImpl::return_type should raise an error.

See ScalarUDFImpl::return_type for more details.

pub fn return_field_from_args( &self, args: ReturnFieldArgs<'_>, ) -> Result<Arc<Field>, DataFusionError>

Return the datatype this function returns given the input argument types.

See ScalarUDFImpl::return_field_from_args for more details.

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

Do the function rewrite

See ScalarUDFImpl::simplify for more details.

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

👎Deprecated since 50.0.0: Use return_field_from_args instead.

pub fn invoke_with_args( &self, args: ScalarFunctionArgs, ) -> Result<ColumnarValue, DataFusionError>

Invoke the function on args, returning the appropriate result.

See ScalarUDFImpl::invoke_with_args for details.

pub fn short_circuits(&self) -> bool

Get the circuits of inner implementation

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

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>>, DataFusionError>

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, DataFusionError>

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

pub fn preserves_lex_ordering( &self, inputs: &[ExprProperties], ) -> Result<bool, DataFusionError>

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

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.

pub fn as_async(&self) -> Option<&AsyncScalarUDF>

Return true if this function is an async function

Trait Implementations

impl Clone for ScalarUDF

fn clone(&self) -> ScalarUDF

Returns a duplicate 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<(), Error>

Formats the value using the given formatter.

impl<F> From<F> for ScalarUDF

where F: ScalarUDFImpl + 'static,

fn from(fun: F) -> ScalarUDF

Converts to this type from the input type.

impl Hash for ScalarUDF

fn hash<H>(&self, state: &mut H)

where H: Hasher,

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