Skip to content

Apache DataFusion SQL Query Engine

fix: Handle potential overflow in internal state for `avg(decimal)` (#22714)

Adam Gutglick0099876a3c0c
diff --git a/datafusion/functions-aggregate-common/src/aggregate/avg_distinct/decimal.rs b/datafusion/functions-aggregate-common/src/aggregate/avg_distinct/decimal.rs
index 0a4c1692ba..0394a8391a 100644
--- a/datafusion/functions-aggregate-common/src/aggregate/avg_distinct/decimal.rs
+++ b/datafusion/functions-aggregate-common/src/aggregate/avg_distinct/decimal.rs
@@ -16,14 +16,14 @@
// under the License.
use arrow::{
- array::{ArrayRef, ArrowNumericType},
- datatypes::{
- Decimal32Type, Decimal64Type, Decimal128Type, Decimal256Type, DecimalType, i256,
- },
+ array::{ArrayRef, ArrowNativeTypeOp, ArrowNumericType},
+ compute::DecimalCast,
+ datatypes::{ArrowNativeType, DecimalType},
};
-use datafusion_common::{Result, ScalarValue};
+use datafusion_common::{Result, ScalarValue, exec_datafusion_err, exec_err};
use datafusion_expr_common::accumulator::Accumulator;
use std::fmt::Debug;
+use std::marker::PhantomData;
use std::mem::size_of_val;
use crate::aggregate::sum_distinct::DistinctSumAccumulator;
@@ -31,33 +31,46 @@ use crate::utils::DecimalAverager;
/// Generic implementation of `AVG DISTINCT` for Decimal types.
/// Handles both all Arrow decimal types (32, 64, 128 and 256 bits).
+///
+/// The distinct values are stored in the input type `I`; only the intermediate
+/// sum is computed in the (never narrower) sum type `S` so it cannot overflow
+/// `I`'s native type.
#[derive(Debug)]
-pub struct DecimalDistinctAvgAccumulator<T: DecimalType + Debug> {
- sum_accumulator: DistinctSumAccumulator<T>,
+pub struct DecimalDistinctAvgAccumulator<
+ I: DecimalType + Debug,
+ S: DecimalType + Debug = I,
+> {
+ sum_accumulator: DistinctSumAccumulator<I>,
sum_scale: i8,
target_precision: u8,
target_scale: i8,
+ _sum_type: PhantomData<S>,
}
-impl<T: DecimalType + Debug> DecimalDistinctAvgAccumulator<T> {
+impl<I: DecimalType + Debug, S: DecimalType + Debug> DecimalDistinctAvgAccumulator<I, S> {
pub fn with_decimal_params(
sum_scale: i8,
target_precision: u8,
target_scale: i8,
) -> Self {
- let data_type = T::TYPE_CONSTRUCTOR(T::MAX_PRECISION, sum_scale);
+ let data_type = I::TYPE_CONSTRUCTOR(I::MAX_PRECISION, sum_scale);
Self {
sum_accumulator: DistinctSumAccumulator::new(&data_type),
sum_scale,
target_precision,
target_scale,
+ _sum_type: PhantomData,
}
}
}
-impl<T: DecimalType + ArrowNumericType + Debug> Accumulator
- for DecimalDistinctAvgAccumulator<T>
+impl<I, S> Accumulator for DecimalDistinctAvgAccumulator<I, S>
+where
+ I: DecimalType + ArrowNumericType + Debug,
+ S: DecimalType + ArrowNumericType + Debug,
+ I::Native: Into<S::Native> + DecimalCast,
+ S::Native: DecimalCast,
{
fn state(&mut self) -> Result<Vec<ScalarValue>> {
self.sum_accumulator.state()
@@ -72,78 +85,43 @@ impl<T: DecimalType + ArrowNumericType + Debug> Accumulator
}
fn evaluate(&mut self) -> Result<ScalarValue> {
- if self.sum_accumulator.distinct_count() == 0 {
- return ScalarValue::new_primitive::<T>(
- None,
- &T::TYPE_CONSTRUCTOR(self.target_precision, self.target_scale),
- );
+ let out_type = I::TYPE_CONSTRUCTOR(self.target_precision, self.target_scale);
+ let count = self.sum_accumulator.distinct_count();
+ if count == 0 {
+ return ScalarValue::new_primitive::<I>(None, &out_type);
}
- let sum_scalar = self.sum_accumulator.evaluate()?;
-
- match sum_scalar {
- ScalarValue::Decimal32(Some(sum), _, _) => {
- let decimal_averager = DecimalAverager::<Decimal32Type>::try_new(
- self.sum_scale,
- self.target_precision,
- self.target_scale,
- )?;
- let avg = decimal_averager
- .avg(sum, self.sum_accumulator.distinct_count() as i32)?;
- Ok(ScalarValue::Decimal32(
- Some(avg),
- self.target_precision,
- self.target_scale,
- ))
- }
- ScalarValue::Decimal64(Some(sum), _, _) => {
- let decimal_averager = DecimalAverager::<Decimal64Type>::try_new(
- self.sum_scale,
- self.target_precision,
- self.target_scale,
- )?;
- let avg = decimal_averager
- .avg(sum, self.sum_accumulator.distinct_count() as i64)?;
- Ok(ScalarValue::Decimal64(
- Some(avg),
- self.target_precision,
- self.target_scale,
- ))
- }
- ScalarValue::Decimal128(Some(sum), _, _) => {
- let decimal_averager = DecimalAverager::<Decimal128Type>::try_new(
- self.sum_scale,
- self.target_precision,
- self.target_scale,
- )?;
- let avg = decimal_averager
- .avg(sum, self.sum_accumulator.distinct_count() as i128)?;
- Ok(ScalarValue::Decimal128(
- Some(avg),
- self.target_precision,
- self.target_scale,
- ))
- }
- ScalarValue::Decimal256(Some(sum), _, _) => {
- let decimal_averager = DecimalAverager::<Decimal256Type>::try_new(
- self.sum_scale,
- self.target_precision,
- self.target_scale,
- )?;
- // `distinct_count` returns `u64`, but `avg` expects `i256`
- // first convert `u64` to `i128`, then convert `i128` to `i256` to avoid overflow
- let distinct_cnt: i128 = self.sum_accumulator.distinct_count() as i128;
- let count: i256 = i256::from_i128(distinct_cnt);
- let avg = decimal_averager.avg(sum, count)?;
- Ok(ScalarValue::Decimal256(
- Some(avg),
- self.target_precision,
- self.target_scale,
- ))
- }
-
- _ => unreachable!("Unsupported decimal type: {:?}", sum_scalar),
+ // Sum the distinct input values in the wider `S` so the total cannot
+ // overflow the input's native width (mirrors the non-distinct path).
+ let mut sum = S::Native::usize_as(0);
+ for value in self.sum_accumulator.distinct_values() {
+ sum = sum.add_wrapping(value.into());
}
+
+ let Some(count) = S::Native::from_usize(count) else {
+ return exec_err!(
+ "Arithmetic overflow in avg: the distinct count {count} cannot \
+ be represented in the sum type"
+ );
+ };
+
+ let averager = DecimalAverager::<S>::try_new(
+ self.sum_scale,
+ self.target_precision,
+ self.target_scale,
+ )?;
+ // Narrowing the average back to the (never wider) output type cannot
+ // fail in practice: `DecimalAverager::avg` validates the average
+ // against the output precision, whose bound fits the output's native
+ // type by construction
+ let avg =
+ I::Native::from_decimal(averager.avg(sum, count)?).ok_or_else(|| {
+ exec_datafusion_err!(
+ "Arithmetic overflow in avg: the computed average does not fit \
+ the output type"
+ )
+ })?;
+ ScalarValue::new_primitive::<I>(Some(avg), &out_type)
}
fn size(&self) -> usize {
@@ -160,6 +138,9 @@ mod tests {
use arrow::array::{
Decimal32Array, Decimal64Array, Decimal128Array, Decimal256Array,
};
+ use arrow::datatypes::{
+ Decimal32Type, Decimal64Type, Decimal128Type, Decimal256Type, i256,
+ };
use std::sync::Arc;
#[test]
@@ -279,4 +260,94 @@ mod tests {
Ok(())
}
+
+ // The overflow regression tests below use odd-count ranges symmetric
+ // around a center value, so the exact sum is `count * center` and the
+ // average is exactly `center`.
+
+ #[test]
+ fn test_decimal32_distinct_avg_widens_to_decimal64() -> Result<()> {
+ // 42951 distinct values centered on 50000:
+ // sum = 42951 * 50000 = 2,147,550,000 > i32::MAX
+ let array = Decimal32Array::from_iter_values(28525..=71475)
+ .with_precision_and_scale(5, 0)?;
+
+ let mut accumulator = DecimalDistinctAvgAccumulator::<
+ Decimal32Type,
+ Decimal64Type,
+ >::with_decimal_params(0, 9, 4);
+ accumulator.update_batch(&[Arc::new(array)])?;
+
+ assert_eq!(
+ accumulator.evaluate()?,
+ ScalarValue::Decimal32(Some(500_000_000), 9, 4)
+ );
+
+ Ok(())
+ }
+
+ #[test]
+ fn test_decimal32_distinct_avg_widens_to_decimal128() -> Result<()> {
+ // 21477 distinct values centered on 99999:
+ // sum = 21477 * 99999 = 2,147,678,523 > i32::MAX
+ let array = Decimal32Array::from_iter_values(89261..=110737)
+ .with_precision_and_scale(9, 0)?;
+
+ let mut accumulator = DecimalDistinctAvgAccumulator::<
+ Decimal32Type,
+ Decimal128Type,
+ >::with_decimal_params(0, 9, 4);
+ accumulator.update_batch(&[Arc::new(array)])?;
+
+ assert_eq!(
+ accumulator.evaluate()?,
+ ScalarValue::Decimal32(Some(999_990_000), 9, 4)
+ );
+
+ Ok(())
+ }
+
+ #[test]
+ fn test_decimal64_distinct_avg_widens_to_decimal128() -> Result<()> {
+ // 92235 distinct values centered on 10^14 - 1:
+ // sum = 92235 * (10^14 - 1) ~= 9.22e18 > i64::MAX
+ let center: i64 = 100_000_000_000_000 - 1;
+ let array = Decimal64Array::from_iter_values(center - 46117..=center + 46117)
+ .with_precision_and_scale(18, 0)?;
+
+ let mut accumulator = DecimalDistinctAvgAccumulator::<
+ Decimal64Type,
+ Decimal128Type,
+ >::with_decimal_params(0, 18, 4);
+ accumulator.update_batch(&[Arc::new(array)])?;
+
+ assert_eq!(
+ accumulator.evaluate()?,
+ ScalarValue::Decimal64(Some(999_999_999_999_990_000), 18, 4)
+ );
+
+ Ok(())
+ }
+
+ #[test]
+ fn test_decimal128_distinct_avg_widens_to_decimal256() -> Result<()> {
+ // 21477 distinct values ending at 10^34 - 1, centered on 10^34 - 10739:
+ // sum = 21477 * (10^34 - 10739) ~= 2.15e38 > i128::MAX
+ let center: i128 = 10_i128.pow(34) - 10739;
+ let array = Decimal128Array::from_iter_values(center - 10738..=center + 10738)
+ .with_precision_and_scale(34, 0)?;
+
+ let mut accumulator = DecimalDistinctAvgAccumulator::<
+ Decimal128Type,
+ Decimal256Type,
+ >::with_decimal_params(0, 38, 4);
+ accumulator.update_batch(&[Arc::new(array)])?;
+
+ assert_eq!(
+ accumulator.evaluate()?,
+ ScalarValue::Decimal128(Some(center * 10_000), 38, 4)
+ );
+
+ Ok(())
+ }
}
diff --git a/datafusion/functions-aggregate-common/src/aggregate/sum_distinct/numeric.rs b/datafusion/functions-aggregate-common/src/aggregate/sum_distinct/numeric.rs
index e5a23597c4..2119c06b48 100644
--- a/datafusion/functions-aggregate-common/src/aggregate/sum_distinct/numeric.rs
+++ b/datafusion/functions-aggregate-common/src/aggregate/sum_distinct/numeric.rs
@@ -50,6 +50,13 @@ impl<T: ArrowPrimitiveType> DistinctSumAccumulator<T> {
pub fn distinct_count(&self) -> usize {
self.values.values.len()
}
+
+ /// Iterates the distinct values collected so far. `AVG(DISTINCT)` re-sums
+ /// them in a wider type instead of using [`Self::evaluate`]'s input-typed
+ /// sum.
+ pub(crate) fn distinct_values(&self) -> impl Iterator<Item = T::Native> + '_ {
+ self.values.values.iter().map(|v| v.0)
+ }
}
impl<T: ArrowPrimitiveType + Debug> Accumulator for DistinctSumAccumulator<T> {
diff --git a/datafusion/functions-aggregate/src/average.rs b/datafusion/functions-aggregate/src/average.rs
index 278a861de2..f1159f22b2 100644
--- a/datafusion/functions-aggregate/src/average.rs
+++ b/datafusion/functions-aggregate/src/average.rs
@@ -22,17 +22,19 @@ use arrow::array::{
BooleanArray, PrimitiveArray, PrimitiveBuilder, UInt64Array,
};
-use arrow::compute::sum;
+use arrow::compute::{DecimalCast, sum};
use arrow::datatypes::{
ArrowNativeType, DECIMAL32_MAX_PRECISION, DECIMAL32_MAX_SCALE,
DECIMAL64_MAX_PRECISION, DECIMAL64_MAX_SCALE, DECIMAL128_MAX_PRECISION,
DECIMAL128_MAX_SCALE, DECIMAL256_MAX_PRECISION, DECIMAL256_MAX_SCALE, DataType,
Decimal32Type, Decimal64Type, Decimal128Type, Decimal256Type, DecimalType,
DurationMicrosecondType, DurationMillisecondType, DurationNanosecondType,
- DurationSecondType, Field, FieldRef, Float64Type, TimeUnit, UInt64Type, i256,
+ DurationSecondType, Field, FieldRef, Float64Type, TimeUnit, UInt64Type,
};
use datafusion_common::types::{NativeType, logical_float64};
-use datafusion_common::{Result, ScalarValue, exec_err, not_impl_err};
+use datafusion_common::{
+ Result, ScalarValue, exec_datafusion_err, exec_err, internal_err, not_impl_err,
+};
use datafusion_expr::function::{AccumulatorArgs, StateFieldsArgs};
use datafusion_expr::utils::format_state_name;
use datafusion_expr::{
@@ -51,6 +53,7 @@ use datafusion_functions_aggregate_common::utils::DecimalAverager;
use datafusion_macros::user_doc;
use log::debug;
use std::fmt::Debug;
+use std::marker::PhantomData;
use std::mem::{size_of, size_of_val};
use std::sync::Arc;
@@ -125,6 +128,85 @@ impl Default for Avg {
}
}
+/// Digits reserved above the input precision for `avg`'s intermediate sum: 4 for
+/// the scale-up [`DecimalAverager`] applies before dividing (`Avg::return_type`
+/// adds 4 to the scale), 9 for the row count.
+///
+/// The 9 is a row budget. A sum of `n` rows of `Decimal(p, _)` is bounded by
+/// `n * 10^p`, so a sum type with `p + 4 + 9` digits holds `10^9` rows. The sum
+/// wraps on overflow, like the `sum` aggregate; the budget is what puts that out
+/// of reach. `Decimal256` input near max precision is the exception: no wider
+/// type exists, so its sum keeps only whatever headroom `Decimal256(76, _)` has
+/// left, as before this budget was introduced.
+const AVG_SUM_HEADROOM_DIGITS: u8 = 13;
+
+/// The narrowest decimal that can accumulate `avg`'s sum over `data_type`, never
+/// narrower than `data_type` itself. Other types accumulate as themselves.
+fn avg_sum_data_type(data_type: &DataType) -> DataType {
+ let (precision, scale, input_max_precision) = match data_type {
+ DataType::Decimal32(precision, scale) => {
+ (*precision, *scale, DECIMAL32_MAX_PRECISION)
+ }
+ DataType::Decimal64(precision, scale) => {
+ (*precision, *scale, DECIMAL64_MAX_PRECISION)
+ }
+ DataType::Decimal128(precision, scale) => {
+ (*precision, *scale, DECIMAL128_MAX_PRECISION)
+ }
+ DataType::Decimal256(precision, scale) => {
+ (*precision, *scale, DECIMAL256_MAX_PRECISION)
+ }
+ data_type => return data_type.clone(),
+ };
+
+ let required = precision
+ .saturating_add(AVG_SUM_HEADROOM_DIGITS)
+ .max(input_max_precision);
+
+ // `required` always exceeds `DECIMAL32_MAX_PRECISION`, so a `Decimal32` sum is
+ // never wide enough, not even for `Decimal32` input
+ if required <= DECIMAL64_MAX_PRECISION {
+ DataType::Decimal64(DECIMAL64_MAX_PRECISION, scale)
+ } else if required <= DECIMAL128_MAX_PRECISION {
+ DataType::Decimal128(DECIMAL128_MAX_PRECISION, scale)
+ } else {
+ DataType::Decimal256(DECIMAL256_MAX_PRECISION, scale)
+ }
+}
+
+/// Instantiates `$builder::<Input, Sum>` for every decimal pair that
+/// [`avg_sum_data_type`] can produce.
+macro_rules! decimal_avg_dispatch {
+ ($input:expr, $sum:expr, $builder:ident, $($arg:expr),*) => {
+ match ($input, $sum) {
+ (DataType::Decimal32(..), DataType::Decimal64(..)) => {
+ $builder::<Decimal32Type, Decimal64Type>($($arg),*)
+ }
+ (DataType::Decimal32(..), DataType::Decimal128(..)) => {
+ $builder::<Decimal32Type, Decimal128Type>($($arg),*)
+ }
+ (DataType::Decimal64(..), DataType::Decimal64(..)) => {
+ $builder::<Decimal64Type, Decimal64Type>($($arg),*)
+ }
+ (DataType::Decimal64(..), DataType::Decimal128(..)) => {
+ $builder::<Decimal64Type, Decimal128Type>($($arg),*)
+ }
+ (DataType::Decimal128(..), DataType::Decimal128(..)) => {
+ $builder::<Decimal128Type, Decimal128Type>($($arg),*)
+ }
+ (DataType::Decimal128(..), DataType::Decimal256(..)) => {
+ $builder::<Decimal128Type, Decimal256Type>($($arg),*)
+ }
+ (DataType::Decimal256(..), DataType::Decimal256(..)) => {
+ $builder::<Decimal256Type, Decimal256Type>($($arg),*)
+ }
+ (input, sum) => {
+ internal_err!("avg cannot accumulate {input} as {sum}")
+ }
+ }
+ };
+}
+
impl AggregateUDFImpl for Avg {
fn name(&self) -> &str {
"avg"
@@ -179,39 +261,19 @@ impl AggregateUDFImpl for Avg {
// Numeric types are converted to Float64 via `coerce_avg_type` during logical plan creation
(Float64, _) => Ok(Box::new(Float64DistinctAvgAccumulator::default())),
- (
- Decimal32(_, scale),
- Decimal32(target_precision, target_scale),
- ) => Ok(Box::new(DecimalDistinctAvgAccumulator::<Decimal32Type>::with_decimal_params(
- *scale,
- *target_precision,
- *target_scale,
- ))),
- (
- Decimal64(_, scale),
- Decimal64(target_precision, target_scale),
- ) => Ok(Box::new(DecimalDistinctAvgAccumulator::<Decimal64Type>::with_decimal_params(
- *scale,
- *target_precision,
- *target_scale,
- ))),
- (
- Decimal128(_, scale),
- Decimal128(target_precision, target_scale),
- ) => Ok(Box::new(DecimalDistinctAvgAccumulator::<Decimal128Type>::with_decimal_params(
- *scale,
- *target_precision,
- *target_scale,
- ))),
-
- (
- Decimal256(_, scale),
- Decimal256(target_precision, target_scale),
- ) => Ok(Box::new(DecimalDistinctAvgAccumulator::<Decimal256Type>::with_decimal_params(
- *scale,
- *target_precision,
- *target_scale,
- ))),
+ (Decimal32(..), Decimal32(..))
+ | (Decimal64(..), Decimal64(..))
+ | (Decimal128(..), Decimal128(..))
+ | (Decimal256(..), Decimal256(..)) => {
+ let sum_data_type = avg_sum_data_type(data_type);
+ decimal_avg_dispatch!(
+ data_type,
+ &sum_data_type,
+ decimal_distinct_avg_accumulator,
+ &sum_data_type,
+ acc_args.return_type()
+ )
+ }
(dt, return_type) => exec_err!(
"AVG(DISTINCT) for ({} --> {}) not supported",
@@ -222,51 +284,19 @@ impl AggregateUDFImpl for Avg {
} else {
match (&data_type, acc_args.return_type()) {
(Float64, Float64) => Ok(Box::<AvgAccumulator>::default()),
- (
- Decimal32(sum_precision, sum_scale),
- Decimal32(target_precision, target_scale),
- ) => Ok(Box::new(DecimalAvgAccumulator::<Decimal32Type> {
- sum: None,
- count: 0,
- sum_scale: *sum_scale,
- sum_precision: *sum_precision,
- target_precision: *target_precision,
- target_scale: *target_scale,
- })),
- (
- Decimal64(sum_precision, sum_scale),
- Decimal64(target_precision, target_scale),
- ) => Ok(Box::new(DecimalAvgAccumulator::<Decimal64Type> {
- sum: None,
- count: 0,
- sum_scale: *sum_scale,
- sum_precision: *sum_precision,
- target_precision: *target_precision,
- target_scale: *target_scale,
- })),
- (
- Decimal128(sum_precision, sum_scale),
- Decimal128(target_precision, target_scale),
- ) => Ok(Box::new(DecimalAvgAccumulator::<Decimal128Type> {
- sum: None,
- count: 0,
- sum_scale: *sum_scale,
- sum_precision: *sum_precision,
- target_precision: *target_precision,
- target_scale: *target_scale,
- })),
-
- (
- Decimal256(sum_precision, sum_scale),
- Decimal256(target_precision, target_scale),
- ) => Ok(Box::new(DecimalAvgAccumulator::<Decimal256Type> {
- sum: None,
- count: 0,
- sum_scale: *sum_scale,
- sum_precision: *sum_precision,
- target_precision: *target_precision,
- target_scale: *target_scale,
- })),
+ (Decimal32(..), Decimal32(..))
+ | (Decimal64(..), Decimal64(..))
+ | (Decimal128(..), Decimal128(..))
+ | (Decimal256(..), Decimal256(..)) => {
+ let sum_data_type = avg_sum_data_type(data_type);
+ decimal_avg_dispatch!(
+ data_type,
+ &sum_data_type,
+ decimal_avg_accumulator,
+ sum_data_type.clone(),
+ acc_args.return_type().clone()
+ )
+ }
(Duration(time_unit), Duration(result_unit)) => {
Ok(Box::new(DurationAvgAccumulator {
@@ -314,17 +344,14 @@ impl AggregateUDFImpl for Avg {
.into(),
])
} else {
+ let sum_data_type = avg_sum_data_type(args.input_fields[0].data_type());
Ok(vec![
Field::new(
format_state_name(args.name, "count"),
DataType::UInt64,
true,
),
- Field::new(
- format_state_name(args.name, "sum"),
- args.input_fields[0].data_type().clone(),
- true,
- ),
+ Field::new(format_state_name(args.name, "sum"), sum_data_type, true),
]
.into_iter()
.map(Arc::new)
@@ -361,83 +388,18 @@ impl AggregateUDFImpl for Avg {
|sum: f64, count: u64| Ok(sum / count as f64),
)))
}
- (
- Decimal32(_sum_precision, sum_scale),
- Decimal32(target_precision, target_scale),
- ) => {
- let decimal_averager = DecimalAverager::<Decimal32Type>::try_new(
- *sum_scale,
- *target_precision,
- *target_scale,
- )?;
-
- let avg_fn =
- move |sum: i32, count: u64| decimal_averager.avg(sum, count as i32);
-
- Ok(Box::new(AvgGroupsAccumulator::<Decimal32Type, _>::new(
+ (Decimal32(..), Decimal32(..))
+ | (Decimal64(..), Decimal64(..))
+ | (Decimal128(..), Decimal128(..))
+ | (Decimal256(..), Decimal256(..)) => {
+ let sum_data_type = avg_sum_data_type(data_type);
+ decimal_avg_dispatch!(
data_type,
- args.return_field.data_type(),
- avg_fn,
- )))
- }
- (
- Decimal64(_sum_precision, sum_scale),
- Decimal64(target_precision, target_scale),
- ) => {
- let decimal_averager = DecimalAverager::<Decimal64Type>::try_new(
- *sum_scale,
- *target_precision,
- *target_scale,
- )?;
-
- let avg_fn =
- move |sum: i64, count: u64| decimal_averager.avg(sum, count as i64);
-
- Ok(Box::new(AvgGroupsAccumulator::<Decimal64Type, _>::new(
- data_type,
- args.return_field.data_type(),
- avg_fn,
- )))
- }
- (
- Decimal128(_sum_precision, sum_scale),
- Decimal128(target_precision, target_scale),
- ) => {
- let decimal_averager = DecimalAverager::<Decimal128Type>::try_new(
- *sum_scale,
- *target_precision,
- *target_scale,
- )?;
-
- let avg_fn =
- move |sum: i128, count: u64| decimal_averager.avg(sum, count as i128);
-
- Ok(Box::new(AvgGroupsAccumulator::<Decimal128Type, _>::new(
- data_type,
- args.return_field.data_type(),
- avg_fn,
- )))
- }
-
- (
- Decimal256(_sum_precision, sum_scale),
- Decimal256(target_precision, target_scale),
- ) => {
- let decimal_averager = DecimalAverager::<Decimal256Type>::try_new(
- *sum_scale,
- *target_precision,
- *target_scale,
- )?;
-
- let avg_fn = move |sum: i256, count: u64| {
- decimal_averager.avg(sum, i256::from_usize(count as usize).unwrap())
- };
-
- Ok(Box::new(AvgGroupsAccumulator::<Decimal256Type, _>::new(
- data_type,
- args.return_field.data_type(),
- avg_fn,
- )))
+ &sum_data_type,
+ decimal_avg_groups_accumulator,
+ &sum_data_type,
+ args.return_field.data_type()
+ )
}
(Duration(time_unit), Duration(_result_unit)) => {
@@ -500,6 +462,117 @@ impl AggregateUDFImpl for Avg {
}
}
+/// The precision and scale of a decimal `DataType`
+fn decimal_parts(data_type: &DataType) -> Result<(u8, i8)> {
+ match data_type {
+ DataType::Decimal32(precision, scale)
+ | DataType::Decimal64(precision, scale)
+ | DataType::Decimal128(precision, scale)
+ | DataType::Decimal256(precision, scale) => Ok((*precision, *scale)),
+ data_type => internal_err!("expected a decimal type, got {data_type}"),
+ }
+}
+
+fn decimal_avg_fn<I, S>(
+ sum_scale: i8,
+ target_precision: u8,
+ target_scale: i8,
+) -> Result<impl Fn(S::Native, u64) -> Result<I::Native> + Send + Sync + 'static>
+where
+ I: DecimalType,
+ S: DecimalType,
+ I::Native: DecimalCast,
+ S::Native: DecimalCast,
+{
+ let decimal_averager =
+ DecimalAverager::<S>::try_new(sum_scale, target_precision, target_scale)?;
+
+ Ok(move |sum, count: u64| {
+ let Some(count) = usize::try_from(count).ok().and_then(S::Native::from_usize)
+ else {
+ return exec_err!(
+ "Arithmetic overflow in avg: the row count {count} cannot be \
+ represented in the sum type"
+ );
+ };
+
+ // Narrowing the average back to the (never wider) output type cannot
+ // fail in practice: `DecimalAverager::avg` validates the average
+ // against the output precision, whose bound fits the output's native
+ // type by construction
+ I::Native::from_decimal(decimal_averager.avg(sum, count)?).ok_or_else(|| {
+ exec_datafusion_err!(
+ "Arithmetic overflow in avg: the computed average does not fit \
+ the output type"
+ )
+ })
+ })
+}
+
+fn decimal_avg_accumulator<I, S>(
+ sum_data_type: DataType,
+ return_data_type: DataType,
+) -> Result<Box<dyn Accumulator>>
+where
+ I: DecimalType + ArrowNumericType + Debug + Send + Sync,
+ S: DecimalType + ArrowNumericType + Debug + Send + Sync,
+ I::Native: Into<S::Native> + DecimalCast,
+ S::Native: DecimalCast,
+{
+ let (_, sum_scale) = decimal_parts(&sum_data_type)?;
+ let (target_precision, target_scale) = decimal_parts(&return_data_type)?;
+ let avg_fn = decimal_avg_fn::<I, S>(sum_scale, target_precision, target_scale)?;
+
+ Ok(Box::new(DecimalAvgAccumulator::<I, S, _>::new(
+ sum_data_type,
+ return_data_type,
+ avg_fn,
+ )))
+}
+
+fn decimal_distinct_avg_accumulator<I, S>(
+ sum_data_type: &DataType,
+ return_data_type: &DataType,
+) -> Result<Box<dyn Accumulator>>
+where
+ I: DecimalType + ArrowNumericType + Debug + Send + Sync,
+ S: DecimalType + ArrowNumericType + Debug + Send + Sync,
+ I::Native: Into<S::Native> + DecimalCast,
+ S::Native: DecimalCast,
+{
+ let (_, sum_scale) = decimal_parts(sum_data_type)?;
+ let (target_precision, target_scale) = decimal_parts(return_data_type)?;
+
+ Ok(Box::new(
+ DecimalDistinctAvgAccumulator::<I, S>::with_decimal_params(
+ sum_scale,
+ target_precision,
+ target_scale,
+ ),
+ ))
+}
+
+fn decimal_avg_groups_accumulator<I, S>(
+ sum_data_type: &DataType,
+ return_data_type: &DataType,
+) -> Result<Box<dyn GroupsAccumulator>>
+where
+ I: DecimalType + ArrowNumericType + Debug + Send + Sync,
+ S: DecimalType + ArrowNumericType + Debug + Send + Sync,
+ I::Native: Into<S::Native> + DecimalCast,
+ S::Native: DecimalCast,
+{
+ let (_, sum_scale) = decimal_parts(sum_data_type)?;
+ let (target_precision, target_scale) = decimal_parts(return_data_type)?;
+ let avg_fn = decimal_avg_fn::<I, S>(sum_scale, target_precision, target_scale)?;
+
+ Ok(Box::new(AvgGroupsAccumulator::<I, _, S>::new(
+ sum_data_type,
+ return_data_type,
+ avg_fn,
+ )))
+}
+
/// An accumulator to compute the average
#[derive(Debug, Default)]
pub struct AvgAccumulator {
@@ -567,24 +640,104 @@ impl Accumulator for AvgAccumulator {
}
}
-/// An accumulator to compute the average for decimals
-#[derive(Debug)]
-struct DecimalAvgAccumulator<T: DecimalType + ArrowNumericType + Debug> {
- sum: Option<T::Native>,
+/// An accumulator to compute the average for decimals.
+///
+/// `I` is the input (and output) decimal type. `S` is the type used to accumulate
+/// the sum, chosen by [`avg_sum_data_type`] so the running total does not overflow.
+struct DecimalAvgAccumulator<I, S, F>
+where
+ I: DecimalType + ArrowNumericType + Debug,
+ S: DecimalType + ArrowNumericType + Debug,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native>,
+{
+ sum: Option<S::Native>,
count: u64,
- sum_scale: i8,
- sum_precision: u8,
- target_precision: u8,
- target_scale: i8,
+ sum_data_type: DataType,
+ return_data_type: DataType,
+ avg_fn: F,
+ _phantom: PhantomData<I>,
}
-impl<T: DecimalType + ArrowNumericType + Debug> Accumulator for DecimalAvgAccumulator<T> {
+impl<I, S, F> Debug for DecimalAvgAccumulator<I, S, F>
+where
+ I: DecimalType + ArrowNumericType + Debug,
+ S: DecimalType + ArrowNumericType + Debug,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native>,
+{
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("DecimalAvgAccumulator")
+ .field("sum", &self.sum)
+ .field("count", &self.count)
+ .field("sum_data_type", &self.sum_data_type)
+ .field("return_data_type", &self.return_data_type)
+ .finish_non_exhaustive()
+ }
+}
+
+impl<I, S, F> DecimalAvgAccumulator<I, S, F>
+where
+ I: DecimalType + ArrowNumericType + Debug,
+ S: DecimalType + ArrowNumericType + Debug,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native>,
+{
+ fn new(sum_data_type: DataType, return_data_type: DataType, avg_fn: F) -> Self {
+ Self {
+ sum: None,
+ count: 0,
+ sum_data_type,
+ return_data_type,
+ avg_fn,
+ _phantom: PhantomData,
+ }
+ }
+}
+
+/// Sums `values` into the wider `S`.
+///
+/// Wraps on overflow, matching the `sum` aggregate and [`arrow::compute::sum`].
+/// [`avg_sum_data_type`] gives `S` enough headroom that this is unreachable for
+/// any realistic row count.
+fn decimal_sum_as<I, S>(values: &PrimitiveArray<I>) -> Option<S::Native>
+where
+ I: DecimalType + ArrowNumericType,
+ S: DecimalType + ArrowNumericType,
+ I::Native: Into<S::Native>,
+{
+ // Matches `arrow::compute::sum`: an empty or all-null input has no sum
+ if values.null_count() == values.len() {
+ return None;
+ }
+
+ let mut sum = S::Native::default();
+ if values.null_count() == 0 {
+ for value in values.values() {
+ sum = sum.add_wrapping((*value).into());
+ }
+ } else {
+ for value in values.iter().flatten() {
+ sum = sum.add_wrapping(value.into());
+ }
+ }
+
+ Some(sum)
+}
+
+impl<I, S, F> Accumulator for DecimalAvgAccumulator<I, S, F>
+where
+ I: DecimalType + ArrowNumericType + Debug,
+ S: DecimalType + ArrowNumericType + Debug,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native> + Send + Sync + 'static,
+{
fn update_batch(&mut self, values: &[ArrayRef]) -> Result<()> {
- let values = values[0].as_primitive::<T>();
+ let values = values[0].as_primitive::<I>();
self.count += (values.len() - values.null_count()) as u64;
- if let Some(x) = sum(values) {
- let v = self.sum.get_or_insert_with(T::Native::default);
+ if let Some(x) = decimal_sum_as::<I, S>(values) {
+ let v = self.sum.unwrap_or_default();
self.sum = Some(v.add_wrapping(x));
}
Ok(())
@@ -597,22 +750,10 @@ impl<T: DecimalType + ArrowNumericType + Debug> Accumulator for DecimalAvgAccumu
let v = if self.count == 0 {
None
} else {
- self.sum
- .map(|v| {
- DecimalAverager::<T>::try_new(
- self.sum_scale,
- self.target_precision,
- self.target_scale,
- )?
- .avg(v, T::Native::from_usize(self.count as usize).unwrap())
- })
- .transpose()?
+ self.sum.map(|v| (self.avg_fn)(v, self.count)).transpose()?
};
- ScalarValue::new_primitive::<T>(
- v,
- &T::TYPE_CONSTRUCTOR(self.target_precision, self.target_scale),
- )
+ ScalarValue::new_primitive::<I>(v, &self.return_data_type)
}
fn size(&self) -> usize {
@@ -622,10 +763,7 @@ impl<T: DecimalType + ArrowNumericType + Debug> Accumulator for DecimalAvgAccumu
fn state(&mut self) -> Result<Vec<ScalarValue>> {
Ok(vec![
ScalarValue::from(self.count),
- ScalarValue::new_primitive::<T>(
- self.sum,
- &T::TYPE_CONSTRUCTOR(self.sum_precision, self.sum_scale),
- )?,
+ ScalarValue::new_primitive::<S>(self.sum, &self.sum_data_type)?,
])
}
@@ -634,17 +772,18 @@ impl<T: DecimalType + ArrowNumericType + Debug> Accumulator for DecimalAvgAccumu
self.count += sum(states[0].as_primitive::<UInt64Type>()).unwrap_or_default();
// sums are summed
- if let Some(x) = sum(states[1].as_primitive::<T>()) {
- let v = self.sum.get_or_insert_with(T::Native::default);
+ if let Some(x) = sum(states[1].as_primitive::<S>()) {
+ let v = self.sum.unwrap_or_default();
self.sum = Some(v.add_wrapping(x));
}
Ok(())
}
fn retract_batch(&mut self, values: &[ArrayRef]) -> Result<()> {
- let values = values[0].as_primitive::<T>();
+ let values = values[0].as_primitive::<I>();
self.count -= (values.len() - values.null_count()) as u64;
- if let Some(x) = sum(values) {
- self.sum = Some(self.sum.unwrap().sub_wrapping(x));
+ if let Some(x) = decimal_sum_as::<I, S>(values) {
+ let v = self.sum.unwrap_or_default();
+ self.sum = Some(v.sub_wrapping(x));
}
Ok(())
}
@@ -760,16 +899,21 @@ impl Accumulator for DurationAvgAccumulator {
}
}
-/// An accumulator to compute the average of `[PrimitiveArray<T>]`.
+/// An accumulator to compute the average of `[PrimitiveArray<I>]`.
/// Stores values as native types, and does overflow checking
///
/// F: Function that calculates the average value from a sum of
-/// T::Native and a total count
+/// S::Native and a total count
+///
+/// `I` is the input (and output) type. `S` is a possibly wider type used to
+/// accumulate the sum so it does not overflow.
#[derive(Debug)]
-struct AvgGroupsAccumulator<T, F>
+struct AvgGroupsAccumulator<I, F, S = I>
where
- T: ArrowNumericType + Send,
- F: Fn(T::Native, u64) -> Result<T::Native> + Send + 'static,
+ I: ArrowNumericType + Send,
+ S: ArrowNumericType + Send,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native> + Send + 'static,
{
/// The type of the internal sum
sum_data_type: DataType,
@@ -781,24 +925,28 @@ where
counts: Vec<u64>,
/// Sums per group, stored as the native type
- sums: Vec<T::Native>,
+ sums: Vec<S::Native>,
/// Track nulls in the input / filters
null_state: NullState,
/// Function that computes the final average (value / count)
avg_fn: F,
+
+ _phantom: PhantomData<I>,
}
-impl<T, F> AvgGroupsAccumulator<T, F>
+impl<I, F, S> AvgGroupsAccumulator<I, F, S>
where
- T: ArrowNumericType + Send,
- F: Fn(T::Native, u64) -> Result<T::Native> + Send + 'static,
+ I: ArrowNumericType + Send,
+ S: ArrowNumericType + Send,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native> + Send + 'static,
{
pub fn new(sum_data_type: &DataType, return_data_type: &DataType, avg_fn: F) -> Self {
debug!(
"AvgGroupsAccumulator ({}, sum type: {sum_data_type}) --> {return_data_type}",
- std::any::type_name::<T>()
+ std::any::type_name::<I>()
);
Self {
@@ -808,14 +956,17 @@ where
sums: vec![],
null_state: NullState::new(),
avg_fn,
+ _phantom: PhantomData,
}
}
}
-impl<T, F> GroupsAccumulator for AvgGroupsAccumulator<T, F>
+impl<I, F, S> GroupsAccumulator for AvgGroupsAccumulator<I, F, S>
where
- T: ArrowNumericType + Send,
- F: Fn(T::Native, u64) -> Result<T::Native> + Send + 'static,
+ I: ArrowNumericType + Send,
+ S: ArrowNumericType + Send,
+ I::Native: Into<S::Native>,
+ F: Fn(S::Native, u64) -> Result<I::Native> + Send + 'static,
{
fn update_batch(
&mut self,
@@ -825,11 +976,12 @@ where
total_num_groups: usize,
) -> Result<()> {
assert_eq!(values.len(), 1, "single argument to update_batch");
- let values = values[0].as_primitive::<T>();
+ let values = values[0].as_primitive::<I>();
// increment counts, update sums
self.counts.resize(total_num_groups, 0);
- self.sums.resize(total_num_groups, T::default_value());
+ self.sums.resize(total_num_groups, S::default_value());
+
self.null_state.accumulate(
group_indices,
values,
@@ -838,7 +990,7 @@ where
|group_index, new_value| {
// SAFETY: group_index is guaranteed to be in bounds
let sum = unsafe { self.sums.get_unchecked_mut(group_index) };
- *sum = sum.add_wrapping(new_value);
+ *sum = sum.add_wrapping(new_value.into());
self.counts[group_index] += 1;
},
@@ -859,10 +1011,10 @@ where
// don't evaluate averages with null inputs to avoid errors on null values
- let array: PrimitiveArray<T> = if let Some(nulls) = &nulls
+ let array: PrimitiveArray<I> = if let Some(nulls) = &nulls
&& nulls.null_count() > 0
{
- let mut builder = PrimitiveBuilder::<T>::with_capacity(nulls.len())
+ let mut builder = PrimitiveBuilder::<I>::with_capacity(nulls.len())
.with_data_type(self.return_data_type.clone());
let iter = sums.into_iter().zip(counts).zip(nulls.iter());
@@ -875,7 +1027,7 @@ where
}
builder.finish()
} else {
- let averages: Vec<T::Native> = sums
+ let averages: Vec<I::Native> = sums
.into_iter()
.zip(counts)
.map(|(sum, count)| (self.avg_fn)(sum, count))
@@ -895,7 +1047,7 @@ where
let counts = UInt64Array::new(counts.into(), nulls.clone()); // zero copy
let sums = emit_to.take_needed(&mut self.sums);
- let sums = PrimitiveArray::<T>::new(sums.into(), nulls) // zero copy
+ let sums = PrimitiveArray::<S>::new(sums.into(), nulls) // zero copy
.with_data_type(self.sum_data_type.clone());
Ok(vec![
@@ -913,7 +1065,7 @@ where
assert_eq!(values.len(), 2, "two arguments to merge_batch");
// first batch is counts, second is partial sums
let partial_counts = values[0].as_primitive::<UInt64Type>();
- let partial_sums = values[1].as_primitive::<T>();
+ let partial_sums = values[1].as_primitive::<S>();
// update counts with partial counts
self.counts.resize(total_num_groups, 0);
self.null_state.accumulate(
@@ -929,13 +1081,13 @@ where
);
// update sums
- self.sums.resize(total_num_groups, T::default_value());
+ self.sums.resize(total_num_groups, S::default_value());
self.null_state.accumulate(
group_indices,
partial_sums,
None,
total_num_groups,
- |group_index, new_value: <T as ArrowPrimitiveType>::Native| {
+ |group_index, new_value: <S as ArrowPrimitiveType>::Native| {
// SAFETY: group_index is guaranteed to be in bounds
let sum = unsafe { self.sums.get_unchecked_mut(group_index) };
*sum = sum.add_wrapping(new_value);
@@ -950,10 +1102,27 @@ where
values: &[ArrayRef],
opt_filter: Option<&BooleanArray>,
) -> Result<Vec<ArrayRef>> {
- let sums = values[0]
- .as_primitive::<T>()
- .clone()
- .with_data_type(self.sum_data_type.clone());
+ // When the sum type equals the input type (`I == S`: `Float64`,
+ // `Duration`, `Decimal256`, and any decimal whose precision already
+ // leaves [`avg_sum_data_type`] enough headroom) the input is already a
+ // valid sum array and is reused as is; the downcast is by Rust type, so
+ // it succeeds even when precision differs. Otherwise every value is
+ // widened.
+ let sums = match values[0].as_any().downcast_ref::<PrimitiveArray<S>>() {
+ Some(sums) => sums.clone().with_data_type(self.sum_data_type.clone()),
+ None => {
+ let values = values[0].as_primitive::<I>();
+ // Values under null slots are widened too rather than branching per
+ // element; `set_nulls` below masks them out again.
+ let sums: Vec<S::Native> = values
+ .values()
+ .iter()
+ .map(|value| (*value).into())
+ .collect();
+ PrimitiveArray::<S>::new(sums.into(), values.nulls().cloned())
+ .with_data_type(self.sum_data_type.clone())
+ }
+ };
let counts = UInt64Array::from_value(1, sums.len());
let nulls = filtered_null_mask(opt_filter, &sums);
@@ -972,11 +1141,262 @@ where
fn size(&self) -> usize {
// Heap buffers
self.counts.capacity() * size_of::<u64>()
- + self.sums.capacity() * size_of::<T::Native>()
+ + self.sums.capacity() * size_of::<S::Native>()
// Vec struct overhead (ptr, len, cap) for each field
+ size_of::<Vec<u64>>()
- + size_of::<Vec<T::Native>>()
+ + size_of::<Vec<S::Native>>()
// Null tracking buffers
+ self.null_state.size()
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use arrow::array::{
+ Decimal32Array, Decimal64Array, Decimal128Array, Decimal256Array,
+ DurationSecondArray, Float64Array,
+ };
+ use arrow::datatypes::{Schema, i256};
+
+ struct AvgCase {
+ name: &'static str,
+ values: ArrayRef,
+ return_type: DataType,
+ sum_type: DataType,
+ expected: ScalarValue,
+ }
+
+ fn with_avg_args<R>(
+ input_type: &DataType,
+ return_type: &DataType,
+ f: impl FnOnce(AccumulatorArgs) -> R,
+ ) -> R {
+ let schema = Schema::empty();
+ let expr_field = Arc::new(Field::new("a", input_type.clone(), true));
+ let return_field = Arc::new(Field::new("avg", return_type.clone(), true));
+
+ f(AccumulatorArgs {
+ return_field,
+ schema: &schema,
+ expr_fields: &[expr_field],
+ ignore_nulls: false,
+ order_bys: &[],
+ is_distinct: false,
+ name: "avg",
+ is_reversed: false,
+ exprs: &[],
+ })
+ }
+
+ fn avg_groups_accumulator(
+ input_type: &DataType,
+ return_type: &DataType,
+ ) -> Result<Box<dyn GroupsAccumulator>> {
+ with_avg_args(input_type, return_type, |args| {
+ Avg::new().create_groups_accumulator(args)
+ })
+ }
+
+ fn avg_accumulator(
+ input_type: &DataType,
+ return_type: &DataType,
+ ) -> Result<Box<dyn Accumulator>> {
+ with_avg_args(input_type, return_type, |args| Avg::new().accumulator(args))
+ }
+
+ fn avg_state_fields(
+ input_type: &DataType,
+ return_type: &DataType,
+ ) -> Result<Vec<FieldRef>> {
+ let input_field = Arc::new(Field::new("a", input_type.clone(), true));
+ let return_field = Arc::new(Field::new("avg", return_type.clone(), true));
+
+ Avg::new().state_fields(StateFieldsArgs {
+ name: "avg",
+ input_fields: &[input_field],
+ return_field,
+ ordering_fields: &[],
+ is_distinct: false,
+ })
+ }
+
+ fn avg_cases() -> Result<Vec<AvgCase>> {
+ const ROWS: usize = 21_476;
+ const DECIMAL32_VALUE: i32 = 99_999;
+ const DECIMAL64_ROWS: usize = 92_235;
+ const DECIMAL64_VALUE: i64 = 99_999_999_999_999;
+ const DECIMAL128_ROWS: usize = 21_476;
+ const DECIMAL128_VALUE: i128 = 9_999_999_999_999_999_999_999_999_999_999_999;
+
+ Ok(vec![
+ AvgCase {
+ name: "float64",
+ values: Arc::new(Float64Array::from(vec![10.0, 20.0])),
+ return_type: DataType::Float64,
+ sum_type: DataType::Float64,
+ expected: ScalarValue::Float64(Some(15.0)),
+ },
+ AvgCase {
+ name: "decimal32",
+ values: Arc::new(
+ Decimal32Array::from(vec![Some(DECIMAL32_VALUE); ROWS])
+ .with_precision_and_scale(5, 0)?,
+ ),
+ return_type: DataType::Decimal32(9, 4),
+ sum_type: DataType::Decimal64(18, 0),
+ expected: ScalarValue::Decimal32(Some(DECIMAL32_VALUE * 10_000), 9, 4),
+ },
+ AvgCase {
+ name: "decimal64",
+ values: Arc::new(
+ Decimal64Array::from(vec![Some(DECIMAL64_VALUE); DECIMAL64_ROWS])
+ .with_precision_and_scale(14, 0)?,
+ ),
+ return_type: DataType::Decimal64(18, 4),
+ sum_type: DataType::Decimal128(38, 0),
+ expected: ScalarValue::Decimal64(Some(DECIMAL64_VALUE * 10_000), 18, 4),
+ },
+ AvgCase {
+ name: "decimal128",
+ values: Arc::new(
+ Decimal128Array::from(vec![Some(DECIMAL128_VALUE); DECIMAL128_ROWS])
+ .with_precision_and_scale(34, 0)?,
+ ),
+ return_type: DataType::Decimal128(38, 4),
+ sum_type: DataType::Decimal256(76, 0),
+ expected: ScalarValue::Decimal128(Some(DECIMAL128_VALUE * 10_000), 38, 4),
+ },
+ AvgCase {
+ name: "decimal256",
+ values: Arc::new(
+ Decimal256Array::from(vec![i256::from_i128(10), i256::from_i128(20)])
+ .with_precision_and_scale(50, 0)?,
+ ),
+ return_type: DataType::Decimal256(54, 4),
+ sum_type: DataType::Decimal256(76, 0),
+ expected: ScalarValue::Decimal256(Some(i256::from_i128(150_000)), 54, 4),
+ },
+ // A `Decimal128` whose precision leaves room for the sum stays on
+ // `i128` rather than widening to the emulated `i256` arithmetic
+ AvgCase {
+ name: "decimal128_with_headroom",
+ values: Arc::new(
+ Decimal128Array::from(vec![100_000, 200_000])
+ .with_precision_and_scale(20, 4)?,
+ ),
+ return_type: DataType::Decimal128(24, 8),
+ sum_type: DataType::Decimal128(38, 4),
+ expected: ScalarValue::Decimal128(Some(1_500_000_000), 24, 8),
+ },
+ // A `Decimal32` at max precision needs more than `Decimal64` can hold
+ // once `DecimalAverager` scales the sum up, so it accumulates as `i128`
+ AvgCase {
+ name: "decimal32_max_precision",
+ values: Arc::new(
+ Decimal32Array::from(vec![10, 20]).with_precision_and_scale(9, 0)?,
+ ),
+ return_type: DataType::Decimal32(9, 4),
+ sum_type: DataType::Decimal128(38, 0),
+ expected: ScalarValue::Decimal32(Some(150_000), 9, 4),
+ },
+ // One duration unit suffices: all four units instantiate the same
+ // `S = I` generic code
+ AvgCase {
+ name: "duration_second",
+ values: Arc::new(DurationSecondArray::from(vec![10, 20])),
+ return_type: DataType::Duration(TimeUnit::Second),
+ sum_type: DataType::Duration(TimeUnit::Second),
+ expected: ScalarValue::DurationSecond(Some(15)),
+ },
+ ])
+ }
+
+ #[test]
+ fn avg_accumulator_evaluate_and_state_types() -> Result<()> {
+ for case in avg_cases()? {
+ let input_type = case.values.data_type();
+ let state_fields = avg_state_fields(input_type, &case.return_type)?;
+ let mut acc = avg_accumulator(input_type, &case.return_type)?;
+ acc.update_batch(std::slice::from_ref(&case.values))?;
+
+ let state = acc.state()?;
+ assert_eq!(
+ &state[0].data_type(),
+ state_fields[0].data_type(),
+ "{}",
+ case.name
+ );
+ assert_eq!(
+ &state[1].data_type(),
+ state_fields[1].data_type(),
+ "{}",
+ case.name
+ );
+ assert_eq!(acc.evaluate()?, case.expected, "{}", case.name);
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ fn avg_groups_state_types_match_state_fields() -> Result<()> {
+ for case in avg_cases()? {
+ let input_type = case.values.data_type();
+ let state_fields = avg_state_fields(input_type, &case.return_type)?;
+ let acc = avg_groups_accumulator(input_type, &case.return_type)?;
+ let state = acc.convert_to_state(std::slice::from_ref(&case.values), None)?;
+
+ assert_eq!(
+ state_fields[0].data_type(),
+ &DataType::UInt64,
+ "{}",
+ case.name
+ );
+ assert_eq!(state_fields[1].data_type(), &case.sum_type, "{}", case.name);
+ assert_eq!(state[0].data_type(), &DataType::UInt64, "{}", case.name);
+ assert_eq!(state[1].data_type(), &case.sum_type, "{}", case.name);
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ fn avg_groups_convert_to_state_roundtrip() -> Result<()> {
+ for case in avg_cases()? {
+ let input_type = case.values.data_type();
+ let partial = avg_groups_accumulator(input_type, &case.return_type)?;
+ let mut final_acc = avg_groups_accumulator(input_type, &case.return_type)?;
+ let state =
+ partial.convert_to_state(std::slice::from_ref(&case.values), None)?;
+ final_acc.merge_batch(&state, &vec![0; case.values.len()], 1)?;
+
+ let result = final_acc.evaluate(EmitTo::All)?;
+ assert_eq!(result.data_type(), &case.return_type, "{}", case.name);
+ assert_eq!(
+ ScalarValue::try_from_array(result.as_ref(), 0)?,
+ case.expected,
+ "{}",
+ case.name
+ );
+ }
+
+ Ok(())
+ }
+
+ /// The widened sum fits, but the average does not fit the output type once
+ /// `DecimalAverager` rescales it: avg must error rather than silently wrap
+ #[test]
+ fn avg_errors_when_average_exceeds_output_precision() -> Result<()> {
+ let values: ArrayRef = Arc::new(
+ Decimal32Array::from(vec![999_999_999]).with_precision_and_scale(9, 0)?,
+ );
+ let return_type = DataType::Decimal32(9, 4);
+ let mut acc = avg_accumulator(values.data_type(), &return_type)?;
+
+ acc.update_batch(&[values])?;
+ assert!(acc.evaluate().is_err());
+
+ Ok(())
+ }
+}
diff --git a/datafusion/sqllogictest/test_files/decimal.slt b/datafusion/sqllogictest/test_files/decimal.slt
index dd2b294557..4335ec0668 100644
--- a/datafusion/sqllogictest/test_files/decimal.slt
+++ b/datafusion/sqllogictest/test_files/decimal.slt
@@ -1291,3 +1291,52 @@ ORDER BY c1;
statement ok
DROP TABLE decimal_div_mismatch;
+
+# Regression tests: `avg` of a decimal column must accumulate its intermediate
+# sum in a type wide enough not to overflow the input's native type. Each row
+# count below is chosen so that the sum just exceeds the input's native maximum
+# and would silently wrap if accumulated unwidened.
+
+# 21476 * 99999 = 2,147,578,524 > i32::MAX
+query RT
+select avg(d), arrow_typeof(avg(d))
+from (
+ select arrow_cast(99999.0, 'Decimal32(5, 0)') as d
+ from generate_series(1, 21476)
+) t;
+----
+99999 Decimal32(9, 4)
+
+# 92235 * 99999999999999 ~= 9.22e18 > i64::MAX
+query RT
+select avg(d), arrow_typeof(avg(d))
+from (
+ select arrow_cast('99999999999999', 'Decimal64(14, 0)') as d
+ from generate_series(1, 92235)
+) t;
+----
+99999999999999 Decimal64(18, 4)
+
+# 21476 * (10^34 - 1) ~= 2.15e38 > i128::MAX
+query RT
+select avg(d), arrow_typeof(avg(d))
+from (
+ select arrow_cast('9999999999999999999999999999999999', 'Decimal128(34, 0)') as d
+ from generate_series(1, 21476)
+) t;
+----
+9999999999999999999999999999999999 Decimal128(38, 4)
+
+# Regression: `avg(DISTINCT ...)` must widen its intermediate sum the same way.
+# The second distinct aggregate keeps `single_distinct_to_group_by` from
+# rewriting the plan, so the distinct accumulator is the code under test.
+
+# sum(1..65536) = 2,147,516,416 > i32::MAX, avg = 32768.5
+query RTR
+select avg(distinct d), arrow_typeof(avg(distinct d)), avg(distinct v)
+from (
+ select arrow_cast(v, 'Decimal32(9, 0)') as d, v
+ from generate_series(1, 65536) t(v)
+) t;
+----
+32768.5 Decimal32(9, 4) 32768.5