vortex_array/scalar_fn/fns/
is_null.rs1use vortex_error::VortexExpect as _;
5use vortex_error::VortexResult;
6use vortex_session::VortexSession;
7use vortex_session::registry::CachedId;
8
9use crate::ArrayRef;
10use crate::ExecutionCtx;
11use crate::IntoArray;
12use crate::arrays::ConstantArray;
13use crate::arrays::ScalarFnArray;
14use crate::builtins::ArrayBuiltins;
15use crate::dtype::DType;
16use crate::dtype::Nullability;
17use crate::scalar_fn::Arity;
18use crate::scalar_fn::ChildName;
19use crate::scalar_fn::EmptyOptions;
20use crate::scalar_fn::ExecutionArgs;
21use crate::scalar_fn::ReduceNode;
22use crate::scalar_fn::ScalarFnId;
23use crate::scalar_fn::ScalarFnVTable;
24use crate::scalar_fn::ScalarFnVTableExt;
25use crate::scalar_fn::fns::is_not_null::reduce_null;
26use crate::validity::Validity;
27
28#[derive(Clone)]
30pub struct IsNull;
31
32impl IsNull {
33 #[expect(clippy::new_ret_no_self, reason = "constructs the lazy result array")]
35 pub fn new(input: ArrayRef) -> ScalarFnArray {
36 ScalarFnArray::try_new(IsNull.bind(EmptyOptions), [input])
37 .vortex_expect("IsNull has one child and an infallible return dtype")
38 }
39}
40
41impl ScalarFnVTable for IsNull {
42 type Options = EmptyOptions;
43
44 fn id(&self) -> ScalarFnId {
45 static ID: CachedId = CachedId::new("vortex.is_null");
46 *ID
47 }
48
49 fn serialize(&self, _instance: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
50 Ok(Some(vec![]))
51 }
52
53 fn deserialize(
54 &self,
55 _metadata: &[u8],
56 _session: &VortexSession,
57 ) -> VortexResult<Self::Options> {
58 Ok(EmptyOptions)
59 }
60
61 fn arity(&self, _options: &Self::Options) -> Arity {
62 Arity::Exact(1)
63 }
64
65 fn child_name(&self, _instance: &Self::Options, child_idx: usize) -> ChildName {
66 match child_idx {
67 0 => ChildName::from("input"),
68 _ => unreachable!("Invalid child index {} for IsNull expression", child_idx),
69 }
70 }
71
72 fn return_dtype(&self, _options: &Self::Options, _arg_dtypes: &[DType]) -> VortexResult<DType> {
73 Ok(DType::Bool(Nullability::NonNullable))
74 }
75
76 fn execute(
77 &self,
78 _data: &Self::Options,
79 args: &dyn ExecutionArgs,
80 _ctx: &mut ExecutionCtx,
81 ) -> VortexResult<ArrayRef> {
82 let child = args.get(0)?;
83 if let Some(scalar) = child.as_constant() {
84 return Ok(ConstantArray::new(scalar.is_null(), args.row_count()).into_array());
85 }
86
87 match child.validity()? {
88 Validity::NonNullable | Validity::AllValid => {
89 Ok(ConstantArray::new(false, args.row_count()).into_array())
90 }
91 Validity::AllInvalid => Ok(ConstantArray::new(true, args.row_count()).into_array()),
92 Validity::Array(a) => a.not(),
93 }
94 }
95
96 fn reduce<T: ReduceNode>(&self, _options: &Self::Options, node: &T) -> VortexResult<Option<T>> {
97 reduce_null(true, node)
98 }
99
100 fn is_strict(&self, _instance: &Self::Options) -> bool {
101 false
103 }
104
105 fn is_infallible(&self, _instance: &Self::Options) -> bool {
106 true
107 }
108}
109
110#[cfg(test)]
111mod tests {
112 use std::sync::LazyLock;
113
114 use vortex_buffer::buffer;
115 use vortex_session::VortexSession;
116
117 use crate::IntoArray;
118 use crate::VortexSessionExecute;
119 use crate::arrays::PrimitiveArray;
120 use crate::arrays::StructArray;
121 use crate::dtype::DType;
122 use crate::dtype::Nullability;
123 use crate::expr::col;
124 use crate::expr::get_item;
125 use crate::expr::is_null;
126 use crate::expr::root;
127 use crate::expr::test_harness;
128 use crate::scalar::Scalar;
129
130 static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
131
132 #[test]
133 fn dtype() {
134 let dtype = test_harness::struct_dtype();
135 assert_eq!(
136 is_null(root()).return_dtype(&dtype).unwrap(),
137 DType::Bool(Nullability::NonNullable)
138 );
139 }
140
141 #[test]
142 fn evaluate_mask() {
143 let test_array =
144 PrimitiveArray::from_option_iter(vec![Some(1), None, Some(2), None, Some(3)])
145 .into_array();
146 let expected = [false, true, false, true, false];
147
148 let result = test_array.clone().apply(&is_null(root())).unwrap();
149
150 assert_eq!(result.len(), test_array.len());
151 assert_eq!(result.dtype(), &DType::Bool(Nullability::NonNullable));
152
153 for (i, expected_value) in expected.iter().enumerate() {
154 assert_eq!(
155 result
156 .execute_scalar(i, &mut SESSION.create_execution_ctx())
157 .unwrap(),
158 Scalar::bool(*expected_value, Nullability::NonNullable)
159 );
160 }
161 }
162
163 #[test]
164 fn evaluate_all_false() {
165 let test_array = buffer![1, 2, 3, 4, 5].into_array();
166
167 let result = test_array.clone().apply(&is_null(root())).unwrap();
168
169 assert_eq!(result.len(), test_array.len());
170 for i in 0..result.len() {
172 assert_eq!(
173 result
174 .execute_scalar(i, &mut SESSION.create_execution_ctx())
175 .unwrap(),
176 Scalar::bool(false, Nullability::NonNullable)
177 );
178 }
179 }
180
181 #[test]
182 fn evaluate_all_true() {
183 let test_array =
184 PrimitiveArray::from_option_iter(vec![None::<i32>, None, None, None, None])
185 .into_array();
186
187 let result = test_array.clone().apply(&is_null(root())).unwrap();
188
189 assert_eq!(result.len(), test_array.len());
190 for i in 0..result.len() {
192 assert_eq!(
193 result
194 .execute_scalar(i, &mut SESSION.create_execution_ctx())
195 .unwrap(),
196 Scalar::bool(true, Nullability::NonNullable)
197 );
198 }
199 }
200
201 #[test]
202 fn evaluate_struct() {
203 let test_array = StructArray::from_fields(&[(
204 "a",
205 PrimitiveArray::from_option_iter(vec![Some(1), None, Some(2), None, Some(3)])
206 .into_array(),
207 )])
208 .unwrap()
209 .into_array();
210 let expected = [false, true, false, true, false];
211
212 let result = test_array
213 .clone()
214 .apply(&is_null(get_item("a", root())))
215 .unwrap();
216
217 assert_eq!(result.len(), test_array.len());
218 assert_eq!(result.dtype(), &DType::Bool(Nullability::NonNullable));
219
220 for (i, expected_value) in expected.iter().enumerate() {
221 assert_eq!(
222 result
223 .execute_scalar(i, &mut SESSION.create_execution_ctx())
224 .unwrap(),
225 Scalar::bool(*expected_value, Nullability::NonNullable)
226 );
227 }
228 }
229
230 #[test]
231 fn test_display() {
232 let expr = is_null(get_item("name", root()));
233 assert_eq!(expr.to_string(), "vortex.is_null($.name)");
234
235 let expr2 = is_null(root());
236 assert_eq!(expr2.to_string(), "vortex.is_null($)");
237 }
238
239 #[test]
240 fn test_is_null_is_not_strict() {
241 assert!(
242 !is_null(col("a"))
243 .as_scalar()
244 .is_some_and(|f| f.signature().is_strict())
245 );
246 }
247}