Skip to main content

vortex_array/arrays/null/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use vortex_error::VortexResult;
5use vortex_error::vortex_bail;
6use vortex_error::vortex_ensure;
7use vortex_error::vortex_ensure_eq;
8use vortex_error::vortex_panic;
9use vortex_session::VortexSession;
10use vortex_session::registry::CachedId;
11
12use crate::ArrayRef;
13use crate::ArraySlots;
14use crate::ArrayVTable;
15use crate::ExecutionCtx;
16use crate::ExecutionResult;
17use crate::array::Array;
18use crate::array::ArrayId;
19use crate::array::ArrayParts;
20use crate::array::ArrayView;
21use crate::array::EmptyArrayData;
22use crate::array::OperationsVTable;
23use crate::array::ProbeState;
24use crate::array::VTable;
25use crate::array::ValidityVTable;
26use crate::array::with_empty_buffers;
27use crate::arrays::Dict;
28use crate::arrays::dict::TakeExecuteAdaptor;
29use crate::arrays::null::compute::rules::PARENT_RULES;
30use crate::buffer::BufferHandle;
31use crate::builders::ArrayBuilder;
32use crate::builders::NullBuilder;
33use crate::dtype::DType;
34use crate::optimizer::kernels::ArrayKernelsExt;
35use crate::scalar::Scalar;
36use crate::serde::ArrayChildren;
37use crate::validity::Validity;
38
39pub(crate) mod compute;
40
41/// A [`Null`]-encoded Vortex array.
42pub type NullArray = Array<Null>;
43
44pub(crate) fn initialize(session: &VortexSession) {
45    session
46        .kernels()
47        .register_execute_parent_kernel(Dict.id(), Null, TakeExecuteAdaptor(Null));
48}
49
50impl VTable for Null {
51    type TypedArrayData = EmptyArrayData;
52
53    type OperationsVTable = Self;
54    type ValidityVTable = Self;
55
56    fn id(&self) -> ArrayId {
57        static ID: CachedId = CachedId::new("vortex.null");
58        *ID
59    }
60
61    fn validate(
62        &self,
63        _data: &EmptyArrayData,
64        dtype: &DType,
65        _len: usize,
66        _slots: &[Option<ArrayRef>],
67    ) -> VortexResult<()> {
68        vortex_ensure_eq!(*dtype, DType::Null, "NullArray dtype must be DType::Null");
69        Ok(())
70    }
71
72    fn nbuffers(_array: ArrayView<'_, Self>) -> usize {
73        0
74    }
75
76    fn buffer(_array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
77        vortex_panic!("NullArray buffer index {idx} out of bounds")
78    }
79
80    fn buffer_name(_array: ArrayView<'_, Self>, _idx: usize) -> Option<String> {
81        None
82    }
83
84    fn with_buffers(
85        &self,
86        array: ArrayView<'_, Self>,
87        buffers: &[BufferHandle],
88    ) -> VortexResult<ArrayParts<Self>> {
89        with_empty_buffers(self, array, buffers)
90    }
91
92    fn slot_name(_array: ArrayView<'_, Self>, idx: usize) -> String {
93        vortex_panic!("NullArray slot_name index {idx} out of bounds")
94    }
95
96    fn serialize(
97        _array: ArrayView<'_, Self>,
98        _session: &VortexSession,
99    ) -> VortexResult<Option<Vec<u8>>> {
100        Ok(Some(vec![]))
101    }
102
103    fn deserialize(
104        &self,
105        dtype: &DType,
106        len: usize,
107        metadata: &[u8],
108
109        _buffers: &[BufferHandle],
110        _children: &dyn ArrayChildren,
111        _session: &VortexSession,
112    ) -> VortexResult<ArrayParts<Self>> {
113        vortex_ensure!(
114            metadata.is_empty(),
115            "NullArray expects empty metadata, got {} bytes",
116            metadata.len()
117        );
118        Ok(ArrayParts::new(
119            self.clone(),
120            dtype.clone(),
121            len,
122            EmptyArrayData,
123            ArraySlots::new(),
124        ))
125    }
126
127    fn reduce_parent(
128        array: ArrayView<'_, Self>,
129        parent: &ArrayRef,
130        child_idx: usize,
131    ) -> VortexResult<Option<ArrayRef>> {
132        PARENT_RULES.evaluate(array, parent, child_idx)
133    }
134
135    fn execute(array: Array<Self>, _ctx: &mut ExecutionCtx) -> VortexResult<ExecutionResult> {
136        Ok(ExecutionResult::done(array))
137    }
138
139    fn append_to_builder(
140        array: ArrayView<'_, Self>,
141        builder: &mut dyn ArrayBuilder,
142        _ctx: &mut ExecutionCtx,
143    ) -> VortexResult<()> {
144        let Some(builder) = builder.as_any_mut().downcast_mut::<NullBuilder>() else {
145            vortex_bail!("append_to_builder for Null requires a NullBuilder");
146        };
147        builder.append_nulls(array.len());
148        Ok(())
149    }
150}
151
152/// A array where all values are null.
153///
154/// This mirrors the Apache Arrow Null array encoding and provides an efficient representation
155/// for arrays containing only null values. No actual data is stored, only the length.
156///
157/// All operations on null arrays return null values or indicate invalid data.
158///
159/// # Examples
160///
161/// ```
162/// # fn main() -> vortex_error::VortexResult<()> {
163/// use vortex_array::arrays::NullArray;
164/// use vortex_array::{IntoArray, VortexSessionExecute};
165/// use vortex_session::VortexSession;
166///
167/// // Create a null array with 5 elements
168/// let array = NullArray::new(5);
169///
170/// // Slice the array - still contains nulls
171/// let sliced = array.slice(1..3)?;
172/// assert_eq!(sliced.len(), 2);
173///
174/// // All elements are null
175/// let mut ctx = VortexSession::empty().create_execution_ctx();
176/// let scalar = array.execute_scalar(0, &mut ctx).unwrap();
177/// assert!(scalar.is_null());
178/// # Ok(())
179/// # }
180/// ```
181#[derive(Clone, Debug)]
182pub struct Null;
183
184impl Array<Null> {
185    pub fn new(len: usize) -> Self {
186        unsafe {
187            Array::from_parts_unchecked(ArrayParts::new(
188                Null,
189                DType::Null,
190                len,
191                EmptyArrayData,
192                ArraySlots::new(),
193            ))
194        }
195    }
196}
197
198impl OperationsVTable<Null> for Null {
199    type ProbeState = ();
200
201    fn probe_scalar(
202        _state: &mut ProbeState<'_, Null>,
203        _index: usize,
204        _ctx: &mut ExecutionCtx,
205    ) -> VortexResult<Scalar> {
206        Ok(Scalar::null(DType::Null))
207    }
208
209    fn scalar_at(
210        array: ArrayView<'_, Null>,
211        index: usize,
212        ctx: &mut ExecutionCtx,
213    ) -> VortexResult<Scalar> {
214        Self::probe_scalar(&mut ProbeState::once(array), index, ctx)
215    }
216}
217
218impl ValidityVTable<Null> for Null {
219    fn validity(_array: ArrayView<'_, Null>) -> VortexResult<Validity> {
220        Ok(Validity::AllInvalid)
221    }
222}