Merge pull request #3 from alamb/alamb/docs_and_dep

Do not yet deprecate `invoke_batch`, add docs to invoke_with_args

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<ColumnarValue> {
         #[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<ColumnarValue> {
         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<ColumnarValue> {
         #[allow(deprecated)]
@@ -337,26 +338,27 @@ 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.
 ///
 /// 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<ColumnarValue> { unimplemented!() }
+///    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+///         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<ColumnarValue> {
         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 <https://github.com/apache/datafusion/issues/13515> 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<ColumnarValue> {
         not_impl_err!(
             "Function {} does not implement invoke_no_args but called",