vortex_array/scalar_fn/fns/mask/
kernel.rs1use vortex_error::VortexResult;
7use vortex_error::vortex_err;
8
9use crate::ArrayRef;
10use crate::ExecutionCtx;
11use crate::array::ArrayView;
12use crate::array::VTable;
13use crate::arrays::Bool;
14use crate::arrays::Constant;
15use crate::arrays::scalar_fn::ExactScalarFn;
16use crate::arrays::scalar_fn::ScalarFnArrayView;
17use crate::kernel::ExecuteParentKernel;
18use crate::optimizer::rules::ArrayParentReduceRule;
19use crate::scalar_fn::fns::mask::Mask as MaskExpr;
20
21pub trait MaskReduce: VTable {
33 const VALIDITY_IS_METADATA_ONLY: bool = false;
38
39 fn mask(array: ArrayView<'_, Self>, mask: &ArrayRef) -> VortexResult<Option<ArrayRef>>;
40}
41
42pub trait MaskKernel: VTable {
54 fn mask(
55 array: ArrayView<'_, Self>,
56 mask: &ArrayRef,
57 ctx: &mut ExecutionCtx,
58 ) -> VortexResult<Option<ArrayRef>>;
59}
60
61#[derive(Default, Debug)]
63pub struct MaskReduceAdaptor<V>(pub V);
64
65impl<V> ArrayParentReduceRule<V> for MaskReduceAdaptor<V>
66where
67 V: MaskReduce,
68{
69 type Parent = ExactScalarFn<MaskExpr>;
70
71 fn reduce_parent(
72 &self,
73 array: ArrayView<'_, V>,
74 parent: ScalarFnArrayView<'_, MaskExpr>,
75 child_idx: usize,
76 ) -> VortexResult<Option<ArrayRef>> {
77 if child_idx != 0 {
79 return Ok(None);
80 }
81
82 let parent_ref: ArrayRef = (*parent).clone();
83 let mask_child = parent_ref
84 .nth_child(1)
85 .ok_or_else(|| vortex_err!("Mask expression must have 2 children"))?;
86
87 if mask_child.as_opt::<Bool>().is_none() && mask_child.as_opt::<Constant>().is_none() {
88 let can_attach_mask =
89 V::VALIDITY_IS_METADATA_ONLY && array.validity()?.definitely_no_nulls();
90
91 if !can_attach_mask {
92 return Ok(None);
93 }
94 }
95
96 <V as MaskReduce>::mask(array, mask_child)
97 }
98}
99
100#[derive(Default, Debug)]
102pub struct MaskExecuteAdaptor<V>(pub V);
103
104impl<V> ExecuteParentKernel<V> for MaskExecuteAdaptor<V>
105where
106 V: MaskKernel,
107{
108 type Parent = ExactScalarFn<MaskExpr>;
109
110 fn execute_parent(
111 &self,
112 array: ArrayView<'_, V>,
113 parent: ScalarFnArrayView<'_, MaskExpr>,
114 child_idx: usize,
115 ctx: &mut ExecutionCtx,
116 ) -> VortexResult<Option<ArrayRef>> {
117 if child_idx != 0 {
119 return Ok(None);
120 }
121 let mask_child = parent
122 .nth_child(1)
123 .ok_or_else(|| vortex_err!("Mask expression must have 2 children"))?;
124 <V as MaskKernel>::mask(array, mask_child, ctx)
125 }
126}
127
128#[cfg(test)]
129mod tests {
130 use std::sync::LazyLock;
131
132 use rstest::rstest;
133 use vortex_buffer::buffer;
134 use vortex_error::VortexResult;
135 use vortex_session::VortexSession;
136
137 use crate::ArrayEq;
138 use crate::ArrayRef;
139 use crate::EqMode;
140 use crate::IntoArray;
141 use crate::arrays::BoolArray;
142 use crate::arrays::ConstantArray;
143 use crate::arrays::Primitive;
144 use crate::arrays::PrimitiveArray;
145 use crate::arrays::ScalarFn;
146 use crate::arrays::scalar_fn::ExactScalarFn;
147 use crate::assert_arrays_eq;
148 use crate::builtins::ArrayBuiltins;
149 use crate::dtype::Nullability;
150 use crate::executor::VortexSessionExecute;
151 use crate::optimizer::ArrayOptimizer;
152 use crate::scalar::Scalar;
153 use crate::scalar_fn::fns::binary::Binary;
154 use crate::scalar_fn::fns::mask::Mask as MaskExpr;
155 use crate::scalar_fn::fns::operators::Operator;
156 use crate::validity::Validity;
157
158 static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
159
160 fn lazy_mask() -> VortexResult<ArrayRef> {
161 Binary::try_new(
162 BoolArray::from_iter([true, true, false]).into_array(),
163 BoolArray::from_iter([true, false, true]).into_array(),
164 Operator::And,
165 )
166 .map(IntoArray::into_array)
167 }
168
169 #[rstest]
170 #[case::non_nullable(Validity::NonNullable)]
171 #[case::all_valid(Validity::AllValid)]
172 fn all_valid_input_attaches_lazy_mask(#[case] validity: Validity) -> VortexResult<()> {
173 let input = PrimitiveArray::new(buffer![1i32, 2, 3], validity);
174 let mask = lazy_mask()?;
175 let output = input.clone().into_array().mask(mask.clone())?;
176 let primitive = output.as_::<Primitive>();
177
178 assert!(
179 primitive
180 .buffer_handle()
181 .array_eq(input.buffer_handle(), EqMode::Ptr)
182 );
183 assert_eq!(output.dtype(), &input.dtype().as_nullable());
184 assert_eq!(output.len(), input.len());
185 let Validity::Array(validity) = output.validity()? else {
186 panic!("mask must remain array-backed");
187 };
188 assert!(ArrayRef::ptr_eq(&validity, &mask));
189
190 let mut ctx = SESSION.create_execution_ctx();
191 assert_arrays_eq!(
192 output,
193 PrimitiveArray::from_option_iter([Some(1i32), None, None]),
194 &mut ctx
195 );
196 Ok(())
197 }
198
199 #[rstest]
200 #[case::partially_valid(false)]
201 #[case::all_true_bitmap(true)]
202 fn array_backed_validity_keeps_lazy_mask(#[case] all_true: bool) -> VortexResult<()> {
203 let validity = BoolArray::from_iter([all_true, true, true]).into_array();
204 let input =
205 PrimitiveArray::new(buffer![1i32, 2, 3], Validity::Array(validity)).into_array();
206 let output = input.mask(lazy_mask()?)?;
207 assert!(output.is::<ExactScalarFn<MaskExpr>>());
208
209 let mut ctx = SESSION.create_execution_ctx();
210 assert_arrays_eq!(
211 output,
212 PrimitiveArray::from_option_iter([all_true.then_some(1i32), None, None]),
213 &mut ctx
214 );
215 Ok(())
216 }
217
218 #[rstest]
223 #[case(true)]
224 #[case(false)]
225 fn constant_mask_reduces_into_input(#[case] mask_value: bool) -> VortexResult<()> {
226 let input = buffer![1i32, 2, 3, 4, 5].into_array();
227 let mask = ConstantArray::new(
228 Scalar::bool(mask_value, Nullability::NonNullable),
229 input.len(),
230 )
231 .into_array();
232
233 let masked = MaskExpr::try_new(input, mask)?.into_array();
234 assert!(
235 masked.is::<ScalarFn>(),
236 "expected an un-optimized ScalarFn wrapper before optimization"
237 );
238
239 let optimized = masked.optimize()?;
240 assert!(
241 !optimized.is::<ScalarFn>(),
242 "constant mask should not fall through to execution, got {}",
243 optimized.encoding_id()
244 );
245 assert!(
246 optimized.is::<Primitive>(),
247 "constant mask should reduce into the Primitive input, got {}",
248 optimized.encoding_id()
249 );
250
251 let mut ctx = SESSION.create_execution_ctx();
252 let expected = if mask_value {
253 PrimitiveArray::from_option_iter([Some(1i32), Some(2), Some(3), Some(4), Some(5)])
254 } else {
255 PrimitiveArray::from_option_iter([None::<i32>, None, None, None, None])
256 };
257 assert_arrays_eq!(optimized, expected, &mut ctx);
258
259 Ok(())
260 }
261}