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        partials.get_item(NAMES.get(0).vortex_expect("out of bounds").clone())
463    }
464
465    fn finalize_scalar(
466        &self,
467        _args: AggregateArgs<'_, Self::Options>,
468        partial: &Self::Partial,
469    ) -> VortexResult<Scalar> {
470        if partial.first_value.is_none() {
471            // Empty accumulator → return false.
472            return Ok(Scalar::bool(false, Nullability::NonNullable));
473        }
474        Ok(Scalar::bool(partial.is_constant, Nullability::NonNullable))
475    }
476}
477
478#[cfg(test)]
479mod tests {
480    use std::sync::LazyLock;
481
482    use rstest::rstest;
483    use vortex_buffer::Buffer;
484    use vortex_buffer::buffer;
485    use vortex_error::VortexResult;
486    use vortex_session::VortexSession;
487
488    use crate::IntoArray as _;
489    use crate::VortexSessionExecute;
490    use crate::aggregate_fn::Accumulator;
491    use crate::aggregate_fn::AggregateDTypes;
492    use crate::aggregate_fn::AggregateFnVTable;
493    use crate::aggregate_fn::DynAccumulator;
494    use crate::aggregate_fn::EmptyOptions;
495    use crate::aggregate_fn::fns::is_constant::IsConstant;
496    use crate::aggregate_fn::fns::is_constant::IsConstantPartial;
497    use crate::aggregate_fn::fns::is_constant::is_constant;
498    use crate::arrays::BoolArray;
499    use crate::arrays::ChunkedArray;
500    use crate::arrays::ConstantArray;
501    use crate::arrays::DecimalArray;
502    use crate::arrays::DictArray;
503    use crate::arrays::ListArray;
504    use crate::arrays::PrimitiveArray;
505    use crate::arrays::StructArray;
506    use crate::arrays::runend::RunEnd;
507    use crate::builders::MapBuilder;
508    use crate::dtype::DType;
509    use crate::dtype::DecimalDType;
510    use crate::dtype::FieldNames;
511    use crate::dtype::MapDType;
512    use crate::dtype::Nullability;
513    use crate::dtype::PType;
514    use crate::expr::stats::Stat;
515    use crate::scalar::Scalar;
516    use crate::validity::Validity;
517
518    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
519
520    type MapEntryFixture<'a> = (i32, Option<&'a str>);
521    type MapRowFixture<'a> = Option<Vec<MapEntryFixture<'a>>>;
522
523    fn map_array_from_rows(rows: &[MapRowFixture<'_>]) -> VortexResult<crate::ArrayRef> {
524        let map_dtype = MapDType::try_new(
525            DType::Primitive(PType::I32, Nullability::NonNullable),
526            DType::Utf8(Nullability::Nullable),
527            false,
528        )?;
529        let dtype = DType::Map(map_dtype.clone(), Nullability::Nullable);
530        let mut builder = MapBuilder::<u64, u64>::with_capacity_in(
531            map_dtype,
532            Nullability::Nullable,
533            rows.len(),
534            vortex_buffer::BufferAllocatorRef::static_ref(),
535        );
536
537        for row in rows {
538            let scalar = match row {
539                Some(entries) => {
540                    let entries = entries
541                        .iter()
542                        .map(|(key, value)| {
543                            let key = Scalar::primitive(*key, Nullability::NonNullable);
544                            let value = value.map_or_else(
545                                || Scalar::null(DType::Utf8(Nullability::Nullable)),
546                                |value| Scalar::utf8(value, Nullability::Nullable),
547                            );
548                            (key, value)
549                        })
550                        .collect::<Vec<_>>();
551                    Scalar::try_map(dtype.clone(), entries)?
552                }
553                None => Scalar::null(dtype.clone()),
554            };
555            builder.append_value(scalar.as_map())?;
556        }
557
558        Ok(builder.finish_into_map().into_array())
559    }
560
561    // Tests migrated from compute/is_constant.rs
562    #[test]
563    fn is_constant_min_max_no_nan() -> VortexResult<()> {
564        let mut ctx = SESSION.create_execution_ctx();
565
566        let arr = buffer![0, 1].into_array();
567        arr.statistics()
568            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
569        assert!(!is_constant(&arr, &mut ctx)?);
570
571        let arr = buffer![0, 0].into_array();
572        arr.statistics()
573            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
574        assert!(is_constant(&arr, &mut ctx)?);
575
576        let arr = PrimitiveArray::from_option_iter([Some(0), Some(0)]).into_array();
577        assert!(is_constant(&arr, &mut ctx)?);
578        Ok(())
579    }
580
581    #[test]
582    fn is_constant_min_max_with_nan() -> VortexResult<()> {
583        let mut ctx = SESSION.create_execution_ctx();
584
585        let arr = PrimitiveArray::from_iter([0.0, 0.0, f32::NAN]).into_array();
586        arr.statistics()
587            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
588        assert!(!is_constant(&arr, &mut ctx)?);
589
590        let arr =
591            PrimitiveArray::from_option_iter([Some(f32::NEG_INFINITY), Some(f32::NEG_INFINITY)])
592                .into_array();
593        arr.statistics()
594            .compute_all(&[Stat::Min, Stat::Max], &mut ctx)?;
595        assert!(is_constant(&arr, &mut ctx)?);
596        Ok(())
597    }
598
599    // Tests migrated from arrays/bool/compute/is_constant.rs
600    #[rstest]
601    #[case(vec![true], true)]
602    #[case(vec![false; 65], true)]
603    #[case({
604        let mut v = vec![true; 64];
605        v.push(false);
606        v
607    }, false)]
608    fn test_bool_is_constant(#[case] input: Vec<bool>, #[case] expected: bool) -> VortexResult<()> {
609        let array = BoolArray::from_iter(input);
610        let mut ctx = SESSION.create_execution_ctx();
611        assert_eq!(is_constant(&array.into_array(), &mut ctx)?, expected);
612        Ok(())
613    }
614
615    // Tests migrated from arrays/chunked/compute/is_constant.rs
616    #[test]
617    fn empty_chunk_is_constant() -> VortexResult<()> {
618        let chunked = ChunkedArray::try_new(
619            vec![
620                Buffer::<u8>::empty().into_array(),
621                Buffer::<u8>::empty().into_array(),
622                buffer![255u8, 255].into_array(),
623                Buffer::<u8>::empty().into_array(),
624                buffer![255u8, 255].into_array(),
625            ],
626            DType::Primitive(PType::U8, Nullability::NonNullable),
627        )?
628        .into_array();
629
630        let mut ctx = SESSION.create_execution_ctx();
631        assert!(is_constant(&chunked, &mut ctx)?);
632        Ok(())
633    }
634
635    // Tests migrated from arrays/decimal/compute/is_constant.rs
636    #[test]
637    fn test_decimal_is_constant() -> VortexResult<()> {
638        let mut ctx = SESSION.create_execution_ctx();
639
640        let array = DecimalArray::new(
641            buffer![0i128, 1i128, 2i128],
642            DecimalDType::new(19, 0),
643            Validity::NonNullable,
644        );
645        assert!(!is_constant(&array.into_array(), &mut ctx)?);
646
647        let array = DecimalArray::new(
648            buffer![100i128, 100i128, 100i128],
649            DecimalDType::new(19, 0),
650            Validity::NonNullable,
651        );
652        assert!(is_constant(&array.into_array(), &mut ctx)?);
653        Ok(())
654    }
655
656    // Tests migrated from arrays/list/compute/is_constant.rs
657    #[test]
658    fn test_is_constant_nested_list() -> VortexResult<()> {
659        let mut ctx = SESSION.create_execution_ctx();
660
661        let xs = ListArray::try_new(
662            buffer![0i32, 1, 0, 1].into_array(),
663            buffer![0u32, 2, 4].into_array(),
664            Validity::NonNullable,
665            &mut ctx,
666        )?;
667
668        let struct_of_lists = StructArray::try_new(
669            FieldNames::from(["xs"]),
670            vec![xs.into_array()],
671            2,
672            Validity::NonNullable,
673        )?;
674        assert!(is_constant(
675            &struct_of_lists.clone().into_array(),
676            &mut ctx
677        )?);
678        assert!(is_constant(&struct_of_lists.into_array(), &mut ctx)?);
679        Ok(())
680    }
681
682    #[rstest]
683    #[case(
684        // [1,2], [1, 2], [1, 2]
685        vec![1i32, 2, 1, 2, 1, 2],
686        vec![0u32, 2, 4, 6],
687        true
688    )]
689    #[case(
690        // [1, 2], [3], [4, 5]
691        vec![1i32, 2, 3, 4, 5],
692        vec![0u32, 2, 3, 5],
693        false
694    )]
695    #[case(
696        // [1, 2], [3, 4]
697        vec![1i32, 2, 3, 4],
698        vec![0u32, 2, 4],
699        false
700    )]
701    #[case(
702        // [], [], []
703        vec![],
704        vec![0u32, 0, 0, 0],
705        true
706    )]
707    fn test_list_is_constant(
708        #[case] elements: Vec<i32>,
709        #[case] offsets: Vec<u32>,
710        #[case] expected: bool,
711    ) -> VortexResult<()> {
712        let list_array = ListArray::try_new(
713            PrimitiveArray::from_iter(elements).into_array(),
714            PrimitiveArray::from_iter(offsets).into_array(),
715            Validity::NonNullable,
716            &mut SESSION.create_execution_ctx(),
717        )?;
718
719        let mut ctx = SESSION.create_execution_ctx();
720        assert_eq!(is_constant(&list_array.into_array(), &mut ctx)?, expected);
721        Ok(())
722    }
723
724    #[test]
725    fn test_list_is_constant_nested_lists() -> VortexResult<()> {
726        let mut ctx = SESSION.create_execution_ctx();
727        let inner_elements = buffer![1i32, 2, 1, 2].into_array();
728        let inner_offsets = buffer![0u32, 1, 2, 3, 4].into_array();
729        let inner_lists = ListArray::try_new(
730            inner_elements,
731            inner_offsets,
732            Validity::NonNullable,
733            &mut ctx,
734        )?;
735
736        let outer_offsets = buffer![0u32, 2, 4].into_array();
737        let outer_list = ListArray::try_new(
738            inner_lists.into_array(),
739            outer_offsets,
740            Validity::NonNullable,
741            &mut ctx,
742        )?;
743
744        let mut ctx = SESSION.create_execution_ctx();
745        // Both outer lists contain [[1], [2]], so should be constant
746        assert!(is_constant(&outer_list.into_array(), &mut ctx)?);
747        Ok(())
748    }
749
750    #[rstest]
751    #[case(
752        // 100 identical [1, 2] lists
753        [1i32, 2].repeat(100),
754        (0..101).map(|i| (i * 2) as u32).collect(),
755        true
756    )]
757    #[case(
758        // Difference after threshold: 64 identical [1, 2] + one [3, 4]
759        {
760            let mut elements = [1i32, 2].repeat(64);
761            elements.extend_from_slice(&[3, 4]);
762            elements
763        },
764        (0..66).map(|i| (i * 2) as u32).collect(),
765        false
766    )]
767    #[case(
768        // Difference in first 64: first 63 identical [1, 2] + one [3, 4] + rest identical [1, 2]
769        {
770            let mut elements = [1i32, 2].repeat(63);
771            elements.extend_from_slice(&[3, 4]);
772            elements.extend([1i32, 2].repeat(37));
773            elements
774        },
775        (0..101).map(|i| (i * 2) as u32).collect(),
776        false
777    )]
778    fn test_list_is_constant_with_threshold(
779        #[case] elements: Vec<i32>,
780        #[case] offsets: Vec<u32>,
781        #[case] expected: bool,
782    ) -> VortexResult<()> {
783        let list_array = ListArray::try_new(
784            PrimitiveArray::from_iter(elements).into_array(),
785            PrimitiveArray::from_iter(offsets).into_array(),
786            Validity::NonNullable,
787            &mut SESSION.create_execution_ctx(),
788        )?;
789
790        let mut ctx = SESSION.create_execution_ctx();
791        assert_eq!(is_constant(&list_array.into_array(), &mut ctx)?, expected);
792        Ok(())
793    }
794
795    #[test]
796    fn test_map_is_constant() -> VortexResult<()> {
797        let mut ctx = SESSION.create_execution_ctx();
798
799        let identical = map_array_from_rows(&[
800            Some(vec![(1, Some("one")), (2, None)]),
801            Some(vec![(1, Some("one")), (2, None)]),
802        ])?;
803        assert!(is_constant(&identical, &mut ctx)?);
804
805        let different = map_array_from_rows(&[
806            Some(vec![(1, Some("one")), (2, None)]),
807            Some(vec![(1, Some("one")), (3, None)]),
808        ])?;
809        assert!(!is_constant(&different, &mut ctx)?);
810
811        let all_null = map_array_from_rows(&[None, None])?;
812        assert!(is_constant(&all_null, &mut ctx)?);
813
814        Ok(())
815    }
816
817    #[test]
818    fn empty_constant_leaves_partial_empty() -> VortexResult<()> {
819        let mut ctx = SESSION.create_execution_ctx();
820        let array = ConstantArray::new(Scalar::from(99i32), 0).into_array();
821        let mut acc = Accumulator::try_new(IsConstant, EmptyOptions, array.dtype().clone())?;
822
823        acc.accumulate(&array, &mut ctx)?;
824
825        assert!(acc.partial_scalar()?.is_null());
826        Ok(())
827    }
828
829    /// Merging a non-constant partial into a materialized empty one must keep the false verdict
830    /// in the partial scalar rather than collapsing it to the empty state.
831    #[test]
832    fn non_constant_merged_into_empty_keeps_verdict() -> VortexResult<()> {
833        let mut ctx = SESSION.create_execution_ctx();
834        let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
835        let mut empty = Accumulator::try_new(IsConstant, EmptyOptions, dtype.clone())?;
836        let mut varying = Accumulator::try_new(IsConstant, EmptyOptions, dtype)?;
837
838        // An empty batch materializes the empty partial in place.
839        empty.accumulate(
840            &PrimitiveArray::new(Buffer::<i32>::empty(), Validity::NonNullable).into_array(),
841            &mut ctx,
842        )?;
843        varying.accumulate(&buffer![1i32, 2].into_array(), &mut ctx)?;
844        empty.merge_from(&mut varying)?;
845
846        assert!(!empty.partial_scalar()?.is_null());
847        assert_eq!(
848            empty.finish()?,
849            Scalar::bool(false, Nullability::NonNullable)
850        );
851        Ok(())
852    }
853
854    /// A non-constant verdict without an observed value is not the empty state.
855    #[test]
856    fn non_constant_partial_without_value_is_not_empty() -> VortexResult<()> {
857        let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
858        let owned = AggregateDTypes::try_new(&IsConstant, &EmptyOptions, dtype)?;
859        let args = owned.args(&EmptyOptions);
860        let partial = IsConstantPartial {
861            is_constant: false,
862            first_value: None,
863        };
864
865        let scalar = IsConstant.to_scalar(args, &partial)?;
866        assert!(!scalar.is_null());
867        let parsed = IsConstant.partial_from_scalar(args, &scalar)?;
868        assert_eq!(
869            IsConstant.finalize_scalar(args, &parsed)?,
870            Scalar::bool(false, Nullability::NonNullable)
871        );
872        Ok(())
873    }
874
875    #[rstest]
876    fn empty_batch_leaves_constant_partial_empty(
877        #[values("primitive", "dict", "runend")] encoding: &str,
878    ) -> VortexResult<()> {
879        let mut ctx = SESSION.create_execution_ctx();
880        let empty = match encoding {
881            "primitive" => Buffer::<i32>::empty().into_array(),
882            "dict" => DictArray::try_new(
883                Buffer::<u32>::empty().into_array(),
884                buffer![1i32].into_array(),
885            )?
886            .into_array(),
887            "runend" => RunEnd::encode(Buffer::<i32>::empty().into_array(), &mut ctx)?.into_array(),
888            _ => unreachable!(),
889        };
890        let mut acc = Accumulator::try_new(IsConstant, EmptyOptions, empty.dtype().clone())?;
891        acc.accumulate(&empty, &mut ctx)?;
892
893        assert!(acc.partial_scalar()?.is_null());
894        assert!(!is_constant(&empty, &mut ctx)?);
895
896        acc.accumulate(&buffer![1i32, 1].into_array(), &mut ctx)?;
897        acc.accumulate(&empty, &mut ctx)?;
898
899        assert_eq!(acc.finish()?, Scalar::bool(true, Nullability::NonNullable));
900        Ok(())
901    }
902}