Skip to main content

vortex_array/aggregate_fn/fns/sum_v2/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! SQL-style sums with explicit overflow and empty-input state.
5//!
6//! [`SumV2`] returns null when there are no valid values, while [`Sum`] returns zero. Tracking empty
7//! input separately from overflow requires a different partial representation. A separate aggregate
8//! preserves compatibility with the scalar partials stored by older Vortex files.
9
10mod grouped;
11pub(crate) use grouped::PrimitiveGroupedSumV2EncodingKernel;
12use vortex_error::VortexExpect;
13use vortex_error::VortexResult;
14use vortex_error::vortex_bail;
15use vortex_error::vortex_ensure;
16use vortex_error::vortex_err;
17use vortex_session::VortexSession;
18use vortex_session::registry::CachedId;
19
20use crate::ArrayRef;
21use crate::ArrayView;
22use crate::Canonical;
23use crate::Columnar;
24use crate::ExecutionCtx;
25use crate::aggregate_fn::Accumulator;
26use crate::aggregate_fn::AggregateArgs;
27use crate::aggregate_fn::AggregateFnId;
28use crate::aggregate_fn::AggregateFnVTable;
29use crate::aggregate_fn::DynAccumulator;
30use crate::aggregate_fn::NumericalAggregateOpts;
31use crate::aggregate_fn::fns::sum::Sum;
32use crate::aggregate_fn::fns::sum::SumState;
33use crate::aggregate_fn::fns::sum::accumulate_bool;
34use crate::aggregate_fn::fns::sum::accumulate_decimal;
35use crate::aggregate_fn::fns::sum::accumulate_primitive;
36use crate::aggregate_fn::fns::sum::checked_add_sum_states;
37use crate::aggregate_fn::fns::sum::make_zero_state;
38use crate::aggregate_fn::fns::sum::multiply_constant;
39use crate::arrays::Struct;
40use crate::arrays::struct_::StructArrayExt;
41use crate::builtins::ArrayBuiltins;
42use crate::dtype::DType;
43use crate::dtype::FieldName;
44use crate::dtype::FieldNames;
45use crate::dtype::Nullability;
46use crate::dtype::PType;
47use crate::dtype::StructFields;
48use crate::expr::stats::Precision;
49use crate::expr::stats::Stat;
50use crate::expr::stats::StatsProviderExt;
51use crate::scalar::Scalar;
52use crate::scalar::ScalarValue;
53use crate::scalar_fn::fns::operators::Operator;
54use crate::validity::Validity;
55
56const SUM_FIELD: &str = "sum";
57const IS_OVERFLOW_FIELD: &str = "is_overflow";
58const IS_EMPTY_FIELD: &str = "is_empty";
59
60/// Return the SQL-style sum of an array.
61///
62/// Unlike [`sum`](crate::aggregate_fn::fns::sum::sum), this returns null when the array has no
63/// valid values.
64pub fn sum_v2(array: &ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<Scalar> {
65    let mut acc = Accumulator::try_new(
66        SumV2,
67        NumericalAggregateOpts::default(),
68        array.dtype().clone(),
69    )?;
70    acc.accumulate(array, ctx)?;
71    acc.finish()
72}
73
74/// Sum an array, returning null when it has no valid values or if the sum overflows.
75///
76/// This aggregate intentionally has a distinct ID and partial representation from the legacy
77/// [`Sum`]. Keeping `vortex.sum` unchanged preserves the scalar partials stored by older Vortex
78/// files, while `SumV2` can use an explicit `{ sum, is_overflow, is_empty }` state.
79///
80/// NaN handling for float inputs is controlled by [`NumericalAggregateOpts`]. With `skip_nans`
81/// (the default), NaN values contribute nothing but still make the input non-empty. Otherwise,
82/// any NaN value poisons the sum to NaN.
83#[derive(Clone, Copy, Debug)]
84pub struct SumV2;
85
86impl SumV2 {
87    /// Build an encoding kernel's partial from a widened primitive sum.
88    ///
89    /// `sum` must have dtype `u64`, `i64`, or `f64`. A null sum records overflow and overrides
90    /// `is_empty`. Set `is_empty` only when there were no valid inputs. Valid NaNs make the input
91    /// non-empty even when skipped. The returned struct and its fields are non-null.
92    pub fn partial_from_sum(sum: Scalar, is_empty: bool) -> VortexResult<Scalar> {
93        vortex_ensure!(
94            matches!(
95                sum.dtype(),
96                DType::Primitive(PType::U64 | PType::I64 | PType::F64, _)
97            ),
98            "Expected a widened primitive sum, got {}",
99            sum.dtype(),
100        );
101
102        let sum_dtype = sum.dtype().as_nonnullable();
103        let is_overflow = sum.is_null();
104        let sum = if is_overflow {
105            Scalar::zero_value(&sum_dtype)
106        } else {
107            sum.cast(&sum_dtype)?
108        };
109
110        Ok(Scalar::struct_(
111            sum_v2_partial_dtype(sum_dtype),
112            vec![
113                sum,
114                Scalar::bool(is_overflow, Nullability::NonNullable),
115                Scalar::bool(is_empty && !is_overflow, Nullability::NonNullable),
116            ],
117        ))
118    }
119}
120
121impl AggregateFnVTable for SumV2 {
122    type Options = NumericalAggregateOpts;
123    type Partial = SumV2Partial;
124
125    fn id(&self) -> AggregateFnId {
126        static ID: CachedId = CachedId::new("vortex.sum_v2");
127        *ID
128    }
129
130    fn serialize(&self, options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
131        Ok(Some(options.serialize()))
132    }
133
134    fn deserialize(
135        &self,
136        metadata: &[u8],
137        _session: &VortexSession,
138    ) -> VortexResult<Self::Options> {
139        NumericalAggregateOpts::deserialize(metadata)
140    }
141
142    fn return_dtype(&self, options: &Self::Options, input_dtype: &DType) -> Option<DType> {
143        Sum.return_dtype(options, input_dtype)
144    }
145
146    fn partial_dtype(&self, options: &Self::Options, input_dtype: &DType) -> Option<DType> {
147        self.return_dtype(options, input_dtype)
148            .map(sum_v2_partial_dtype)
149    }
150
151    fn empty_partial(&self, args: AggregateArgs<'_, Self::Options>) -> VortexResult<Self::Partial> {
152        Ok(SumV2Partial::empty(args.return_dtype))
153    }
154
155    fn partial_from_scalar(
156        &self,
157        args: AggregateArgs<'_, Self::Options>,
158        scalar: &Scalar,
159    ) -> VortexResult<Self::Partial> {
160        let mut partial = SumV2Partial::empty(args.return_dtype);
161        let (sum, is_overflow, is_empty) = decode_partial_scalar(scalar, args.return_dtype)?;
162
163        // Adding the parsed value to the zero state cannot overflow; treat a decimal value that
164        // no longer fits its precision as an already-overflowed partial.
165        let overflowed = checked_add_sum_value(&mut partial.sum, args.return_dtype, sum)?;
166        partial.is_overflow = is_overflow || overflowed;
167        partial.is_empty = is_empty && !partial.is_overflow;
168        Ok(partial)
169    }
170
171    fn merge_partials(
172        &self,
173        args: AggregateArgs<'_, Self::Options>,
174        mut acc: Self::Partial,
175        partial: Self::Partial,
176    ) -> VortexResult<Self::Partial> {
177        if acc.is_overflow {
178            return Ok(acc);
179        }
180        if partial.is_overflow {
181            // An overflowed state keeps its last valid sum, so an empty accumulator adopts the
182            // incoming sum rather than reporting zero.
183            if acc.is_empty {
184                acc.sum = partial.sum;
185            }
186            acc.is_overflow = true;
187            acc.is_empty = false;
188            return Ok(acc);
189        }
190        if partial.is_empty {
191            return Ok(acc);
192        }
193        acc.is_overflow = checked_add_sum_states(&mut acc.sum, args.return_dtype, &partial.sum)?;
194        acc.is_empty = false;
195        Ok(acc)
196    }
197
198    fn to_scalar(
199        &self,
200        args: AggregateArgs<'_, Self::Options>,
201        partial: &Self::Partial,
202    ) -> VortexResult<Scalar> {
203        Ok(Scalar::struct_(
204            args.partial_dtype.clone(),
205            vec![
206                sum_state_scalar(partial, args.return_dtype, Nullability::NonNullable),
207                Scalar::bool(partial.is_overflow, Nullability::NonNullable),
208                Scalar::bool(partial.is_empty, Nullability::NonNullable),
209            ],
210        ))
211    }
212
213    fn is_saturated(
214        &self,
215        _args: AggregateArgs<'_, Self::Options>,
216        partial: &Self::Partial,
217    ) -> bool {
218        partial.is_overflow || matches!(&partial.sum, SumState::Float(value) if value.is_nan())
219    }
220
221    fn try_accumulate(
222        &self,
223        args: AggregateArgs<'_, Self::Options>,
224        partial: &mut Self::Partial,
225        batch: &ArrayRef,
226        _ctx: &mut ExecutionCtx,
227    ) -> VortexResult<bool> {
228        if args.options.skip_nans || !matches!(&partial.sum, SumState::Float(_)) {
229            return Ok(false);
230        }
231
232        match batch.statistics().get_as::<u64>(Stat::NaNCount) {
233            Precision::Exact(0) => Ok(false),
234            Precision::Exact(_) => {
235                let SumState::Float(sum) = &mut partial.sum else {
236                    unreachable!("checked float sum state")
237                };
238                *sum = f64::NAN;
239                partial.is_empty = false;
240                Ok(true)
241            }
242            _ => Ok(false),
243        }
244    }
245
246    fn accumulate(
247        &self,
248        args: AggregateArgs<'_, Self::Options>,
249        partial: &mut Self::Partial,
250        batch: &Columnar,
251        ctx: &mut ExecutionCtx,
252    ) -> VortexResult<()> {
253        if partial.is_overflow {
254            return Ok(());
255        }
256
257        if let Columnar::Constant(constant) = batch {
258            if !constant.scalar().is_null() && !constant.is_empty() {
259                partial.is_empty = false;
260            }
261            if args.options.skip_nans
262                && constant
263                    .scalar()
264                    .as_primitive_opt()
265                    .is_some_and(|primitive| primitive.is_nan())
266            {
267                return Ok(());
268            }
269            if let Some(product) =
270                multiply_constant(constant.scalar(), constant.len(), args.return_dtype)?
271            {
272                if product.is_null() {
273                    partial.is_overflow = true;
274                    partial.is_empty = false;
275                } else {
276                    partial.is_overflow =
277                        checked_add_sum_state(&mut partial.sum, args.return_dtype, &product)?;
278                    partial.is_empty = false;
279                }
280            }
281            return Ok(());
282        }
283
284        let any_valid = partial.is_empty && has_valid_value(batch, ctx)?;
285        let result = match batch {
286            Columnar::Canonical(canonical) => match canonical {
287                Canonical::Primitive(array) => {
288                    accumulate_primitive(&mut partial.sum, array, ctx, args.options.skip_nans)
289                }
290                Canonical::Bool(array) => accumulate_bool(&mut partial.sum, array, ctx),
291                Canonical::Decimal(array) => {
292                    accumulate_decimal(&mut partial.sum, args.return_dtype, array, ctx)
293                }
294                _ => {
295                    vortex_bail!("Unsupported canonical type for sum_v2: {}", batch.dtype())
296                }
297            },
298            Columnar::Constant(_) => unreachable!(),
299        };
300
301        if any_valid {
302            partial.is_empty = false;
303        }
304        if result? {
305            partial.is_overflow = true;
306            partial.is_empty = false;
307        }
308        Ok(())
309    }
310
311    fn finalize(
312        &self,
313        _args: AggregateArgs<'_, Self::Options>,
314        partials: ArrayRef,
315    ) -> VortexResult<ArrayRef> {
316        if let Some(partials) = partials.as_opt::<Struct>() {
317            return finalize_struct(partials);
318        }
319
320        let sum = partials.get_item(SUM_FIELD)?;
321        let is_invalid = partials
322            .get_item(IS_OVERFLOW_FIELD)?
323            .binary(partials.get_item(IS_EMPTY_FIELD)?, Operator::Or)?
324            .fill_null(true)?;
325        sum.mask(is_invalid.not()?)
326    }
327
328    fn finalize_scalar(
329        &self,
330        args: AggregateArgs<'_, Self::Options>,
331        partial: &Self::Partial,
332    ) -> VortexResult<Scalar> {
333        if partial.is_overflow || partial.is_empty {
334            return Ok(Scalar::null(args.return_dtype.as_nullable()));
335        }
336        Ok(sum_state_scalar(
337            partial,
338            args.return_dtype,
339            Nullability::Nullable,
340        ))
341    }
342}
343
344fn finalize_struct(partials: ArrayView<'_, Struct>) -> VortexResult<ArrayRef> {
345    let sum = partials.unmasked_field_by_name(SUM_FIELD)?.clone();
346    let is_overflow = partials.unmasked_field_by_name(IS_OVERFLOW_FIELD)?.clone();
347    let is_empty = partials.unmasked_field_by_name(IS_EMPTY_FIELD)?.clone();
348
349    let is_invalid = is_overflow
350        .binary(is_empty, Operator::Or)?
351        .fill_null(true)?;
352    let mut is_valid = is_invalid.not()?;
353    match partials.struct_validity() {
354        Validity::NonNullable | Validity::AllValid => {}
355        validity => {
356            is_valid = is_valid.binary(validity.to_array(partials.len()), Operator::And)?;
357        }
358    }
359
360    sum.mask(is_valid)
361}
362
363/// In-memory state for SumV2 accumulation.
364pub struct SumV2Partial {
365    sum: SumState,
366    is_overflow: bool,
367    is_empty: bool,
368}
369
370impl SumV2Partial {
371    /// The state of a group with no accumulated values.
372    fn empty(return_dtype: &DType) -> Self {
373        Self {
374            sum: make_zero_state(return_dtype),
375            is_overflow: false,
376            is_empty: true,
377        }
378    }
379}
380
381fn has_valid_value(batch: &Columnar, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
382    let (validity, len) = match batch {
383        Columnar::Canonical(Canonical::Primitive(array)) => {
384            (array.as_ref().validity()?, array.as_ref().len())
385        }
386        Columnar::Canonical(Canonical::Bool(array)) => {
387            (array.as_ref().validity()?, array.as_ref().len())
388        }
389        Columnar::Canonical(Canonical::Decimal(array)) => {
390            (array.as_ref().validity()?, array.as_ref().len())
391        }
392        Columnar::Canonical(_) => return Ok(false),
393        Columnar::Constant(constant) => {
394            return Ok(!constant.is_empty() && !constant.scalar().is_null());
395        }
396    };
397    Ok(validity.execute_mask(len, ctx)?.true_count() > 0)
398}
399
400/// Reads the `sum`, `is_overflow` and `is_empty` fields of a partial scalar.
401///
402/// This reads the struct values directly, because building a [`Scalar`] for each field costs more
403/// than the merge itself.
404fn decode_partial_scalar<'a>(
405    scalar: &'a Scalar,
406    return_dtype: &DType,
407) -> VortexResult<(&'a ScalarValue, bool, bool)> {
408    vortex_ensure!(!scalar.is_null(), "SumV2 partial must not be null");
409
410    let (DType::Struct(fields, _), Some(ScalarValue::Tuple(values))) =
411        (scalar.dtype(), scalar.value())
412    else {
413        vortex_bail!("SumV2 partial must be a struct, got {}", scalar.dtype());
414    };
415
416    let field_index = |name: &str| {
417        fields
418            .find(name)
419            .ok_or_else(|| vortex_err!("SumV2 partial is missing the {name} field"))
420    };
421    let bool_field = |name: &str| -> VortexResult<bool> {
422        match &values[field_index(name)?] {
423            Some(ScalarValue::Bool(value)) => Ok(*value),
424            _ => {
425                vortex_bail!("SumV2 partial field {name} must be a non-null bool")
426            }
427        }
428    };
429
430    let sum_index = field_index(SUM_FIELD)?;
431    let sum_dtype = fields
432        .field_dtypes()
433        .nth(sum_index)
434        .vortex_expect("field index from find is in bounds");
435    validate_sum_field_dtype(sum_dtype, return_dtype)?;
436
437    let sum = values[sum_index]
438        .as_ref()
439        .ok_or_else(|| vortex_err!("SumV2 partial sum must not be null"))?;
440
441    Ok((
442        sum,
443        bool_field(IS_OVERFLOW_FIELD)?,
444        bool_field(IS_EMPTY_FIELD)?,
445    ))
446}
447
448fn validate_sum_field_dtype(sum_dtype: &DType, return_dtype: &DType) -> VortexResult<()> {
449    vortex_ensure!(
450        sum_dtype.nullability() == Nullability::NonNullable
451            && sum_dtype.eq_ignore_nullability(return_dtype),
452        "SumV2 partial value has dtype {}, expected {}",
453        sum_dtype,
454        return_dtype.as_nonnullable(),
455    );
456    Ok(())
457}
458
459fn checked_add_sum_state(
460    state: &mut SumState,
461    return_dtype: &DType,
462    other: &Scalar,
463) -> VortexResult<bool> {
464    let other = other
465        .value()
466        .ok_or_else(|| vortex_err!("Can't extract present value from null scalar"))?;
467    checked_add_sum_value(state, return_dtype, other)
468}
469
470fn checked_add_sum_value(
471    state: &mut SumState,
472    return_dtype: &DType,
473    other: &ScalarValue,
474) -> VortexResult<bool> {
475    Ok(match (state, other) {
476        (SumState::Unsigned(sum), ScalarValue::Primitive(other)) => {
477            checked_add_u64(sum, other.cast::<u64>()?)
478        }
479        (SumState::Signed(sum), ScalarValue::Primitive(other)) => {
480            checked_add_i64(sum, other.cast::<i64>()?)
481        }
482        (SumState::Float(sum), ScalarValue::Primitive(other)) => {
483            *sum += other.cast::<f64>()?;
484            false
485        }
486        (SumState::Decimal(value), ScalarValue::Decimal(other)) => {
487            let dtype = return_dtype
488                .as_decimal_opt()
489                .vortex_expect("decimal sum result dtype");
490            match value.checked_add(other) {
491                Some(result) if result.fits_in_precision(*dtype) => {
492                    *value = result;
493                    false
494                }
495                Some(_) | None => true,
496            }
497        }
498        (_, other) => {
499            vortex_bail!("SumV2 cannot add {other} to a {return_dtype} sum")
500        }
501    })
502}
503
504fn sum_v2_partial_dtype(sum_dtype: DType) -> DType {
505    DType::Struct(sum_v2_partial_fields(sum_dtype), Nullability::Nullable)
506}
507
508fn sum_v2_partial_fields(sum_dtype: DType) -> StructFields {
509    StructFields::new(
510        FieldNames::from_iter([
511            FieldName::from(SUM_FIELD),
512            FieldName::from(IS_OVERFLOW_FIELD),
513            FieldName::from(IS_EMPTY_FIELD),
514        ]),
515        vec![
516            sum_dtype.as_nonnullable(),
517            DType::Bool(Nullability::NonNullable),
518            DType::Bool(Nullability::NonNullable),
519        ],
520    )
521}
522
523fn sum_state_scalar(
524    partial: &SumV2Partial,
525    return_dtype: &DType,
526    nullability: Nullability,
527) -> Scalar {
528    match &partial.sum {
529        SumState::Unsigned(value) => Scalar::primitive(*value, nullability),
530        SumState::Signed(value) => Scalar::primitive(*value, nullability),
531        SumState::Float(value) => Scalar::primitive(*value, nullability),
532        SumState::Decimal(value) => Scalar::decimal(
533            *value,
534            *return_dtype
535                .as_decimal_opt()
536                .vortex_expect("decimal sum result dtype"),
537            nullability,
538        ),
539    }
540}
541
542fn checked_add_u64(sum: &mut u64, value: u64) -> bool {
543    match sum.checked_add(value) {
544        Some(result) => {
545            *sum = result;
546            false
547        }
548        None => true,
549    }
550}
551
552fn checked_add_i64(sum: &mut i64, value: i64) -> bool {
553    match sum.checked_add(value) {
554        Some(result) => {
555            *sum = result;
556            false
557        }
558        None => true,
559    }
560}
561
562#[cfg(test)]
563mod tests;