Skip to main content

vortex_array/aggregate_fn/fns/min/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use vortex_error::VortexExpect;
5use vortex_error::VortexResult;
6use vortex_session::VortexSession;
7use vortex_session::registry::CachedId;
8
9use crate::ArrayRef;
10use crate::Columnar;
11use crate::ExecutionCtx;
12use crate::aggregate_fn::AggregateArgs;
13use crate::aggregate_fn::AggregateFnId;
14use crate::aggregate_fn::AggregateFnRef;
15use crate::aggregate_fn::AggregateFnSatisfaction;
16use crate::aggregate_fn::AggregateFnVTable;
17use crate::aggregate_fn::NumericalAggregateOpts;
18use crate::aggregate_fn::fns::bounded_min::BoundedMin;
19use crate::aggregate_fn::fns::min_max::MinMax;
20use crate::aggregate_fn::fns::min_max::columnar_min_max;
21use crate::aggregate_fn::fns::min_max::min_max;
22use crate::aggregate_fn::fns::min_max::nan_scalar;
23use crate::aggregate_fn::fns::min_max::scalar_is_nan;
24use crate::dtype::DType;
25use crate::expr::stats::Precision;
26use crate::expr::stats::Stat;
27use crate::expr::stats::StatsProvider;
28use crate::expr::stats::StatsProviderExt;
29use crate::partial_ord::partial_min;
30use crate::scalar::Scalar;
31
32/// Compute the minimum non-null value of an array.
33///
34/// NaN handling for float inputs is controlled by [`NumericalAggregateOpts`]: with `skip_nans` (the
35/// default) NaN values are ignored, otherwise any NaN value poisons the minimum to NaN.
36#[derive(Clone, Debug)]
37pub struct Min;
38
39/// Partial accumulator state for the minimum aggregate.
40pub struct MinPartial {
41    min: Option<Scalar>,
42}
43
44impl MinPartial {
45    fn merge(
46        &mut self,
47        args: AggregateArgs<'_, NumericalAggregateOpts>,
48        min: Scalar,
49    ) -> VortexResult<()> {
50        if min.is_null() {
51            return Ok(());
52        }
53
54        // NaN scalars are incomparable under `partial_min`; they poison the minimum when NaNs
55        // participate, and are dropped when they are skipped.
56        if scalar_is_nan(&min) || self.is_poisoned() {
57            if !args.options.skip_nans {
58                self.poison(args)?;
59            }
60            return Ok(());
61        }
62
63        self.min = Some(match self.min.take() {
64            Some(current) => partial_min(min, current).vortex_expect("incomparable min scalars"),
65            None => min,
66        });
67
68        Ok(())
69    }
70
71    fn poison(&mut self, args: AggregateArgs<'_, NumericalAggregateOpts>) -> VortexResult<()> {
72        self.min = Some(nan_scalar(args.dtype)?);
73
74        Ok(())
75    }
76
77    fn is_poisoned(&self) -> bool {
78        self.min.as_ref().is_some_and(scalar_is_nan)
79    }
80}
81
82impl AggregateFnVTable for Min {
83    type Options = NumericalAggregateOpts;
84    type Partial = MinPartial;
85
86    fn id(&self) -> AggregateFnId {
87        static ID: CachedId = CachedId::new("vortex.min");
88        *ID
89    }
90
91    fn serialize(&self, options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
92        Ok(Some(options.serialize()))
93    }
94
95    fn deserialize(
96        &self,
97        metadata: &[u8],
98        _session: &VortexSession,
99    ) -> VortexResult<Self::Options> {
100        NumericalAggregateOpts::deserialize(metadata)
101    }
102
103    fn return_dtype(&self, options: &Self::Options, input_dtype: &DType) -> Option<DType> {
104        MinMax
105            .return_dtype(options, input_dtype)
106            .map(|_| input_dtype.as_nullable())
107    }
108
109    fn can_satisfy(
110        &self,
111        options: &Self::Options,
112        requested: &AggregateFnRef,
113    ) -> AggregateFnSatisfaction {
114        if requested
115            .as_opt::<Self>()
116            .is_some_and(|other| other == options)
117        {
118            AggregateFnSatisfaction::Exact
119        } else if requested.is::<BoundedMin>() && options.skip_nans {
120            // A NaN-including minimum may be NaN, which is not a usable lower bound.
121            AggregateFnSatisfaction::Approximate
122        } else {
123            AggregateFnSatisfaction::No
124        }
125    }
126
127    fn partial_dtype(&self, options: &Self::Options, input_dtype: &DType) -> Option<DType> {
128        self.return_dtype(options, input_dtype)
129    }
130
131    fn empty_partial(
132        &self,
133        _args: AggregateArgs<'_, Self::Options>,
134    ) -> VortexResult<Self::Partial> {
135        Ok(MinPartial { min: None })
136    }
137
138    fn partial_from_scalar(
139        &self,
140        args: AggregateArgs<'_, Self::Options>,
141        scalar: &Scalar,
142    ) -> VortexResult<Self::Partial> {
143        let mut partial = MinPartial { min: None };
144        // `merge` normalizes the parsed scalar: nulls stay empty and NaNs poison or drop.
145        partial.merge(args, scalar.clone())?;
146        Ok(partial)
147    }
148
149    fn merge_partials(
150        &self,
151        args: AggregateArgs<'_, Self::Options>,
152        mut first: Self::Partial,
153        second: Self::Partial,
154    ) -> VortexResult<Self::Partial> {
155        if let Some(min) = second.min {
156            first.merge(args, min)?;
157        }
158        Ok(first)
159    }
160
161    fn to_scalar(
162        &self,
163        args: AggregateArgs<'_, Self::Options>,
164        partial: &Self::Partial,
165    ) -> VortexResult<Scalar> {
166        let dtype = args.dtype.as_nullable();
167        match &partial.min {
168            Some(min) => min.cast(&dtype),
169            None => Ok(Scalar::null(dtype)),
170        }
171    }
172
173    fn is_saturated(
174        &self,
175        _args: AggregateArgs<'_, Self::Options>,
176        partial: &Self::Partial,
177    ) -> bool {
178        // A poisoned NaN-including minimum is fully determined.
179        partial.is_poisoned()
180    }
181
182    fn try_accumulate(
183        &self,
184        args: AggregateArgs<'_, Self::Options>,
185        partial: &mut Self::Partial,
186        batch: &ArrayRef,
187        ctx: &mut ExecutionCtx,
188    ) -> VortexResult<bool> {
189        if args.options.skip_nans || !args.dtype.is_float() {
190            // `min_max` computes both extrema in one pass and caches both on `batch`, so a
191            // `Max` over the same batch reads the cached value instead of a second scan.
192            if let Some(result) = min_max(batch, ctx, *args.options)? {
193                partial.merge(args, result.min)?;
194            }
195            return Ok(true);
196        }
197
198        match batch.statistics().get_as::<u64>(Stat::NaNCount) {
199            Precision::Exact(0) => {
200                // NaN-free batch: the cached NaN-skipping minimum (if any) is valid. `to_scalar`
201                // re-casts to the result dtype, so the cached scalar can merge as-is.
202                if let Some(min) = batch.statistics().get(Stat::Min).as_exact() {
203                    partial.merge(args, min)?;
204                    return Ok(true);
205                }
206                Ok(false)
207            }
208            Precision::Exact(_) => {
209                partial.poison(args)?;
210                Ok(true)
211            }
212            _ => Ok(false),
213        }
214    }
215
216    fn accumulate(
217        &self,
218        args: AggregateArgs<'_, Self::Options>,
219        partial: &mut Self::Partial,
220        batch: &Columnar,
221        ctx: &mut ExecutionCtx,
222    ) -> VortexResult<()> {
223        // Delegate to the existing min_max implementation for now. A dedicated min aggregate
224        // would avoid computing max when only min is needed.
225        if let Some(result) = columnar_min_max(batch, *args.options, ctx)? {
226            partial.merge(args, result.min)?;
227        }
228        Ok(())
229    }
230
231    fn finalize(
232        &self,
233        _args: AggregateArgs<'_, Self::Options>,
234        partials: ArrayRef,
235    ) -> VortexResult<ArrayRef> {
236        Ok(partials)
237    }
238
239    fn finalize_scalar(
240        &self,
241        args: AggregateArgs<'_, Self::Options>,
242        partial: &Self::Partial,
243    ) -> VortexResult<Scalar> {
244        self.to_scalar(args, partial)
245    }
246}
247
248#[cfg(test)]
249mod tests {
250    use std::sync::LazyLock;
251
252    use vortex_buffer::buffer;
253    use vortex_error::VortexResult;
254    use vortex_session::VortexSession;
255
256    use crate::IntoArray as _;
257    use crate::VortexSessionExecute;
258    use crate::aggregate_fn::Accumulator;
259    use crate::aggregate_fn::DynAccumulator;
260    use crate::aggregate_fn::NumericalAggregateOpts;
261    use crate::aggregate_fn::fns::min::Min;
262    use crate::arrays::PrimitiveArray;
263    use crate::dtype::DType;
264    use crate::dtype::Nullability;
265    use crate::dtype::PType;
266    use crate::expr::stats::Precision;
267    use crate::expr::stats::Stat;
268    use crate::scalar::Scalar;
269    use crate::scalar::ScalarValue;
270    use crate::validity::Validity;
271
272    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
273
274    #[test]
275    fn min_aggregate_fn() -> VortexResult<()> {
276        let mut ctx = SESSION.create_execution_ctx();
277        let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
278        let mut acc = Accumulator::try_new(Min, NumericalAggregateOpts::default(), dtype)?;
279
280        let batch1 = PrimitiveArray::new(buffer![10i32, 20, 5], Validity::NonNullable).into_array();
281        acc.accumulate(&batch1, &mut ctx)?;
282
283        let batch2 = PrimitiveArray::new(buffer![3i32, 25], Validity::NonNullable).into_array();
284        acc.accumulate(&batch2, &mut ctx)?;
285
286        assert_eq!(
287            acc.finish()?,
288            Scalar::primitive(3i32, Nullability::Nullable)
289        );
290        Ok(())
291    }
292
293    #[test]
294    fn min_empty_group_returns_null() -> VortexResult<()> {
295        let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
296        let mut acc = Accumulator::try_new(Min, NumericalAggregateOpts::default(), dtype)?;
297
298        assert_eq!(
299            acc.finish()?,
300            Scalar::null(DType::Primitive(PType::I32, Nullability::Nullable))
301        );
302        Ok(())
303    }
304
305    #[test]
306    fn min_with_nan_not_skipping() -> VortexResult<()> {
307        let mut ctx = SESSION.create_execution_ctx();
308        let dtype = DType::Primitive(PType::F64, Nullability::NonNullable);
309        let mut acc = Accumulator::try_new(Min, NumericalAggregateOpts::include_nans(), dtype)?;
310
311        let batch = PrimitiveArray::new(buffer![1.0f64, f64::NAN, -5.0], Validity::NonNullable)
312            .into_array();
313        acc.accumulate(&batch, &mut ctx)?;
314        assert!(acc.is_saturated());
315
316        let result = acc.finish()?;
317        assert!(
318            result
319                .as_primitive()
320                .typed_value::<f64>()
321                .is_some_and(f64::is_nan)
322        );
323        Ok(())
324    }
325
326    #[test]
327    fn min_not_skipping_with_exact_nan_count_stat() -> VortexResult<()> {
328        let mut ctx = SESSION.create_execution_ctx();
329        // The exact NaN count agrees with the batch; including NaNs must poison the result.
330        let batch =
331            PrimitiveArray::new(buffer![1.0f64, 2.0, f64::NAN], Validity::NonNullable).into_array();
332        batch
333            .statistics()
334            .set(Stat::NaNCount, Precision::Exact(ScalarValue::from(1u64)));
335        let mut acc = Accumulator::try_new(
336            Min,
337            NumericalAggregateOpts::include_nans(),
338            batch.dtype().clone(),
339        )?;
340        acc.accumulate(&batch, &mut ctx)?;
341        let result = acc.finish()?;
342        assert!(
343            result
344                .as_primitive()
345                .typed_value::<f64>()
346                .is_some_and(f64::is_nan)
347        );
348        Ok(())
349    }
350
351    #[test]
352    fn min_nan_including_nullable_cached_stat() -> VortexResult<()> {
353        // A nullable float array's cached Min stat is reconstructed as a nullable scalar. The
354        // NaN-including shortcircuit merges it as-is; `to_scalar` re-casts to the result dtype.
355        let mut ctx = SESSION.create_execution_ctx();
356        let array =
357            PrimitiveArray::from_option_iter([Some(1.0f64), Some(2.0), Some(3.0)]).into_array();
358        array
359            .statistics()
360            .set(Stat::NaNCount, Precision::Exact(ScalarValue::from(0u64)));
361        array
362            .statistics()
363            .set(Stat::Min, Precision::Exact(ScalarValue::from(1.0f64)));
364        let mut acc = Accumulator::try_new(
365            Min,
366            NumericalAggregateOpts::include_nans(),
367            array.dtype().clone(),
368        )?;
369        acc.accumulate(&array, &mut ctx)?;
370        assert_eq!(
371            acc.finish()?,
372            Scalar::primitive(1.0f64, Nullability::Nullable)
373        );
374        Ok(())
375    }
376
377    #[test]
378    fn min_casts_nonnullable_legacy_stat_to_nullable_partial() -> VortexResult<()> {
379        let mut ctx = SESSION.create_execution_ctx();
380        let batch = PrimitiveArray::new(buffer![10i32, 20], Validity::NonNullable).into_array();
381        batch
382            .statistics()
383            .set(Stat::Min, Precision::Exact(ScalarValue::from(10i32)));
384        let mut acc = Accumulator::try_new(
385            Min,
386            NumericalAggregateOpts::default(),
387            batch.dtype().clone(),
388        )?;
389
390        acc.accumulate(&batch, &mut ctx)?;
391
392        assert_eq!(
393            acc.finish()?,
394            Scalar::primitive(10i32, Nullability::Nullable)
395        );
396        Ok(())
397    }
398}