diff --git a/datafusion/expr/src/udf.rs b/datafusion/expr/src/udf.rs index 0e78b4a6d42f..57b8d9c6b02e 100644 --- a/datafusion/expr/src/udf.rs +++ b/datafusion/expr/src/udf.rs @@ -203,7 +203,7 @@ impl ScalarUDF { self.inner.simplify(args, info) } - #[deprecated(since = "42.1.0", note = "Use `invoke_batch` instead")] + #[deprecated(since = "42.1.0", note = "Use `invoke_with_args` instead")] pub fn invoke(&self, args: &[ColumnarValue]) -> Result { #[allow(deprecated)] self.inner.invoke(args) @@ -213,7 +213,7 @@ impl ScalarUDF { self.inner.is_nullable(args, schema) } - #[deprecated(since = "43.0.0", note = "Use `invoke_batch` instead")] + #[deprecated(since = "43.0.0", note = "Use `invoke_with_args` instead")] pub fn invoke_batch( &self, args: &[ColumnarValue], @@ -225,14 +225,15 @@ impl ScalarUDF { /// Invoke the function on `args`, returning the appropriate result. /// - /// See [`ScalarUDFImpl::invoke_with_args`] for more details. + /// See [`ScalarUDFImpl::invoke_with_args`] for details. pub fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result { self.inner.invoke_with_args(args) } /// Invoke the function without `args` but number of rows, returning the appropriate result. /// - /// See [`ScalarUDFImpl::invoke_no_args`] for more details. + /// Note: This method is deprecated and will be removed in future releases. + /// User defined functions should implement [`Self::invoke_with_args`] instead. #[deprecated(since = "42.1.0", note = "Use `invoke_batch` instead")] pub fn invoke_no_args(&self, number_rows: usize) -> Result { #[allow(deprecated)] @@ -337,7 +338,7 @@ pub struct ScalarFunctionArgs<'a> { pub return_type: &'a DataType, } -/// Trait for implementing [`ScalarUDF`]. +/// Trait for implementing user defined scalar functions. /// /// This trait exposes the full API for implementing user defined functions and /// can be used to implement any function. @@ -345,18 +346,19 @@ pub struct ScalarFunctionArgs<'a> { /// See [`advanced_udf.rs`] for a full example with complete implementation and /// [`ScalarUDF`] for other available options. /// -/// /// [`advanced_udf.rs`]: https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/advanced_udf.rs +/// /// # Basic Example /// ``` /// # use std::any::Any; /// # use std::sync::OnceLock; /// # use arrow::datatypes::DataType; /// # use datafusion_common::{DataFusionError, plan_err, Result}; -/// # use datafusion_expr::{col, ColumnarValue, Documentation, Signature, Volatility}; +/// # use datafusion_expr::{col, ColumnarValue, Documentation, ScalarFunctionArgs, Signature, Volatility}; /// # use datafusion_expr::{ScalarUDFImpl, ScalarUDF}; /// # use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; /// +/// /// This struct for a simple UDF that adds one to an int32 /// #[derive(Debug)] /// struct AddOne { /// signature: Signature, @@ -396,7 +398,9 @@ pub struct ScalarFunctionArgs<'a> { /// Ok(DataType::Int32) /// } /// // The actual implementation would add one to the argument -/// fn invoke(&self, args: &[ColumnarValue]) -> Result { unimplemented!() } +/// fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result { +/// unimplemented!() +/// } /// fn documentation(&self) -> Option<&Documentation> { /// Some(get_doc()) /// } @@ -492,24 +496,9 @@ pub trait ScalarUDFImpl: Debug + Send + Sync { /// Invoke the function on `args`, returning the appropriate result /// - /// The function will be invoked passed with the slice of [`ColumnarValue`] - /// (either scalar or array). - /// - /// If the function does not take any arguments, please use [invoke_no_args] - /// instead and return [not_impl_err] for this function. - /// - /// - /// # Performance - /// - /// For the best performance, the implementations of `invoke` should handle - /// the common case when one or more of their arguments are constant values - /// (aka [`ColumnarValue::Scalar`]). - /// - /// [`ColumnarValue::values_to_arrays`] can be used to convert the arguments - /// to arrays, which will likely be simpler code, but be slower. - /// - /// [invoke_no_args]: ScalarUDFImpl::invoke_no_args - #[deprecated(since = "42.1.0", note = "Use `invoke_batch` instead")] + /// Note: This method is deprecated and will be removed in future releases. + /// User defined functions should implement [`Self::invoke_with_args`] instead. + #[deprecated(since = "42.1.0", note = "Use `invoke_with_args` instead")] fn invoke(&self, _args: &[ColumnarValue]) -> Result { not_impl_err!( "Function {} does not implement invoke but called", @@ -520,18 +509,12 @@ pub trait ScalarUDFImpl: Debug + Send + Sync { /// Invoke the function with `args` and the number of rows, /// returning the appropriate result. /// - /// The function will be invoked with the slice of [`ColumnarValue`] - /// (either scalar or array). - /// - /// # Performance + /// Note: See notes on [`Self::invoke_with_args`] /// - /// For the best performance, the implementations should handle the common case - /// when one or more of their arguments are constant values (aka - /// [`ColumnarValue::Scalar`]). + /// Note: This method is deprecated and will be removed in future releases. + /// User defined functions should implement [`Self::invoke_with_args`] instead. /// - /// [`ColumnarValue::values_to_arrays`] can be used to convert the arguments - /// to arrays, which will likely be simpler code, but be slower. - #[deprecated(since = "43.0.0", note = "Use `invoke_with_args` instead")] + /// See for more details. fn invoke_batch( &self, args: &[ColumnarValue], @@ -551,9 +534,7 @@ pub trait ScalarUDFImpl: Debug + Send + Sync { } } - /// Invoke the function with `args: ScalarFunctionArgs` returning the appropriate result. - /// - /// The function will be invoked with a struct `ScalarFunctionArgs` + /// Invoke the function returning the appropriate result. /// /// # Performance /// @@ -570,7 +551,10 @@ pub trait ScalarUDFImpl: Debug + Send + Sync { /// Invoke the function without `args`, instead the number of rows are provided, /// returning the appropriate result. - #[deprecated(since = "42.1.0", note = "Use `invoke_batch` instead")] + /// + /// Note: This method is deprecated and will be removed in future releases. + /// User defined functions should implement [`Self::invoke_with_args`] instead. + #[deprecated(since = "42.1.0", note = "Use `invoke_with_args` instead")] fn invoke_no_args(&self, _number_rows: usize) -> Result { not_impl_err!( "Function {} does not implement invoke_no_args but called",