Skip to main content

vortex_array/arrays/scalar_fn/vtable/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3mod operations;
4mod validity;
5
6use std::hash::Hash;
7use std::hash::Hasher;
8use std::marker::PhantomData;
9use std::ops::Deref;
10
11use itertools::Itertools;
12use validity::ValidityArray;
13use vortex_error::VortexResult;
14use vortex_error::vortex_bail;
15use vortex_error::vortex_ensure;
16use vortex_error::vortex_ensure_eq;
17use vortex_error::vortex_panic;
18use vortex_session::VortexSession;
19
20use crate::ArrayEq;
21use crate::ArrayHash;
22use crate::ArrayRef;
23use crate::EqMode;
24use crate::IntoArray;
25use crate::array::Array;
26use crate::array::ArrayId;
27use crate::array::ArrayParts;
28use crate::array::ArrayView;
29use crate::array::VTable;
30use crate::array::ValidityVTable;
31use crate::array::with_empty_buffers;
32use crate::arrays::scalar_fn::array::ScalarFnArrayExt;
33use crate::arrays::scalar_fn::array::ScalarFnData;
34use crate::arrays::scalar_fn::rules::PARENT_RULES;
35use crate::arrays::scalar_fn::rules::RULES;
36use crate::buffer::BufferHandle;
37use crate::dtype::DType;
38use crate::executor::ExecutionCtx;
39use crate::executor::ExecutionResult;
40use crate::matcher::Matcher;
41use crate::scalar_fn;
42use crate::scalar_fn::ArrayReduceNode;
43use crate::scalar_fn::ReduceNode;
44use crate::scalar_fn::ReduceNodeValidity;
45use crate::scalar_fn::ScalarFnExecutionStep;
46use crate::scalar_fn::ScalarFnId;
47use crate::scalar_fn::VecExecutionArgs;
48use crate::serde::ArrayChildren;
49use crate::validity::Validity;
50
51/// A [`ScalarFn`]-encoded Vortex array.
52pub type ScalarFnArray = Array<ScalarFn>;
53
54#[derive(Clone, Debug)]
55pub struct ScalarFn {
56    pub(super) id: ScalarFnId,
57}
58
59impl ArrayHash for ScalarFnData {
60    fn array_hash<H: Hasher>(&self, state: &mut H, _accuracy: EqMode) {
61        self.scalar_fn().hash(state);
62    }
63}
64
65impl ArrayEq for ScalarFnData {
66    fn array_eq(&self, other: &Self, _accuracy: EqMode) -> bool {
67        self.scalar_fn() == other.scalar_fn()
68    }
69}
70
71impl VTable for ScalarFn {
72    type TypedArrayData = ScalarFnData;
73    type OperationsVTable = Self;
74    type ValidityVTable = Self;
75
76    fn id(&self) -> ArrayId {
77        self.id
78    }
79
80    fn validate(
81        &self,
82        data: &ScalarFnData,
83        dtype: &DType,
84        len: usize,
85        slots: &[Option<ArrayRef>],
86    ) -> VortexResult<()> {
87        let scalar_fn = data.scalar_fn();
88        vortex_ensure_eq!(
89            scalar_fn.id(),
90            self.id,
91            "ScalarFnArray data scalar_fn does not match vtable",
92        );
93
94        Array::<ScalarFn>::validate_not_literal(scalar_fn)?;
95
96        let missing_children = slots.iter().filter(|slot| slot.is_none()).count();
97        vortex_ensure_eq!(
98            missing_children,
99            0,
100            "ScalarFnArray requires every child slot to be present",
101        );
102
103        let arity = scalar_fn.signature().arity();
104        vortex_ensure!(
105            arity.matches(slots.len()),
106            "ScalarFnArray requires {arity} children, got {}",
107            slots.len()
108        );
109        vortex_ensure!(
110            slots.iter().flatten().all(|c| c.len() == len),
111            "All child arrays must have the same length as the scalar function array"
112        );
113
114        let child_dtypes = slots
115            .iter()
116            .flatten()
117            .map(|c| c.dtype().clone())
118            .collect_vec();
119        vortex_ensure_eq!(
120            scalar_fn.return_dtype(&child_dtypes)?,
121            *dtype,
122            "ScalarFnArray dtype does not match scalar function return dtype",
123        );
124        Ok(())
125    }
126
127    fn nbuffers(_array: ArrayView<'_, Self>) -> usize {
128        0
129    }
130
131    fn buffer(_array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
132        vortex_panic!("ScalarFnArray buffer index {idx} out of bounds")
133    }
134
135    fn buffer_name(_array: ArrayView<'_, Self>, _idx: usize) -> Option<String> {
136        None
137    }
138
139    fn with_buffers(
140        &self,
141        array: ArrayView<'_, Self>,
142        buffers: &[BufferHandle],
143    ) -> VortexResult<ArrayParts<Self>> {
144        with_empty_buffers(self, array, buffers)
145    }
146
147    fn serialize(
148        _array: ArrayView<'_, Self>,
149        _session: &VortexSession,
150    ) -> VortexResult<Option<Vec<u8>>> {
151        // Not supported
152        Ok(None)
153    }
154
155    fn deserialize(
156        &self,
157        _dtype: &DType,
158        _len: usize,
159        _metadata: &[u8],
160        _buffers: &[BufferHandle],
161        _children: &dyn ArrayChildren,
162        _session: &VortexSession,
163    ) -> VortexResult<ArrayParts<Self>> {
164        vortex_bail!("Deserialization of ScalarFnVTable metadata is not supported");
165    }
166
167    fn slot_name(array: ArrayView<'_, Self>, idx: usize) -> String {
168        array
169            .scalar_fn()
170            .signature()
171            .child_name(idx)
172            .as_ref()
173            .to_string()
174    }
175
176    fn execute(array: Array<Self>, ctx: &mut ExecutionCtx) -> VortexResult<ExecutionResult> {
177        let args = VecExecutionArgs::new(array.children(), array.len());
178        match array.scalar_fn().execute_step(&args, ctx)?.into_step() {
179            ScalarFnExecutionStep::Done(result) => Ok(ExecutionResult::done(result)),
180            ScalarFnExecutionStep::ExecuteInput(idx, done) => Ok(
181                ExecutionResult::execute_slot_until(array.into_array(), idx, done),
182            ),
183        }
184    }
185
186    fn reduce(array: ArrayView<'_, Self>) -> VortexResult<Option<ArrayRef>> {
187        RULES.evaluate(array)
188    }
189
190    fn reduce_parent(
191        array: ArrayView<'_, Self>,
192        parent: &ArrayRef,
193        child_idx: usize,
194    ) -> VortexResult<Option<ArrayRef>> {
195        PARENT_RULES.evaluate(array, parent, child_idx)
196    }
197}
198
199/// A matcher that matches any scalar function expression.
200#[derive(Debug)]
201pub struct AnyScalarFn;
202impl Matcher for AnyScalarFn {
203    type Match<'a> = ArrayView<'a, ScalarFn>;
204
205    fn matches(array: &ArrayRef) -> bool {
206        array.is::<ScalarFn>()
207    }
208
209    fn try_match(array: &ArrayRef) -> Option<Self::Match<'_>> {
210        array.as_opt::<ScalarFn>()
211    }
212}
213
214/// A matcher that matches a specific scalar function expression.
215#[derive(Debug, Default)]
216pub struct ExactScalarFn<F: scalar_fn::ScalarFnVTable>(PhantomData<F>);
217
218impl<F: scalar_fn::ScalarFnVTable> Matcher for ExactScalarFn<F> {
219    type Match<'a> = ScalarFnArrayView<'a, F>;
220
221    fn matches(array: &ArrayRef) -> bool {
222        if let Some(scalar_fn_array) = array.as_opt::<ScalarFn>() {
223            scalar_fn_array.data().scalar_fn().is::<F>()
224        } else {
225            false
226        }
227    }
228
229    fn try_match(array: &ArrayRef) -> Option<Self::Match<'_>> {
230        let scalar_fn_array = array.as_opt::<ScalarFn>()?;
231        let scalar_fn_data = scalar_fn_array.data();
232        let scalar_fn = scalar_fn_data.scalar_fn().downcast_ref::<F>()?;
233        Some(ScalarFnArrayView {
234            array,
235            vtable: scalar_fn.vtable(),
236            options: scalar_fn.options(),
237        })
238    }
239}
240
241pub struct ScalarFnArrayView<'a, F: scalar_fn::ScalarFnVTable> {
242    array: &'a ArrayRef,
243    pub vtable: &'a F,
244    pub options: &'a F::Options,
245}
246
247impl<F: scalar_fn::ScalarFnVTable> Deref for ScalarFnArrayView<'_, F> {
248    type Target = ArrayRef;
249
250    fn deref(&self) -> &Self::Target {
251        self.array
252    }
253}
254
255impl ValidityVTable<ScalarFn> for ScalarFn {
256    fn validity(view: ArrayView<'_, ScalarFn>) -> VortexResult<Validity> {
257        let node = ArrayReduceNode::new(view.as_ref());
258        Ok(Validity::Array(match node.validity()? {
259            ReduceNodeValidity::Reduced(reduced) => reduced.into_array(),
260            ReduceNodeValidity::Irreducible => ValidityArray::new(node.into_array()).into_array(),
261        }))
262    }
263}