1mod 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
60pub 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#[derive(Clone, Copy, Debug)]
84pub struct SumV2;
85
86impl SumV2 {
87 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 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 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
363pub struct SumV2Partial {
365 sum: SumState,
366 is_overflow: bool,
367 is_empty: bool,
368}
369
370impl SumV2Partial {
371 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
400fn 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;