Skip to main content

vortex_array/aggregate_fn/fns/is_constant/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4mod bool;
5mod decimal;
6mod extension;
7mod fixed_size_list;
8mod list;
9mod map;
10pub mod primitive;
11mod struct_;
12mod varbin;
13
14use vortex_error::VortexExpect;
15use vortex_error::VortexResult;
16use vortex_error::vortex_bail;
17use vortex_mask::Mask;
18use vortex_session::VortexSession;
19use vortex_session::registry::CachedId;
20
21use self::bool::check_bool_constant;
22use self::decimal::check_decimal_constant;
23use self::extension::check_extension_constant;
24use self::fixed_size_list::check_fixed_size_list_constant;
25use self::list::check_listview_constant;
26use self::map::check_map_constant;
27use self::primitive::check_primitive_constant;
28use self::struct_::check_struct_constant;
29use self::varbin::check_varbinview_constant;
30use crate::ArrayRef;
31use crate::Canonical;
32use crate::Columnar;
33use crate::ExecutionCtx;
34use crate::IntoArray;
35use crate::aggregate_fn::Accumulator;
36use crate::aggregate_fn::AggregateArgs;
37use crate::aggregate_fn::AggregateFnId;
38use crate::aggregate_fn::AggregateFnVTable;
39use crate::aggregate_fn::DynAccumulator;
40use crate::aggregate_fn::EmptyOptions;
41use crate::arrays::Constant;
42use crate::arrays::Null;
43use crate::builtins::ArrayBuiltins;
44use crate::dtype::DType;
45use crate::dtype::FieldNames;
46use crate::dtype::Nullability;
47use crate::dtype::StructFields;
48use crate::expr::stats::Precision;
49use crate::expr::stats::Stat;
50use crate::expr::stats::StatsProvider;
51use crate::expr::stats::StatsProviderExt;
52use crate::scalar::Scalar;
53use crate::scalar_fn::fns::operators::Operator;
54
55/// Check if two arrays of the same length have equal values at every position (null-safe).
56///
57/// Two positions are considered equal if they are both null, or both non-null with the same value.
58// TODO(ngates): move this function out when we have any/all aggregate functions.
59fn arrays_value_equal(a: &ArrayRef, b: &ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
60    debug_assert_eq!(a.len(), b.len());
61    if a.is_empty() {
62        return Ok(true);
63    }
64
65    // Check validity masks match (null positions must be identical).
66    let a_mask = a.validity()?.execute_mask(a.len(), ctx)?;
67    let b_mask = b.validity()?.execute_mask(b.len(), ctx)?;
68    if a_mask != b_mask {
69        return Ok(false);
70    }
71
72    let valid_count = a_mask.true_count();
73    if valid_count == 0 {
74        // Both all-null → equal.
75        return Ok(true);
76    }
77
78    // Compare values element-wise. Result is null where both inputs are null,
79    // true/false where both are valid.
80    let eq_result = a.binary(b.clone(), Operator::Eq)?;
81    let eq_result = eq_result.fill_null(false)?.execute::<Mask>(ctx)?;
82
83    Ok(eq_result.true_count() == valid_count)
84}
85
86/// Compute whether an array has constant values.
87///
88/// An array is constant IFF at least one of the following conditions apply:
89/// 1. It has at least one element (**Note** - an empty array isn't constant).
90/// 2. It's encoded as a [`ConstantArray`](crate::arrays::ConstantArray) or [`NullArray`](crate::arrays::NullArray)
91/// 3. Has an exact statistic attached to it, saying its constant.
92/// 4. Is all invalid.
93/// 5. Is all valid AND has minimum and maximum statistics that are equal.
94pub fn is_constant(array: &ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
95    // Short-circuit using cached array statistics.
96    if let Precision::Exact(value) = array.statistics().get_as::<bool>(Stat::IsConstant) {
97        return Ok(value);
98    }
99
100    // Empty arrays are not constant.
101    if array.is_empty() {
102        return Ok(false);
103    }
104
105    // Array of length 1 is always constant.
106    if array.len() == 1 {
107        array
108            .statistics()
109            .set(Stat::IsConstant, Precision::Exact(true.into()));
110        return Ok(true);
111    }
112
113    // Constant and null arrays are always constant.
114    if array.is::<Constant>() || array.is::<Null>() {
115        array
116            .statistics()
117            .set(Stat::IsConstant, Precision::Exact(true.into()));
118        return Ok(true);
119    }
120
121    let all_invalid = array.all_invalid(ctx)?;
122    if all_invalid {
123        array
124            .statistics()
125            .set(Stat::IsConstant, Precision::Exact(true.into()));
126        return Ok(true);
127    }
128
129    let all_valid = array.all_valid(ctx)?;
130
131    // If we have some nulls but not all nulls, array can't be constant.
132    if !all_valid && !all_invalid {
133        array
134            .statistics()
135            .set(Stat::IsConstant, Precision::Exact(false.into()));
136        return Ok(false);
137    }
138
139    // We already know here that the array is all valid, so we check for min/max stats.
140    let min_stat = array.statistics().get(Stat::Min);
141    let max_stat = array.statistics().get(Stat::Max);
142
143    if let Precision::Exact(min) = min_stat.as_ref()
144        && let Precision::Exact(max) = max_stat.as_ref()
145        && min == max
146        && (Stat::NaNCount.dtype(array.dtype()).is_none()
147            || array.statistics().get_as::<u64>(Stat::NaNCount) == Precision::exact(0u64))
148    {
149        array
150            .statistics()
151            .set(Stat::IsConstant, Precision::Exact(true.into()));
152        return Ok(true);
153    }
154
155    // Short-circuit for unsupported dtypes.
156    if IsConstant
157        .return_dtype(&EmptyOptions, array.dtype())
158        .is_none()
159    {
160        // Null dtype - vacuously false for empty
161        return Ok(false);
162    }
163
164    // Compute using Accumulator<IsConstant>.
165    let mut acc = Accumulator::try_new(IsConstant, EmptyOptions, array.dtype().clone())?;
166    acc.accumulate(array, ctx)?;
167    let result_scalar = acc.finish()?;
168
169    let result = result_scalar.as_bool().value().unwrap_or(false);
170
171    // Cache the computed is_constant as a statistic.
172    array
173        .statistics()
174        .set(Stat::IsConstant, Precision::Exact(result.into()));
175
176    Ok(result)
177}
178
179/// Compute whether an array is constant.
180///
181/// Returns a `Bool(NonNullable)` scalar.
182/// The partial state is a nullable struct `{is_constant: Bool(NN), value: input_dtype?}`.
183/// A null struct means the accumulator has seen no data yet (empty).
184#[derive(Clone, Debug)]
185pub struct IsConstant;
186
187impl IsConstant {
188    /// Build a partial scalar from a kernel's `is_constant` result.
189    ///
190    /// Kernels that compute `is_constant` by delegating to child arrays can call this
191    /// to package the boolean result into the partial struct format expected by the
192    /// accumulator, avoiding duplicated boilerplate.
193    pub fn make_partial(
194        batch: &ArrayRef,
195        is_constant: bool,
196        ctx: &mut ExecutionCtx,
197    ) -> VortexResult<Scalar> {
198        let partial_dtype = make_is_constant_partial_dtype(batch.dtype());
199        if batch.is_empty() {
200            return Ok(Scalar::null(partial_dtype));
201        }
202
203        if is_constant {
204            let first_value = batch.execute_scalar(0, ctx)?.into_nullable();
205            Ok(Scalar::struct_(
206                partial_dtype,
207                vec![Scalar::bool(true, Nullability::NonNullable), first_value],
208            ))
209        } else {
210            Ok(Scalar::struct_(
211                partial_dtype,
212                vec![
213                    Scalar::bool(false, Nullability::NonNullable),
214                    Scalar::null(batch.dtype().as_nullable()),
215                ],
216            ))
217        }
218    }
219}
220
221/// Partial accumulator state for is_constant.
222pub struct IsConstantPartial {
223    is_constant: bool,
224    /// None = empty (no values seen), Some(null) = all nulls, Some(v) = first value seen.
225    first_value: Option<Scalar>,
226}
227
228impl IsConstantPartial {
229    /// The state of a group with no accumulated values.
230    fn empty() -> Self {
231        Self {
232            is_constant: true,
233            first_value: None,
234        }
235    }
236
237    fn check_value(&mut self, value: Scalar) {
238        if !self.is_constant {
239            return;
240        }
241        match &self.first_value {
242            None => {
243                self.first_value = Some(value);
244            }
245            Some(first) => {
246                if *first != value {
247                    self.is_constant = false;
248                }
249            }
250        }
251    }
252}
253
254static NAMES: std::sync::LazyLock<FieldNames> =
255    std::sync::LazyLock::new(|| FieldNames::from(["is_constant", "value"]));
256
257pub fn make_is_constant_partial_dtype(element_dtype: &DType) -> DType {
258    DType::Struct(
259        StructFields::new(
260            NAMES.clone(),
261            vec![
262                DType::Bool(Nullability::NonNullable),
263                element_dtype.as_nullable(),
264            ],
265        ),
266        Nullability::Nullable,
267    )
268}
269
270impl AggregateFnVTable for IsConstant {
271    type Options = EmptyOptions;
272    type Partial = IsConstantPartial;
273
274    fn id(&self) -> AggregateFnId {
275        static ID: CachedId = CachedId::new("vortex.is_constant");
276        *ID
277    }
278
279    fn serialize(&self, _options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
280        Ok(Some(vec![]))
281    }
282
283    fn deserialize(
284        &self,
285        _metadata: &[u8],
286        _session: &VortexSession,
287    ) -> VortexResult<Self::Options> {
288        Ok(EmptyOptions)
289    }
290
291    fn return_dtype(&self, _options: &Self::Options, input_dtype: &DType) -> Option<DType> {
292        match input_dtype {
293            DType::Null | DType::Variant(..) => None,
294            _ => Some(DType::Bool(Nullability::NonNullable)),
295        }
296    }
297
298    fn partial_dtype(&self, _options: &Self::Options, input_dtype: &DType) -> Option<DType> {
299        match input_dtype {
300            DType::Null | DType::Variant(..) => None,
301            _ => Some(make_is_constant_partial_dtype(input_dtype)),
302        }
303    }
304
305    fn empty_partial(
306        &self,
307        _args: AggregateArgs<'_, Self::Options>,
308    ) -> VortexResult<Self::Partial> {
309        Ok(IsConstantPartial::empty())
310    }
311
312    fn partial_from_scalar(
313        &self,
314        _args: AggregateArgs<'_, Self::Options>,
315        scalar: &Scalar,
316    ) -> VortexResult<Self::Partial> {
317        // A null struct means the producing accumulator was empty.
318        if scalar.is_null() {
319            return Ok(IsConstantPartial::empty());
320        }
321
322        let is_constant = scalar
323            .as_struct()
324            .field_by_idx(0)
325            .map(|s| s.as_bool().value().unwrap_or(false))
326            .unwrap_or(false);
327
328        Ok(IsConstantPartial {
329            is_constant,
330            first_value: scalar.as_struct().field_by_idx(1),
331        })
332    }
333
334    fn merge_partials(
335        &self,
336        _args: AggregateArgs<'_, Self::Options>,
337        mut acc: Self::Partial,
338        partial: Self::Partial,
339    ) -> VortexResult<Self::Partial> {
340        if !partial.is_constant {
341            acc.is_constant = false;
342        } else if let Some(value) = partial.first_value {
343            acc.check_value(value);
344        }
345        Ok(acc)
346    }
347
348    fn to_scalar(
349        &self,
350        args: AggregateArgs<'_, Self::Options>,
351        partial: &Self::Partial,
352    ) -> VortexResult<Scalar> {
353        let dtype = args.partial_dtype.clone();
354        let element_dtype = args.dtype.as_nullable();
355        // Only a constant partial that saw no values is the empty (null) state: a non-constant
356        // verdict stands regardless of whether a value was observed.
357        let first_value = match &partial.first_value {
358            Some(first_value) => first_value.clone().cast(&element_dtype)?,
359            None if partial.is_constant => return Ok(Scalar::null(dtype)),
360            None => Scalar::null(element_dtype),
361        };
362        Ok(Scalar::struct_(
363            dtype,
364            vec![
365                Scalar::bool(partial.is_constant, Nullability::NonNullable),
366                first_value,
367            ],
368        ))
369    }
370
371    #[inline]
372    fn is_saturated(
373        &self,
374        _args: AggregateArgs<'_, Self::Options>,
375        partial: &Self::Partial,
376    ) -> bool {
377        !partial.is_constant
378    }
379
380    fn accumulate(
381        &self,
382        args: AggregateArgs<'_, Self::Options>,
383        partial: &mut Self::Partial,
384        batch: &Columnar,
385        ctx: &mut ExecutionCtx,
386    ) -> VortexResult<()> {
387        if !partial.is_constant {
388            return Ok(());
389        }
390
391        match batch {
392            Columnar::Constant(c) => {
393                if c.is_empty() {
394                    return Ok(());
395                }
396
397                partial.check_value(c.scalar().clone().into_nullable());
398                Ok(())
399            }
400            Columnar::Canonical(c) => {
401                if c.is_empty() {
402                    return Ok(());
403                }
404
405                // Convert to ArrayRef for DynArrayData methods.
406                let array_ref = c.clone().into_array();
407
408                let all_invalid = array_ref.all_invalid(ctx)?;
409                if all_invalid {
410                    partial.check_value(Scalar::null(args.dtype.as_nullable()));
411                    return Ok(());
412                }
413
414                let all_valid = array_ref.all_valid(ctx)?;
415                // Mixed nulls → not constant.
416                if !all_valid && !all_invalid {
417                    partial.is_constant = false;
418                    return Ok(());
419                }
420
421                // All valid from here. Check batch-level constancy.
422                if c.len() == 1 {
423                    partial.check_value(array_ref.execute_scalar(0, ctx)?.into_nullable());
424                    return Ok(());
425                }
426
427                let batch_is_constant = match c {
428                    Canonical::Primitive(p) => check_primitive_constant(p),
429                    Canonical::Bool(b) => check_bool_constant(b),
430                    Canonical::VarBinView(v) => check_varbinview_constant(v),
431                    Canonical::Decimal(d) => check_decimal_constant(d),
432                    Canonical::Struct(s) => check_struct_constant(s, ctx)?,
433                    Canonical::Extension(e) => check_extension_constant(e, ctx)?,
434                    Canonical::List(l) => check_listview_constant(l, ctx)?,
435                    Canonical::Map(m) => check_map_constant(m, ctx)?,
436                    Canonical::FixedSizeList(f) => check_fixed_size_list_constant(f, ctx)?,
437                    Canonical::Null(_) => true,
438                    Canonical::Union(_) => {
439                        vortex_bail!("TODO(connor)[Union]: implement IsConstant for Union arrays")
440                    }
441                    Canonical::Variant(_) => {
442                        vortex_bail!("Variant arrays don't support IsConstant")
443                    }
444                };
445
446                if !batch_is_constant {
447                    partial.is_constant = false;
448                    return Ok(());
449                }
450
451                partial.check_value(array_ref.execute_scalar(0, ctx)?.into_nullable());
452                Ok(())
453            }
454        }
455    }
456
457    fn finalize(
458        &self,
459        _args: AggregateArgs<'_, Self::Options>,
460        partials: ArrayRef,
461    ) -> VortexResult<ArrayRef> {
462        // A null partial is the empty state of an empty or null group, which is not constant.
463        partials
464            .get_item(NAMES.get(0).vortex_expect("out of bounds").clone())?
465            .fill_null(false)
466    }
467
468    fn finalize_scalar(
469        &self,
470        _args: AggregateArgs<'_, Self::Options>,
471        partial: &Self::Partial,
472    ) -> VortexResult<Scalar> {
473        if partial.first_value.is_none() {
474            // Empty accumulator → return false.
475            return Ok(Scalar::bool(false, Nullability::NonNullable));
476        }
477        Ok(Scalar::bool(partial.is_constant, Nullability::NonNullable))
478    }
479}
480
481#[cfg(test)]
482mod tests {
483    use std::sync::LazyLock;
484
485    use rstest::rstest;
486    use vortex_buffer::Buffer;
487    use vortex_buffer::buffer;
488    use vortex_error::VortexResult;
489    use vortex_session::VortexSession;
490
491    use crate::IntoArray as _;
492    use crate::VortexSessionExecute;
493    use crate::aggregate_fn::Accumulator;
494    use crate::aggregate_fn::AggregateDTypes;
495    use crate::aggregate_fn::AggregateFnVTable;
496    use crate::aggregate_fn::DynAccumulator;
497    use crate::aggregate_fn::DynGroupedAccumulator;
498    use crate::aggregate_fn::EmptyOptions;
499    use crate::aggregate_fn::GroupedAccumulator;
500    use crate::aggregate_fn::fns::is_constant::IsConstant;
501    use crate::aggregate_fn::fns::is_constant::IsConstantPartial;
502    use crate::aggregate_fn::fns::is_constant::is_constant;
503    use crate::arrays::BoolArray;
504    use crate::arrays::ChunkedArray;
505    use crate::arrays::ConstantArray;
506    use crate::arrays::DecimalArray;
507    use crate::arrays::DictArray;
508    use crate::arrays::ListArray;
509    use crate::arrays::ListViewArray;
510    use crate::arrays::PrimitiveArray;
511    use crate::arrays::StructArray;
512    use crate::arrays::runend::RunEnd;
513    use crate::assert_arrays_eq;
514    use crate::builders::MapBuilder;
515    use crate::dtype::DType;
516    use crate::dtype::DecimalDType;
517    use crate::dtype::FieldNames;
518    use crate::dtype::MapDType;
519    use crate::dtype::Nullability;
520    use crate::dtype::PType;
521    use crate::expr::stats::Stat;
522    use crate::scalar::Scalar;
523    use crate::validity::Validity;
524
525    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
526
527    type MapEntryFixture<'a> = (i32, Option<&'a str>);
528    type MapRowFixture<'a> = Option<Vec<MapEntryFixture<'a>>>;
529
530    fn map_array_from_rows(rows: &[MapRowFixture<'_>]) -> VortexResult<crate::ArrayRef> {
531        let map_dtype = MapDType::try_new(
532            DType::Primitive(PType::I32, Nullability::NonNullable),
533            DType::Utf8(Nullability::Nullable),
534            false,
535        )?;
536        let dtype = DType::Map(map_dtype.clone(), Nullability::Nullable);
537        let mut builder = MapBuilder::<u64, u64>::with_capacity_in(
538            map_dtype,
539            Nullability::Nullable,
540            rows.len(),
541            vortex_buffer::BufferAllocatorRef::static_ref(),
542        );
543
544        for row in rows {
545            let scalar = match row {
546                Some(entries) => {
547                    let entries = entries
548                        .iter()
549                        .map(|(key, value)| {
550                            let key = Scalar::primitive(*key, Nullability::NonNullable);
551                            let value = value.map_or_else(
552                                || Scalar::null(DType::Utf8(Nullability::Nullable)),
553                                |value| Scalar::utf8(value, Nullability::Nullable),
554                            );
555                            (key, value)
556                        })
557                        .collect::<Vec<_>>();
558                    Scalar::try_map(dtype.clone(), entries)?
559                }
560                None => Scalar::null(dtype.clone()),
561            };
562            builder.append_value(scalar.as_map())?;
563        }
564
565        Ok(builder.finish_into_map().into_array())
566    }
567
568    // Tests migrated from compute/is_constant.rs
569    #[test]
570    fn is_constant_min_max_no_nan() -> VortexResult<()> {
571        let mut ctx = SESSION.create_execution_ctx();
572
573        let arr = buffer![0, 1].into_array();
574        arr.statistics()
575            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
576        assert!(!is_constant(&arr, &mut ctx)?);
577
578        let arr = buffer![0, 0].into_array();
579        arr.statistics()
580            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
581        assert!(is_constant(&arr, &mut ctx)?);
582
583        let arr = PrimitiveArray::from_option_iter([Some(0), Some(0)]).into_array();
584        assert!(is_constant(&arr, &mut ctx)?);
585        Ok(())
586    }
587
588    #[test]
589    fn is_constant_min_max_with_nan() -> VortexResult<()> {
590        let mut ctx = SESSION.create_execution_ctx();
591
592        let arr = PrimitiveArray::from_iter([0.0, 0.0, f32::NAN]).into_array();
593        arr.statistics()
594            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
595        assert!(!is_constant(&arr, &mut ctx)?);
596
597        let arr =
598            PrimitiveArray::from_option_iter([Some(f32::NEG_INFINITY), Some(f32::NEG_INFINITY)])
599                .into_array();
600        arr.statistics()
601            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
602        assert!(is_constant(&arr, &mut ctx)?);
603        Ok(())
604    }
605
606    // Tests migrated from arrays/bool/compute/is_constant.rs
607    #[rstest]
608    #[case(vec![true], true)]
609    #[case(vec![false; 65], true)]
610    #[case({
611        let mut v = vec![true; 64];
612        v.push(false);
613        v
614    }, false)]
615    fn test_bool_is_constant(#[case] input: Vec<bool>, #[case] expected: bool) -> VortexResult<()> {
616        let array = BoolArray::from_iter(input);
617        let mut ctx = SESSION.create_execution_ctx();
618        assert_eq!(is_constant(&array.into_array(), &mut ctx)?, expected);
619        Ok(())
620    }
621
622    // Tests migrated from arrays/chunked/compute/is_constant.rs
623    #[test]
624    fn empty_chunk_is_constant() -> VortexResult<()> {
625        let chunked = ChunkedArray::try_new(
626            vec![
627                Buffer::<u8>::empty().into_array(),
628                Buffer::<u8>::empty().into_array(),
629                buffer![255u8, 255].into_array(),
630                Buffer::<u8>::empty().into_array(),
631                buffer![255u8, 255].into_array(),
632            ],
633            DType::Primitive(PType::U8, Nullability::NonNullable),
634        )?
635        .into_array();
636
637        let mut ctx = SESSION.create_execution_ctx();
638        assert!(is_constant(&chunked, &mut ctx)?);
639        Ok(())
640    }
641
642    // Tests migrated from arrays/decimal/compute/is_constant.rs
643    #[test]
644    fn test_decimal_is_constant() -> VortexResult<()> {
645        let mut ctx = SESSION.create_execution_ctx();
646
647        let array = DecimalArray::new(
648            buffer![0i128, 1i128, 2i128],
649            DecimalDType::new(19, 0),
650            Validity::NonNullable,
651        );
652        assert!(!is_constant(&array.into_array(), &mut ctx)?);
653
654        let array = DecimalArray::new(
655            buffer![100i128, 100i128, 100i128],
656            DecimalDType::new(19, 0),
657            Validity::NonNullable,
658        );
659        assert!(is_constant(&array.into_array(), &mut ctx)?);
660        Ok(())
661    }
662
663    // Tests migrated from arrays/list/compute/is_constant.rs
664    #[test]
665    fn test_is_constant_nested_list() -> VortexResult<()> {
666        let mut ctx = SESSION.create_execution_ctx();
667
668        let xs = ListArray::try_new(
669            buffer![0i32, 1, 0, 1].into_array(),
670            buffer![0u32, 2, 4].into_array(),
671            Validity::NonNullable,
672            &mut ctx,
673        )?;
674
675        let struct_of_lists = StructArray::try_new(
676            FieldNames::from(["xs"]),
677            vec![xs.into_array()],
678            2,
679            Validity::NonNullable,
680        )?;
681        assert!(is_constant(
682            &struct_of_lists.clone().into_array(),
683            &mut ctx
684        )?);
685        assert!(is_constant(&struct_of_lists.into_array(), &mut ctx)?);
686        Ok(())
687    }
688
689    #[rstest]
690    #[case(
691        // [1,2], [1, 2], [1, 2]
692        vec![1i32, 2, 1, 2, 1, 2],
693        vec![0u32, 2, 4, 6],
694        true
695    )]
696    #[case(
697        // [1, 2], [3], [4, 5]
698        vec![1i32, 2, 3, 4, 5],
699        vec![0u32, 2, 3, 5],
700        false
701    )]
702    #[case(
703        // [1, 2], [3, 4]
704        vec![1i32, 2, 3, 4],
705        vec![0u32, 2, 4],
706        false
707    )]
708    #[case(
709        // [], [], []
710        vec![],
711        vec![0u32, 0, 0, 0],
712        true
713    )]
714    fn test_list_is_constant(
715        #[case] elements: Vec<i32>,
716        #[case] offsets: Vec<u32>,
717        #[case] expected: bool,
718    ) -> VortexResult<()> {
719        let list_array = ListArray::try_new(
720            PrimitiveArray::from_iter(elements).into_array(),
721            PrimitiveArray::from_iter(offsets).into_array(),
722            Validity::NonNullable,
723            &mut SESSION.create_execution_ctx(),
724        )?;
725
726        let mut ctx = SESSION.create_execution_ctx();
727        assert_eq!(is_constant(&list_array.into_array(), &mut ctx)?, expected);
728        Ok(())
729    }
730
731    #[test]
732    fn test_list_is_constant_nested_lists() -> VortexResult<()> {
733        let mut ctx = SESSION.create_execution_ctx();
734        let inner_elements = buffer![1i32, 2, 1, 2].into_array();
735        let inner_offsets = buffer![0u32, 1, 2, 3, 4].into_array();
736        let inner_lists = ListArray::try_new(
737            inner_elements,
738            inner_offsets,
739            Validity::NonNullable,
740            &mut ctx,
741        )?;
742
743        let outer_offsets = buffer![0u32, 2, 4].into_array();
744        let outer_list = ListArray::try_new(
745            inner_lists.into_array(),
746            outer_offsets,
747            Validity::NonNullable,
748            &mut ctx,
749        )?;
750
751        let mut ctx = SESSION.create_execution_ctx();
752        // Both outer lists contain [[1], [2]], so should be constant
753        assert!(is_constant(&outer_list.into_array(), &mut ctx)?);
754        Ok(())
755    }
756
757    #[rstest]
758    #[case(
759        // 100 identical [1, 2] lists
760        [1i32, 2].repeat(100),
761        (0..101).map(|i| (i * 2) as u32).collect(),
762        true
763    )]
764    #[case(
765        // Difference after threshold: 64 identical [1, 2] + one [3, 4]
766        {
767            let mut elements = [1i32, 2].repeat(64);
768            elements.extend_from_slice(&[3, 4]);
769            elements
770        },
771        (0..66).map(|i| (i * 2) as u32).collect(),
772        false
773    )]
774    #[case(
775        // Difference in first 64: first 63 identical [1, 2] + one [3, 4] + rest identical [1, 2]
776        {
777            let mut elements = [1i32, 2].repeat(63);
778            elements.extend_from_slice(&[3, 4]);
779            elements.extend([1i32, 2].repeat(37));
780            elements
781        },
782        (0..101).map(|i| (i * 2) as u32).collect(),
783        false
784    )]
785    fn test_list_is_constant_with_threshold(
786        #[case] elements: Vec<i32>,
787        #[case] offsets: Vec<u32>,
788        #[case] expected: bool,
789    ) -> VortexResult<()> {
790        let list_array = ListArray::try_new(
791            PrimitiveArray::from_iter(elements).into_array(),
792            PrimitiveArray::from_iter(offsets).into_array(),
793            Validity::NonNullable,
794            &mut SESSION.create_execution_ctx(),
795        )?;
796
797        let mut ctx = SESSION.create_execution_ctx();
798        assert_eq!(is_constant(&list_array.into_array(), &mut ctx)?, expected);
799        Ok(())
800    }
801
802    #[test]
803    fn test_map_is_constant() -> VortexResult<()> {
804        let mut ctx = SESSION.create_execution_ctx();
805
806        let identical = map_array_from_rows(&[
807            Some(vec![(1, Some("one")), (2, None)]),
808            Some(vec![(1, Some("one")), (2, None)]),
809        ])?;
810        assert!(is_constant(&identical, &mut ctx)?);
811
812        let different = map_array_from_rows(&[
813            Some(vec![(1, Some("one")), (2, None)]),
814            Some(vec![(1, Some("one")), (3, None)]),
815        ])?;
816        assert!(!is_constant(&different, &mut ctx)?);
817
818        let all_null = map_array_from_rows(&[None, None])?;
819        assert!(is_constant(&all_null, &mut ctx)?);
820
821        Ok(())
822    }
823
824    #[test]
825    fn empty_constant_leaves_partial_empty() -> VortexResult<()> {
826        let mut ctx = SESSION.create_execution_ctx();
827        let array = ConstantArray::new(Scalar::from(99i32), 0).into_array();
828        let mut acc = Accumulator::try_new(IsConstant, EmptyOptions, array.dtype().clone())?;
829
830        acc.accumulate(&array, &mut ctx)?;
831
832        assert!(acc.partial_scalar()?.is_null());
833        Ok(())
834    }
835
836    /// Merging a non-constant partial into a materialized empty one must keep the false verdict
837    /// in the partial scalar rather than collapsing it to the empty state.
838    #[test]
839    fn non_constant_merged_into_empty_keeps_verdict() -> VortexResult<()> {
840        let mut ctx = SESSION.create_execution_ctx();
841        let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
842        let mut empty = Accumulator::try_new(IsConstant, EmptyOptions, dtype.clone())?;
843        let mut varying = Accumulator::try_new(IsConstant, EmptyOptions, dtype)?;
844
845        // An empty batch materializes the empty partial in place.
846        empty.accumulate(
847            &PrimitiveArray::new(Buffer::<i32>::empty(), Validity::NonNullable).into_array(),
848            &mut ctx,
849        )?;
850        varying.accumulate(&buffer![1i32, 2].into_array(), &mut ctx)?;
851        empty.merge_from(&mut varying)?;
852
853        assert!(!empty.partial_scalar()?.is_null());
854        assert_eq!(
855            empty.finish()?,
856            Scalar::bool(false, Nullability::NonNullable)
857        );
858        Ok(())
859    }
860
861    /// A non-constant verdict without an observed value is not the empty state.
862    #[test]
863    fn non_constant_partial_without_value_is_not_empty() -> VortexResult<()> {
864        let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
865        let owned = AggregateDTypes::try_new(&IsConstant, &EmptyOptions, dtype)?;
866        let args = owned.args(&EmptyOptions);
867        let partial = IsConstantPartial {
868            is_constant: false,
869            first_value: None,
870        };
871
872        let scalar = IsConstant.to_scalar(args, &partial)?;
873        assert!(!scalar.is_null());
874        let parsed = IsConstant.partial_from_scalar(args, &scalar)?;
875        assert_eq!(
876            IsConstant.finalize_scalar(args, &parsed)?,
877            Scalar::bool(false, Nullability::NonNullable)
878        );
879        Ok(())
880    }
881
882    #[rstest]
883    fn empty_batch_leaves_constant_partial_empty(
884        #[values("primitive", "dict", "runend")] encoding: &str,
885    ) -> VortexResult<()> {
886        let mut ctx = SESSION.create_execution_ctx();
887        let empty = match encoding {
888            "primitive" => Buffer::<i32>::empty().into_array(),
889            "dict" => DictArray::try_new(
890                Buffer::<u32>::empty().into_array(),
891                buffer![1i32].into_array(),
892            )?
893            .into_array(),
894            "runend" => RunEnd::encode(Buffer::<i32>::empty().into_array(), &mut ctx)?.into_array(),
895            _ => unreachable!(),
896        };
897        let mut acc = Accumulator::try_new(IsConstant, EmptyOptions, empty.dtype().clone())?;
898        acc.accumulate(&empty, &mut ctx)?;
899
900        assert!(acc.partial_scalar()?.is_null());
901        assert!(!is_constant(&empty, &mut ctx)?);
902
903        acc.accumulate(&buffer![1i32, 1].into_array(), &mut ctx)?;
904        acc.accumulate(&empty, &mut ctx)?;
905
906        assert_eq!(acc.finish()?, Scalar::bool(true, Nullability::NonNullable));
907        Ok(())
908    }
909
910    #[test]
911    fn grouped_is_constant() -> VortexResult<()> {
912        let mut ctx = SESSION.create_execution_ctx();
913        let elements = PrimitiveArray::from_option_iter([Some(5i32), Some(5), Some(6), None, None])
914            .into_array();
915        let dtype = elements.dtype().clone();
916
917        // The groups are `[5, 5]`, `[5, 6]`, `[]`, `[null, null]`, and a null group.
918        let groups = ListViewArray::try_new(
919            elements,
920            buffer![0i32, 1, 0, 3, 0].into_array(),
921            buffer![2i32, 2, 0, 2, 0].into_array(),
922            Validity::from_iter([true, true, true, true, false]),
923            &mut ctx,
924        )?
925        .into_array();
926
927        let mut acc = GroupedAccumulator::try_new(IsConstant, EmptyOptions, dtype)?;
928        acc.accumulate_list(&groups, &mut ctx)?;
929
930        assert_arrays_eq!(
931            acc.finish()?,
932            BoolArray::from_iter([true, false, false, true, false]),
933            &mut ctx
934        );
935        Ok(())
936    }
937}