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
263pub(crate) fn replicate_null(vector: &NullVector, offsets: &[usize]) -> VectorRef {
264    assert_eq!(offsets.len(), vector.len());
265
266    if offsets.is_empty() {
267        return vector.slice(0, 0);
268    }
269
270    Arc::new(NullVector::new(*offsets.last().unwrap()))
271}
272
273#[cfg(test)]
274mod tests {
275    use serde_json;
276
277    use super::*;
278    use crate::data_type::DataType;
279
280    #[test]
281    fn test_null_vector_misc() {
282        let v = NullVector::new(32);
283
284        assert_eq!(v.len(), 32);
285        assert_eq!(0, v.memory_size());
286        assert_eq!(v.null_count(), 32);
287
288        let vector2 = v.slice(8, 16);
289        assert_eq!(vector2.len(), 16);
290        assert_eq!(vector2.null_count(), 16);
291
292        assert_eq!("NullVector", v.vector_type_name());
293        assert!(!v.is_const());
294        assert!(v.validity().is_all_null());
295        assert!(v.only_null());
296
297        for i in 0..32 {
298            assert!(v.is_null(i));
299            assert_eq!(Value::Null, v.get(i));
300            assert_eq!(ValueRef::Null, v.get_ref(i));
301        }
302    }
303
304    #[test]
305    fn test_debug_null_vector() {
306        let array = NullVector::new(1024 * 1024);
307        assert_eq!(format!("{array:?}"), "NullVector(1048576)");
308    }
309
310    #[test]
311    fn test_serialize_json() {
312        let vector = NullVector::new(3);
313        let json_value = vector.serialize_to_json().unwrap();
314        assert_eq!(
315            "[null,null,null]",
316            serde_json::to_string(&json_value).unwrap()
317        );
318    }
319
320    #[test]
321    fn test_null_vector_validity() {
322        let vector = NullVector::new(5);
323        assert!(vector.validity().is_all_null());
324        assert_eq!(5, vector.null_count());
325    }
326
327    #[test]
328    fn test_null_vector_builder() {
329        let mut builder = NullType.create_mutable_vector(3);
330        builder.push_null();
331        assert!(builder.try_push_value_ref(&ValueRef::Int32(123)).is_err());
332
333        let input = NullVector::new(3);
334        builder.extend_slice_of(&input, 1, 2).unwrap();
335        assert!(
336            builder
337                .extend_slice_of(&crate::vectors::Int32Vector::from_slice([13]), 0, 1)
338                .is_err()
339        );
340        let vector = builder.to_vector();
341
342        let expect: VectorRef = Arc::new(input);
343        assert_eq!(expect, vector);
344    }
345
346    #[test]
347    fn test_null_vector_builder_finish_cloned() {
348        let mut builder = NullType.create_mutable_vector(3);
349        builder.push_null();
350        builder.push_null();
351        let vector = builder.to_vector_cloned();
352        assert_eq!(vector.len(), 2);
353        assert_eq!(vector.null_count(), 2);
354    }
355}
datatypes/vectors/null.rs

datatypes/vectors/
null.rs
