vortex_array/aggregate_fn/fns/first/
mod.rs1use vortex_error::VortexResult;
5use vortex_session::VortexSession;
6use vortex_session::registry::CachedId;
7
8use crate::ArrayRef;
9use crate::Columnar;
10use crate::ExecutionCtx;
11use crate::aggregate_fn::Accumulator;
12use crate::aggregate_fn::AggregateArgs;
13use crate::aggregate_fn::AggregateFnId;
14use crate::aggregate_fn::AggregateFnVTable;
15use crate::aggregate_fn::DynAccumulator;
16use crate::aggregate_fn::EmptyOptions;
17use crate::dtype::DType;
18use crate::scalar::Scalar;
19
20pub fn first(array: &ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<Scalar> {
24 let mut acc = Accumulator::try_new(First, EmptyOptions, array.dtype().clone())?;
25 acc.accumulate(array, ctx)?;
26 acc.finish()
27}
28
29#[derive(Clone, Debug)]
31pub struct First;
32
33pub struct FirstPartial {
35 value: Option<Scalar>,
37}
38
39impl AggregateFnVTable for First {
40 type Options = EmptyOptions;
41 type Partial = FirstPartial;
42
43 fn id(&self) -> AggregateFnId {
44 static ID: CachedId = CachedId::new("vortex.first");
45 *ID
46 }
47
48 fn serialize(&self, _options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
49 Ok(Some(vec![]))
50 }
51
52 fn deserialize(
53 &self,
54 _metadata: &[u8],
55 _session: &VortexSession,
56 ) -> VortexResult<Self::Options> {
57 Ok(EmptyOptions)
58 }
59
60 fn return_dtype(&self, _options: &Self::Options, input_dtype: &DType) -> Option<DType> {
61 Some(input_dtype.as_nullable())
62 }
63
64 fn partial_dtype(&self, options: &Self::Options, input_dtype: &DType) -> Option<DType> {
65 self.return_dtype(options, input_dtype)
66 }
67
68 fn empty_partial(
69 &self,
70 _args: AggregateArgs<'_, Self::Options>,
71 ) -> VortexResult<Self::Partial> {
72 Ok(FirstPartial { value: None })
73 }
74
75 fn partial_from_scalar(
76 &self,
77 _args: AggregateArgs<'_, Self::Options>,
78 scalar: &Scalar,
79 ) -> VortexResult<Self::Partial> {
80 Ok(FirstPartial {
82 value: (!scalar.is_null()).then(|| scalar.clone()),
83 })
84 }
85
86 fn merge_partials(
87 &self,
88 _args: AggregateArgs<'_, Self::Options>,
89 first: Self::Partial,
90 second: Self::Partial,
91 ) -> VortexResult<Self::Partial> {
92 Ok(FirstPartial {
94 value: first.value.or(second.value),
95 })
96 }
97
98 fn to_scalar(
99 &self,
100 args: AggregateArgs<'_, Self::Options>,
101 partial: &Self::Partial,
102 ) -> VortexResult<Scalar> {
103 Ok(match &partial.value {
104 Some(v) => v.clone(),
105 None => Scalar::null(args.return_dtype.clone()),
106 })
107 }
108
109 #[inline]
110 fn is_saturated(
111 &self,
112 _args: AggregateArgs<'_, Self::Options>,
113 partial: &Self::Partial,
114 ) -> bool {
115 partial.value.is_some()
116 }
117
118 fn try_accumulate(
119 &self,
120 _args: AggregateArgs<'_, Self::Options>,
121 partial: &mut Self::Partial,
122 batch: &ArrayRef,
123 ctx: &mut ExecutionCtx,
124 ) -> VortexResult<bool> {
125 if partial.value.is_some() {
126 return Ok(true);
127 }
128 if let Some(idx) = batch.validity()?.execute_mask(batch.len(), ctx)?.first() {
129 let scalar = batch.execute_scalar(idx, ctx)?;
130 partial.value = Some(scalar.into_nullable());
131 }
132 Ok(true)
133 }
134
135 fn accumulate(
136 &self,
137 _args: AggregateArgs<'_, Self::Options>,
138 _partial: &mut Self::Partial,
139 _batch: &Columnar,
140 _ctx: &mut ExecutionCtx,
141 ) -> VortexResult<()> {
142 unreachable!("First::try_accumulate handles all arrays")
143 }
144
145 fn finalize(
146 &self,
147 _args: AggregateArgs<'_, Self::Options>,
148 partials: ArrayRef,
149 ) -> VortexResult<ArrayRef> {
150 Ok(partials)
151 }
152
153 fn finalize_scalar(
154 &self,
155 args: AggregateArgs<'_, Self::Options>,
156 partial: &Self::Partial,
157 ) -> VortexResult<Scalar> {
158 self.to_scalar(args, partial)
159 }
160}
161
162#[cfg(test)]
163mod tests {
164 use std::sync::LazyLock;
165
166 use vortex_buffer::buffer;
167 use vortex_error::VortexResult;
168 use vortex_session::VortexSession;
169
170 use crate::IntoArray;
171 use crate::VortexSessionExecute;
172 use crate::aggregate_fn::Accumulator;
173 use crate::aggregate_fn::AggregateDTypes;
174 use crate::aggregate_fn::AggregateFnVTable;
175 use crate::aggregate_fn::DynAccumulator;
176 use crate::aggregate_fn::EmptyOptions;
177 use crate::aggregate_fn::fns::first::First;
178 use crate::aggregate_fn::fns::first::first;
179 use crate::arrays::ChunkedArray;
180 use crate::arrays::ConstantArray;
181 use crate::arrays::PrimitiveArray;
182 use crate::arrays::VarBinArray;
183 use crate::dtype::DType;
184 use crate::dtype::Nullability;
185 use crate::dtype::Nullability::Nullable;
186 use crate::dtype::PType;
187 use crate::scalar::Scalar;
188 use crate::validity::Validity;
189
190 static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
191
192 #[test]
193 fn first_non_null() -> VortexResult<()> {
194 let array = PrimitiveArray::new(buffer![10i32, 20, 30], Validity::NonNullable).into_array();
195 let mut ctx = SESSION.create_execution_ctx();
196 assert_eq!(first(&array, &mut ctx)?, Scalar::primitive(10i32, Nullable));
197 Ok(())
198 }
199
200 #[test]
201 fn first_skips_leading_nulls() -> VortexResult<()> {
202 let array =
203 PrimitiveArray::from_option_iter([None, None, Some(7i32), Some(8)]).into_array();
204 let mut ctx = SESSION.create_execution_ctx();
205 assert_eq!(first(&array, &mut ctx)?, Scalar::primitive(7i32, Nullable));
206 Ok(())
207 }
208
209 #[test]
210 fn first_all_null() -> VortexResult<()> {
211 let array = PrimitiveArray::from_option_iter::<i32, _>([None, None, None]).into_array();
212 let mut ctx = SESSION.create_execution_ctx();
213 let dtype = DType::Primitive(PType::I32, Nullable);
214 assert_eq!(first(&array, &mut ctx)?, Scalar::null(dtype));
215 Ok(())
216 }
217
218 #[test]
219 fn first_empty() -> VortexResult<()> {
220 let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
221 let mut acc = Accumulator::try_new(First, EmptyOptions, dtype)?;
222 let result = acc.finish()?;
223 assert_eq!(result, Scalar::null(DType::Primitive(PType::I32, Nullable)));
224 Ok(())
225 }
226
227 #[test]
228 fn first_constant() -> VortexResult<()> {
229 let array = ConstantArray::new(42i32, 10).into_array();
230 let mut ctx = SESSION.create_execution_ctx();
231 assert_eq!(first(&array, &mut ctx)?, Scalar::primitive(42i32, Nullable));
232 Ok(())
233 }
234
235 #[test]
236 fn first_constant_null() -> VortexResult<()> {
237 let dtype = DType::Primitive(PType::I32, Nullable);
238 let array = ConstantArray::new(Scalar::null(dtype.clone()), 10).into_array();
239 let mut ctx = SESSION.create_execution_ctx();
240 assert_eq!(first(&array, &mut ctx)?, Scalar::null(dtype));
241 Ok(())
242 }
243
244 #[test]
245 fn first_varbin() -> VortexResult<()> {
246 let array = VarBinArray::from_iter(
247 vec![None, Some("hello"), Some("world")],
248 DType::Utf8(Nullable),
249 )
250 .into_array();
251 let mut ctx = SESSION.create_execution_ctx();
252 assert_eq!(first(&array, &mut ctx)?, Scalar::utf8("hello", Nullable));
253 Ok(())
254 }
255
256 #[test]
257 fn first_multi_batch_picks_earliest_non_null() -> VortexResult<()> {
258 let mut ctx = SESSION.create_execution_ctx();
259 let dtype = DType::Primitive(PType::I32, Nullable);
260 let mut acc = Accumulator::try_new(First, EmptyOptions, dtype)?;
261
262 let batch1 = PrimitiveArray::from_option_iter::<i32, _>([None, None]).into_array();
264 acc.accumulate(&batch1, &mut ctx)?;
265 assert!(!acc.is_saturated());
266
267 let batch2 = PrimitiveArray::from_option_iter([None, Some(99i32), Some(100)]).into_array();
269 acc.accumulate(&batch2, &mut ctx)?;
270 assert!(acc.is_saturated());
271
272 let batch3 = PrimitiveArray::from_option_iter([Some(1i32)]).into_array();
274 acc.accumulate(&batch3, &mut ctx)?;
275
276 let result = acc.finish()?;
277 assert_eq!(result, Scalar::primitive(99i32, Nullable));
278 Ok(())
279 }
280
281 #[test]
282 fn first_finish_resets_state() -> VortexResult<()> {
283 let mut ctx = SESSION.create_execution_ctx();
284 let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
285 let mut acc = Accumulator::try_new(First, EmptyOptions, dtype)?;
286
287 let batch1 = PrimitiveArray::new(buffer![10i32, 20], Validity::NonNullable).into_array();
288 acc.accumulate(&batch1, &mut ctx)?;
289 assert_eq!(acc.finish()?, Scalar::primitive(10i32, Nullable));
290
291 let batch2 = PrimitiveArray::new(buffer![3i32, 6, 9], Validity::NonNullable).into_array();
292 acc.accumulate(&batch2, &mut ctx)?;
293 assert_eq!(acc.finish()?, Scalar::primitive(3i32, Nullable));
294 Ok(())
295 }
296
297 #[test]
298 fn first_state_merge() -> VortexResult<()> {
299 let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
300 let owned = AggregateDTypes::try_new(&First, &EmptyOptions, dtype)?;
301 let args = owned.args(&EmptyOptions);
302 let partial_of =
303 |value: i32| First.partial_from_scalar(args, &Scalar::primitive(value, Nullable));
304
305 let empty = First.empty_partial(args)?;
306 assert!(!First.is_saturated(args, &empty));
307
308 let five = partial_of(5)?;
310 let seven = partial_of(7)?;
311 let merge = |first, second| First.merge_partials(args, first, second);
312 let state = merge(merge(empty, five)?, seven)?;
313 assert!(First.is_saturated(args, &state));
314 assert_eq!(
315 First.to_scalar(args, &state)?,
316 Scalar::primitive(5i32, Nullable)
317 );
318 Ok(())
319 }
320
321 #[test]
322 fn first_chunked() -> VortexResult<()> {
323 let chunk1 = PrimitiveArray::from_option_iter::<i32, _>([None, None]);
324 let chunk2 = PrimitiveArray::from_option_iter([None, Some(42i32), Some(100)]);
325 let dtype = chunk1.dtype().clone();
326 let chunked = ChunkedArray::try_new(vec![chunk1.into_array(), chunk2.into_array()], dtype)?;
327 let mut ctx = SESSION.create_execution_ctx();
328 assert_eq!(
329 first(&chunked.into_array(), &mut ctx)?,
330 Scalar::primitive(42i32, Nullable)
331 );
332 Ok(())
333 }
334}