diff --git a/datafusion/functions-nested/src/array_product.rs b/datafusion/functions-nested/src/array_product.rs new file mode 100644 index 0000000000000..a5cef43142fa0 --- /dev/null +++ b/datafusion/functions-nested/src/array_product.rs @@ -0,0 +1,174 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! [`ScalarUDFImpl`] definitions for array_product function. + +use crate::utils::make_scalar_function; +use arrow::array::{Array, ArrayRef, Float64Array, OffsetSizeTrait}; +use arrow::datatypes::{ + DataType, + DataType::{FixedSizeList, LargeList, List, Null}, + Field, +}; +use datafusion_common::cast::{as_float64_array, as_generic_list_array}; +use datafusion_common::utils::{ListCoercion, coerced_type_with_base_type_only}; +use datafusion_common::{Result, internal_err, plan_err, utils::take_function_args}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Volatility, +}; +use datafusion_macros::user_doc; +use std::sync::Arc; + +make_udf_expr_and_func!( + ArrayProduct, + array_product, + array, + "returns the product of the elements of a numeric array.", + array_product_udf +); + +#[user_doc( + doc_section(label = "Array Functions"), + description = "Returns the product of the elements in the input numeric array. \ + NULL elements inside the array are skipped (matching SQL aggregate \ + convention). Returns NULL if the input is NULL, every element is \ + NULL, or the array is empty. The result is always returned as \ + `Float64`.", + syntax_example = "array_product(array)", + sql_example = r#"```sql +> select array_product([1.0, 2.0, 3.0]); ++------------------------------------+ +| array_product(List([1.0,2.0,3.0])) | ++------------------------------------+ +| 6.0 | ++------------------------------------+ +```"#, + argument( + name = "array", + description = "Array expression. Can be a constant, column, or function, and any combination of array operators." + ) +)] +#[derive(Debug, PartialEq, Eq, Hash)] +pub struct ArrayProduct { + signature: Signature, + aliases: Vec, +} + +impl Default for ArrayProduct { + fn default() -> Self { + Self::new() + } +} + +impl ArrayProduct { + pub fn new() -> Self { + Self { + signature: Signature::user_defined(Volatility::Immutable), + aliases: vec!["list_product".to_string()], + } + } +} + +impl ScalarUDFImpl for ArrayProduct { + fn name(&self) -> &str { + "array_product" + } + + fn signature(&self) -> &Signature { + &self.signature + } + + fn return_type(&self, _arg_types: &[DataType]) -> Result { + Ok(DataType::Float64) + } + + fn coerce_types(&self, arg_types: &[DataType]) -> Result> { + let [arg_type] = take_function_args(self.name(), arg_types)?; + let coercion = Some(&ListCoercion::FixedSizedListToList); + + if !matches!(arg_type, Null | List(_) | LargeList(_) | FixedSizeList(..)) { + return plan_err!("{} does not support type {arg_type}", self.name()); + } + + let coerced = if matches!(arg_type, Null) { + List(Arc::new(Field::new_list_field(DataType::Float64, true))) + } else { + coerced_type_with_base_type_only(arg_type, &DataType::Float64, coercion) + }; + + Ok(vec![coerced]) + } + + fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result { + make_scalar_function(array_product_inner)(&args.args) + } + + fn aliases(&self) -> &[String] { + &self.aliases + } + + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } +} + +fn array_product_inner(args: &[ArrayRef]) -> Result { + let [array] = take_function_args("array_product", args)?; + match array.data_type() { + List(_) => general_array_product::(args), + LargeList(_) => general_array_product::(args), + arg_type => internal_err!( + "array_product received unexpected type after coercion: {arg_type}" + ), + } +} + +fn general_array_product(arrays: &[ArrayRef]) -> Result { + let list_array = as_generic_list_array::(&arrays[0])?; + let values = as_float64_array(list_array.values())?; + let offsets = list_array.value_offsets(); + + let mut builder = Float64Array::builder(list_array.len()); + + for row in 0..list_array.len() { + if list_array.is_null(row) { + builder.append_null(); + continue; + } + + let start = offsets[row].as_usize(); + let end = offsets[row + 1].as_usize(); + + let mut prod = 1.0_f64; + let mut any_valid = false; + for i in start..end { + if values.is_valid(i) { + prod *= values.value(i); + any_valid = true; + } + } + + if any_valid { + builder.append_value(prod); + } else { + builder.append_null(); + } + } + + Ok(Arc::new(builder.finish())) +} diff --git a/datafusion/functions-nested/src/lib.rs b/datafusion/functions-nested/src/lib.rs index 4ac7dac9a1b4c..359aa6c8de39c 100644 --- a/datafusion/functions-nested/src/lib.rs +++ b/datafusion/functions-nested/src/lib.rs @@ -46,6 +46,7 @@ pub mod array_compact; pub mod array_filter; pub mod array_has; pub mod array_normalize; +pub mod array_product; pub mod array_scale; pub mod array_subtract; pub mod array_transform; @@ -99,6 +100,7 @@ pub mod expr_fn { pub use super::array_has::array_has_all; pub use super::array_has::array_has_any; pub use super::array_normalize::array_normalize; + pub use super::array_product::array_product; pub use super::array_scale::array_scale; pub use super::array_subtract::array_subtract; pub use super::array_transform::array_transform; @@ -177,6 +179,7 @@ pub fn all_default_nested_functions() -> Vec> { length::array_length_udf(), array_normalize::array_normalize_udf(), array_add::array_add_udf(), + array_product::array_product_udf(), array_scale::array_scale_udf(), array_subtract::array_subtract_udf(), cosine_distance::cosine_distance_udf(), diff --git a/datafusion/sqllogictest/test_files/array_product.slt b/datafusion/sqllogictest/test_files/array_product.slt new file mode 100644 index 0000000000000..ba60360d1c1a9 --- /dev/null +++ b/datafusion/sqllogictest/test_files/array_product.slt @@ -0,0 +1,145 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +## array_product + +# Basic product of three floats +query R +select array_product([1.0, 2.0, 3.0]); +---- +6 + +# Negative values: signs multiply +query R +select array_product([-2.0, 3.0]); +---- +-6 + +# Single element returns itself +query R +select array_product([5.0]); +---- +5 + +# Zero element produces zero (no short-circuit; we still multiply) +query R +select array_product([0.0, 3.0, 4.0]); +---- +0 + +# NULL elements inside the list are skipped (SQL aggregate convention) +query R +select array_product([2.0, NULL, 3.0]); +---- +6 + +# All-NULL elements: no data to reduce, returns NULL +query R +select array_product([CAST(NULL AS DOUBLE), CAST(NULL AS DOUBLE)]); +---- +NULL + +# Bare NULL input returns NULL +query R +select array_product(NULL); +---- +NULL + +# Empty array: no data to reduce, returns NULL +query R +select array_product(arrow_cast(make_array(), 'List(Float64)')); +---- +NULL + +# LargeList input +query R +select array_product(arrow_cast([2.0, 3.0, 4.0], 'LargeList(Float64)')); +---- +24 + +# FixedSizeList input (coerced to List) +query R +select array_product(arrow_cast([2.0, 3.0, 4.0], 'FixedSizeList(3, Float64)')); +---- +24 + +# Float32 inner type (coerced to Float64) +query R +select array_product(arrow_cast([2.0, 3.0, 4.0], 'List(Float32)')); +---- +24 + +# Int64 inner type (coerced to Float64) +query R +select array_product(arrow_cast([2, 3, 4], 'List(Int64)')); +---- +24 + +# Integer literals (coerced to Float64) +query R +select array_product([2, 3, 4]); +---- +24 + +# Unsupported non-list input (plan error) +query error array_product does not support type +select array_product(1); + +# No arguments error +query error array_product function requires 1 argument, got 0 +select array_product(); + +# Multi-row query: normal row, NULL row, empty list, all-NULL elements, +# element-NULL skip, single zero +query R +select array_product(column1) from (values + (make_array(2.0, 3.0, 4.0)), + (NULL), + (arrow_cast(make_array(), 'List(Float64)')), + (make_array(CAST(NULL AS DOUBLE), CAST(NULL AS DOUBLE))), + (make_array(CAST(2.0 AS DOUBLE), CAST(NULL AS DOUBLE), CAST(5.0 AS DOUBLE))), + (make_array(0.0, 7.0)) +) as t(column1); +---- +24 +NULL +NULL +NULL +10 +0 + +# Return type is always Float64 (scalar, not List) +query RT +select array_product([2.0, 3.0]), arrow_typeof(array_product([2.0, 3.0])); +---- +6 Float64 + +# list_product alias produces the same result +query R +select list_product([2.0, 3.0, 4.0]); +---- +24 + +# list_product alias multi-row +query R +select list_product(column1) from (values + (make_array(2.0, 3.0)), + (NULL) +) as t(column1); +---- +6 +NULL \ No newline at end of file diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index a3e83409b869c..d7026eec09898 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -3276,6 +3276,7 @@ _Alias of [current_date](#current_date)._ - [array_position](#array_position) - [array_positions](#array_positions) - [array_prepend](#array_prepend) +- [array_product](#array_product) - [array_push_back](#array_push_back) - [array_push_front](#array_push_front) - [array_remove](#array_remove) @@ -3334,6 +3335,7 @@ _Alias of [current_date](#current_date)._ - [list_position](#list_position) - [list_positions](#list_positions) - [list_prepend](#list_prepend) +- [list_product](#list_product) - [list_push_back](#list_push_back) - [list_push_front](#list_push_front) - [list_remove](#list_remove) @@ -4136,6 +4138,33 @@ array_prepend(element, array) - array_push_front - list_push_front +### `array_product` + +Returns the product of the elements in the input numeric array. NULL elements inside the array are skipped (matching SQL aggregate convention). Returns NULL if the input is NULL, every element is NULL, or the array is empty. The result is always returned as `Float64`. + +```sql +array_product(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_product([1.0, 2.0, 3.0]); ++------------------------------------+ +| array_product(List([1.0,2.0,3.0])) | ++------------------------------------+ +| 6.0 | ++------------------------------------+ +``` + +#### Aliases + +- list_product + ### `array_push_back` _Alias of [array_append](#array_append)._ @@ -4959,6 +4988,10 @@ _Alias of [array_positions](#array_positions)._ _Alias of [array_prepend](#array_prepend)._ +### `list_product` + +_Alias of [array_product](#array_product)._ + ### `list_push_back` _Alias of [array_append](#array_append)._