datatypes/vectors/
null.rs

1// Copyright 2023 Greptime Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::any::Any;
16use std::fmt;
17use std::sync::Arc;
18
19use arrow::array::{Array, ArrayRef, NullArray};
20use snafu::{OptionExt, ensure};
21
22use crate::data_type::ConcreteDataType;
23use crate::error::{self, Result};
24use crate::prelude::{ScalarVector, ScalarVectorBuilder};
25use crate::serialize::Serializable;
26use crate::types::NullType;
27use crate::value::{Value, ValueRef};
28use crate::vectors::{self, MutableVector, Validity, Vector, VectorRef};
29
30/// A vector where all elements are nulls.
31#[derive(PartialEq)]
32pub struct NullVector {
33    array: NullArray,
34}
35
36// TODO(yingwen): Support null vector with other logical types.
37impl NullVector {
38    /// Create a new `NullVector` with `n` elements.
39    pub fn new(n: usize) -> Self {
40        Self {
41            array: NullArray::new(n),
42        }
43    }
44
45    pub(crate) fn as_arrow(&self) -> &dyn Array {
46        &self.array
47    }
48}
49
50impl From<NullArray> for NullVector {
51    fn from(array: NullArray) -> Self {
52        Self { array }
53    }
54}
55
56impl Vector for NullVector {
57    fn data_type(&self) -> ConcreteDataType {
58        ConcreteDataType::Null(NullType)
59    }
60
61    fn vector_type_name(&self) -> String {
62        "NullVector".to_string()
63    }
64
65    fn as_any(&self) -> &dyn Any {
66        self
67    }
68
69    fn len(&self) -> usize {
70        self.array.len()
71    }
72
73    fn to_arrow_array(&self) -> ArrayRef {
74        Arc::new(self.array.clone())
75    }
76
77    fn to_boxed_arrow_array(&self) -> Box<dyn Array> {
78        Box::new(self.array.clone())
79    }
80
81    fn validity(&self) -> Validity {
82        Validity::all_null(self.array.len())
83    }
84
85    fn memory_size(&self) -> usize {
86        0
87    }
88
89    fn null_count(&self) -> usize {
90        self.array.len()
91    }
92
93    fn is_null(&self, _row: usize) -> bool {
94        true
95    }
96
97    fn only_null(&self) -> bool {
98        true
99    }
100
101    fn slice(&self, _offset: usize, length: usize) -> VectorRef {
102        Arc::new(Self::new(length))
103    }
104
105    fn get(&self, _index: usize) -> Value {
106        // Skips bound check for null array.
107        Value::Null
108    }
109
110    fn get_ref(&self, _index: usize) -> ValueRef<'_> {
111        // Skips bound check for null array.
112        ValueRef::Null
113    }
114}
115
116impl ScalarVector for NullVector {
117    type OwnedItem = ();
118    type RefItem<'a> = ();
119    type Iter<'a> = NullIter<'a>;
120    type Builder = NullVectorBuilder;
121
122    fn get_data(&self, _idx: usize) -> Option<Self::RefItem<'_>> {
123        Some(())
124    }
125
126    fn iter_data(&self) -> Self::Iter<'_> {
127        NullIter::new(self)
128    }
129}
130
131impl fmt::Debug for NullVector {
132    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
133        write!(f, "NullVector({})", self.len())
134    }
135}
136
137impl Serializable for NullVector {
138    fn serialize_to_json(&self) -> Result<Vec<serde_json::Value>> {
139        Ok(std::iter::repeat_n(serde_json::Value::Null, self.len()).collect())
140    }
141}
142
143vectors::impl_try_from_arrow_array_for_vector!(NullArray, NullVector);
144
145pub struct NullIter<'a> {
146    vector: &'a NullVector,
147    index: usize,
148}
149
150impl<'a> NullIter<'a> {
151    pub fn new(vector: &'a NullVector) -> Self {
152        NullIter { vector, index: 0 }
153    }
154}
155
156impl<'a> Iterator for NullIter<'a> {
157    type Item = Option<()>;
158
159    fn next(&mut self) -> Option<Self::Item> {
160        if self.index < self.vector.len() {
161            self.index += 1;
162            Some(Some(()))
163        } else {
164            None
165        }
166    }
167}
168
169#[derive(Default)]
170pub struct NullVectorBuilder {
171    length: usize,
172}
173
174impl MutableVector for NullVectorBuilder {
175    fn data_type(&self) -> ConcreteDataType {
176        ConcreteDataType::null_datatype()
177    }
178
179    fn len(&self) -> usize {
180        self.length
181    }
182
183    fn as_any(&self) -> &dyn Any {
184        self
185    }
186
187    fn as_mut_any(&mut self) -> &mut dyn Any {
188        self
189    }
190
191    fn to_vector(&mut self) -> VectorRef {
192        let vector = Arc::new(NullVector::new(self.length));
193        self.length = 0;
194        vector
195    }
196
197    fn to_vector_cloned(&self) -> VectorRef {
198        Arc::new(NullVector::new(self.length))
199    }
200
201    fn try_push_value_ref(&mut self, value: &ValueRef) -> Result<()> {
202        ensure!(
203            value.is_null(),
204            error::CastTypeSnafu {
205                msg: format!("Failed to cast value ref {value:?} to null"),
206            }
207        );
208
209        self.length += 1;
210        Ok(())
211    }
212
213    fn extend_slice_of(&mut self, vector: &dyn Vector, offset: usize, length: usize) -> Result<()> {
214        let _ = vector
215            .as_any()
216            .downcast_ref::<NullVector>()
217            .with_context(|| error::CastTypeSnafu {
218                msg: format!(
219                    "Failed to convert vector from {} to NullVector",
220                    vector.vector_type_name()
221                ),
222            })?;
223        assert!(
224            offset + length <= vector.len(),
225            "offset {} + length {} must less than {}",
226            offset,
227            length,
228            vector.len()
229        );
230
231        self.length += length;
232        Ok(())
233    }
234
235    fn push_null(&mut self) {
236        self.length += 1;
237    }
238}
239
240impl ScalarVectorBuilder for NullVectorBuilder {
241    type VectorType = NullVector;
242
243    fn with_capacity(_capacity: usize) -> Self {
244        Self::default()
245    }
246
247    fn push(&mut self, _value: Option<<Self::VectorType as ScalarVector>::RefItem<'_>>) {
248        self.length += 1;
249    }
250
251    fn finish(&mut self) -> Self::VectorType {
252        let result = NullVector::new(self.length);
253
254        self.length = 0;
255        result
256    }
257
258    fn finish_cloned(&self) -> Self::VectorType {
259        NullVector::new(self.length)
260    }
261}
262
263#[cfg(test)]
264mod tests {
265    use serde_json;
266
267    use super::*;
268    use crate::data_type::DataType;
269
270    #[test]
271    fn test_null_vector_misc() {
272        let v = NullVector::new(32);
273
274        assert_eq!(v.len(), 32);
275        assert_eq!(0, v.memory_size());
276        assert_eq!(v.null_count(), 32);
277
278        let vector2 = v.slice(8, 16);
279        assert_eq!(vector2.len(), 16);
280        assert_eq!(vector2.null_count(), 16);
281
282        assert_eq!("NullVector", v.vector_type_name());
283        assert!(v.validity().is_all_null());
284        assert!(v.only_null());
285
286        for i in 0..32 {
287            assert!(v.is_null(i));
288            assert_eq!(Value::Null, v.get(i));
289            assert_eq!(ValueRef::Null, v.get_ref(i));
290        }
291    }
292
293    #[test]
294    fn test_debug_null_vector() {
295        let array = NullVector::new(1024 * 1024);
296        assert_eq!(format!("{array:?}"), "NullVector(1048576)");
297    }
298
299    #[test]
300    fn test_serialize_json() {
301        let vector = NullVector::new(3);
302        let json_value = vector.serialize_to_json().unwrap();
303        assert_eq!(
304            "[null,null,null]",
305            serde_json::to_string(&json_value).unwrap()
306        );
307    }
308
309    #[test]
310    fn test_null_vector_validity() {
311        let vector = NullVector::new(5);
312        assert!(vector.validity().is_all_null());
313        assert_eq!(5, vector.null_count());
314    }
315
316    #[test]
317    fn test_null_vector_builder() {
318        let mut builder = NullType.create_mutable_vector(3);
319        builder.push_null();
320        assert!(builder.try_push_value_ref(&ValueRef::Int32(123)).is_err());
321
322        let input = NullVector::new(3);
323        builder.extend_slice_of(&input, 1, 2).unwrap();
324        assert!(
325            builder
326                .extend_slice_of(&crate::vectors::Int32Vector::from_slice([13]), 0, 1)
327                .is_err()
328        );
329        let vector = builder.to_vector();
330
331        let expect: VectorRef = Arc::new(input);
332        assert_eq!(expect, vector);
333    }
334
335    #[test]
336    fn test_null_vector_builder_finish_cloned() {
337        let mut builder = NullType.create_mutable_vector(3);
338        builder.push_null();
339        builder.push_null();
340        let vector = builder.to_vector_cloned();
341        assert_eq!(vector.len(), 2);
342        assert_eq!(vector.null_count(), 2);
343    }
344}
datatypes/vectors/null.rs

datatypes/vectors/
null.rs
