Skip to main content

arrow_array/array/
struct_array.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::array::print_long_array;
6use crate::{Array, ArrayRef, RecordBatch, make_array, new_null_array};
7use arrow_buffer::{BooleanBuffer, Buffer, NullBuffer};
8use arrow_data::{ArrayData, ArrayDataBuilder};
9use arrow_schema::{ArrowError, DataType, Field, FieldRef, Fields};
10use std::sync::Arc;
11use std::{any::Any, ops::Index};
12
13/// An array of [structs](https://arrow.apache.org/docs/format/Columnar.html#struct-layout)
14///
15/// Each child (called *field*) is represented by a separate array.
16///
17/// # Comparison with [RecordBatch]
18///
19/// Both [`RecordBatch`] and [`StructArray`] represent a collection of columns / arrays with the
20/// same length.
21///
22/// However, there are a couple of key differences:
23///
24/// * [`StructArray`] can be nested within other [`Array`], including itself
25/// * [`RecordBatch`] can contain top-level metadata on its associated [`Schema`][arrow_schema::Schema]
26/// * [`StructArray`] can contain top-level nulls, i.e. `null`
27/// * [`RecordBatch`] can only represent nulls in its child columns, i.e. `{"field": null}`
28///
29/// [`StructArray`] is therefore a more general data container than [`RecordBatch`], and as such
30/// code that needs to handle both will typically share an implementation in terms of
31/// [`StructArray`] and convert to/from [`RecordBatch`] as necessary.
32///
33/// [`From`] implementations are provided to facilitate this conversion, however, converting
34/// from a [`StructArray`] containing top-level nulls to a [`RecordBatch`] will panic, as there
35/// is no way to preserve them.
36///
37/// # Example: Create an array from a vector of fields
38///
39/// ```
40/// use std::sync::Arc;
41/// use arrow_array::{Array, ArrayRef, BooleanArray, Int32Array, StructArray};
42/// use arrow_schema::{DataType, Field};
43///
44/// let boolean = Arc::new(BooleanArray::from(vec![false, false, true, true]));
45/// let int = Arc::new(Int32Array::from(vec![42, 28, 19, 31]));
46///
47/// let struct_array = StructArray::from(vec![
48///     (
49///         Arc::new(Field::new("b", DataType::Boolean, false)),
50///         boolean.clone() as ArrayRef,
51///     ),
52///     (
53///         Arc::new(Field::new("c", DataType::Int32, false)),
54///         int.clone() as ArrayRef,
55///     ),
56/// ]);
57/// assert_eq!(struct_array.column(0).as_ref(), boolean.as_ref());
58/// assert_eq!(struct_array.column(1).as_ref(), int.as_ref());
59/// assert_eq!(4, struct_array.len());
60/// assert_eq!(0, struct_array.null_count());
61/// assert_eq!(0, struct_array.offset());
62/// ```
63#[derive(Clone)]
64pub struct StructArray {
65    len: usize,
66    data_type: DataType,
67    nulls: Option<NullBuffer>,
68    fields: Vec<ArrayRef>,
69}
70
71impl StructArray {
72    /// Create a new [`StructArray`] from the provided parts, panicking on failure
73    ///
74    /// # Panics
75    ///
76    /// Panics if [`Self::try_new`] returns an error
77    pub fn new(fields: Fields, arrays: Vec<ArrayRef>, nulls: Option<NullBuffer>) -> Self {
78        Self::try_new(fields, arrays, nulls).unwrap()
79    }
80
81    /// Create a new [`StructArray`] from the provided parts, returning an error on failure
82    ///
83    /// The length will be inferred from the length of the child arrays.  Returns an error if
84    /// there are no child arrays.  Consider using [`Self::try_new_with_length`] if the length
85    /// is known to avoid this.
86    ///
87    /// # Errors
88    ///
89    /// Errors if
90    ///
91    /// * `fields.len() == 0`
92    /// * Any reason that [`Self::try_new_with_length`] would error
93    pub fn try_new(
94        fields: Fields,
95        arrays: Vec<ArrayRef>,
96        nulls: Option<NullBuffer>,
97    ) -> Result<Self, ArrowError> {
98        let len = arrays.first().map(|x| x.len()).ok_or_else(||ArrowError::InvalidArgumentError("use StructArray::try_new_with_length or StructArray::new_empty_fields to create a struct array with no fields so that the length can be set correctly".to_string()))?;
99
100        Self::try_new_with_length(fields, arrays, nulls, len)
101    }
102
103    /// Create a new [`StructArray`] from the provided parts, returning an error on failure
104    ///
105    /// # Errors
106    ///
107    /// Errors if
108    ///
109    /// * `fields.len() != arrays.len()`
110    /// * `fields[i].data_type() != arrays[i].data_type()`
111    /// * `arrays[i].len() != arrays[j].len()`
112    /// * `arrays[i].len() != nulls.len()`
113    /// * `!fields[i].is_nullable() && !nulls.contains(arrays[i].nulls())`
114    pub fn try_new_with_length(
115        fields: Fields,
116        arrays: Vec<ArrayRef>,
117        nulls: Option<NullBuffer>,
118        len: usize,
119    ) -> Result<Self, ArrowError> {
120        if fields.len() != arrays.len() {
121            return Err(ArrowError::InvalidArgumentError(format!(
122                "Incorrect number of arrays for StructArray fields, expected {} got {}",
123                fields.len(),
124                arrays.len()
125            )));
126        }
127
128        if let Some(n) = nulls.as_ref()
129            && n.len() != len
130        {
131            return Err(ArrowError::InvalidArgumentError(format!(
132                "Incorrect number of nulls for StructArray, expected {len} got {}",
133                n.len(),
134            )));
135        }
136
137        for (f, a) in fields.iter().zip(&arrays) {
138            if f.data_type() != a.data_type() {
139                return Err(ArrowError::InvalidArgumentError(format!(
140                    "Incorrect datatype for StructArray field {:?}, expected {} got {}",
141                    f.name(),
142                    f.data_type(),
143                    a.data_type()
144                )));
145            }
146
147            if a.len() != len {
148                return Err(ArrowError::InvalidArgumentError(format!(
149                    "Incorrect array length for StructArray field {:?}, expected {} got {}",
150                    f.name(),
151                    len,
152                    a.len()
153                )));
154            }
155
156            if !f.is_nullable() {
157                let unmasked = match nulls.as_ref() {
158                    None => a.logical_null_count() > 0,
159                    Some(n) => a.logical_nulls().is_some_and(|ln| !n.contains(&ln)),
160                };
161                if unmasked {
162                    return Err(ArrowError::InvalidArgumentError(format!(
163                        "Found unmasked nulls for non-nullable StructArray field {:?}",
164                        f.name()
165                    )));
166                }
167            }
168        }
169
170        Ok(Self {
171            len,
172            data_type: DataType::Struct(fields),
173            nulls: nulls.filter(|n| n.null_count() > 0),
174            fields: arrays,
175        })
176    }
177
178    /// Create a new [`StructArray`] of length `len` where all values are null
179    pub fn new_null(fields: Fields, len: usize) -> Self {
180        let arrays = fields
181            .iter()
182            .map(|f| new_null_array(f.data_type(), len))
183            .collect();
184
185        Self {
186            len,
187            data_type: DataType::Struct(fields),
188            nulls: Some(NullBuffer::new_null(len)),
189            fields: arrays,
190        }
191    }
192
193    /// Create a new [`StructArray`] from the provided parts without validation
194    ///
195    /// The length will be inferred from the length of the child arrays.  Panics if there are no
196    /// child arrays.  Consider using [`Self::new_unchecked_with_length`] if the length is known
197    /// to avoid this.
198    ///
199    /// # Safety
200    ///
201    /// Safe if [`Self::new`] would not panic with the given arguments
202    pub unsafe fn new_unchecked(
203        fields: Fields,
204        arrays: Vec<ArrayRef>,
205        nulls: Option<NullBuffer>,
206    ) -> Self {
207        if cfg!(feature = "force_validate") {
208            return Self::new(fields, arrays, nulls);
209        }
210
211        let len = arrays.first().map(|x| x.len()).expect(
212            "cannot use StructArray::new_unchecked if there are no fields, length is unknown",
213        );
214        Self {
215            len,
216            data_type: DataType::Struct(fields),
217            nulls,
218            fields: arrays,
219        }
220    }
221
222    /// Create a new [`StructArray`] from the provided parts without validation
223    ///
224    /// # Safety
225    ///
226    /// Safe if [`Self::new`] would not panic with the given arguments
227    pub unsafe fn new_unchecked_with_length(
228        fields: Fields,
229        arrays: Vec<ArrayRef>,
230        nulls: Option<NullBuffer>,
231        len: usize,
232    ) -> Self {
233        if cfg!(feature = "force_validate") {
234            return Self::try_new_with_length(fields, arrays, nulls, len).unwrap();
235        }
236
237        Self {
238            len,
239            data_type: DataType::Struct(fields),
240            nulls,
241            fields: arrays,
242        }
243    }
244
245    /// Create a new [`StructArray`] containing no fields
246    ///
247    /// # Panics
248    ///
249    /// If `len != nulls.len()`
250    pub fn new_empty_fields(len: usize, nulls: Option<NullBuffer>) -> Self {
251        if let Some(n) = &nulls {
252            assert_eq!(len, n.len())
253        }
254        Self {
255            len,
256            data_type: DataType::Struct(Fields::empty()),
257            fields: vec![],
258            nulls,
259        }
260    }
261
262    /// Deconstruct this array into its constituent parts
263    pub fn into_parts(self) -> (Fields, Vec<ArrayRef>, Option<NullBuffer>) {
264        let DataType::Struct(f) = self.data_type else {
265            unreachable!()
266        };
267        (f, self.fields, self.nulls)
268    }
269
270    /// Returns the field at `pos`.
271    ///
272    /// # Panics
273    /// Panics if `pos` is out of bounds
274    pub fn column(&self, pos: usize) -> &ArrayRef {
275        &self.fields[pos]
276    }
277
278    /// Return the number of fields in this struct array
279    pub fn num_columns(&self) -> usize {
280        self.fields.len()
281    }
282
283    /// Returns the fields of the struct array
284    pub fn columns(&self) -> &[ArrayRef] {
285        &self.fields
286    }
287
288    /// Return field names in this struct array
289    pub fn column_names(&self) -> Vec<&str> {
290        match self.data_type() {
291            DataType::Struct(fields) => fields
292                .iter()
293                .map(|f| f.name().as_str())
294                .collect::<Vec<&str>>(),
295            _ => unreachable!("Struct array's data type is not struct!"),
296        }
297    }
298
299    /// Returns the [`Fields`] of this [`StructArray`]
300    pub fn fields(&self) -> &Fields {
301        match self.data_type() {
302            DataType::Struct(f) => f,
303            _ => unreachable!(),
304        }
305    }
306
307    /// Return child array whose field name equals to column_name
308    ///
309    /// Note: A schema can currently have duplicate field names, in which case
310    /// the first field will always be selected.
311    /// This issue will be addressed in [#9205](https://github.com/apache/arrow-rs/issues/9205)
312    pub fn column_by_name(&self, column_name: &str) -> Option<&ArrayRef> {
313        self.fields()
314            .find(column_name)
315            .map(|(pos, _)| self.column(pos))
316    }
317
318    /// Returns the [`FieldRef`] at `pos`.
319    pub fn field(&self, pos: usize) -> &FieldRef {
320        &self.fields()[pos]
321    }
322
323    /// Return the [`FieldRef`] whose name equals to `field_name`
324    ///
325    /// Note: A schema can currently have duplicate field names, in which case
326    /// the first field will always be selected.
327    /// This issue will be addressed in [#9205](https://github.com/apache/arrow-rs/issues/9205)
328    pub fn field_by_name(&self, field_name: &str) -> Option<&FieldRef> {
329        self.fields().find(field_name).map(|(_, field)| field)
330    }
331
332    /// Returns a zero-copy slice of this array with the indicated offset and length.
333    ///
334    /// # Panics
335    /// Panics if `offset + len > self.len()`
336    pub fn slice(&self, offset: usize, len: usize) -> Self {
337        assert!(
338            offset.saturating_add(len) <= self.len,
339            "the length + offset of the sliced StructArray cannot exceed the existing length"
340        );
341
342        let fields = self.fields.iter().map(|a| a.slice(offset, len)).collect();
343
344        Self {
345            len,
346            data_type: self.data_type.clone(),
347            nulls: self.nulls.as_ref().map(|n| n.slice(offset, len)),
348            fields,
349        }
350    }
351
352    /// Returns the children of this [`StructArray`] with the struct's validity
353    /// bitmap AND'd into each child's validity bitmap.
354    ///
355    /// This ensures that positions where the struct itself is null are also
356    /// null in each returned child array. Fields that were non-nullable are
357    /// marked nullable in the returned [`Fields`] when the struct has nulls.
358    ///
359    /// If the struct has no nulls, children and fields are returned as-is.
360    ///
361    /// This mirrors the semantics of C++ Arrow's `StructArray::Flatten`.
362    ///
363    /// # Example
364    ///
365    /// ```
366    /// # use std::sync::Arc;
367    /// # use arrow_array::{Array, ArrayRef, Int32Array, StructArray};
368    /// # use arrow_buffer::{BooleanBuffer, NullBuffer};
369    /// # use arrow_schema::{DataType, Field, Fields};
370    /// let child = Arc::new(Int32Array::from(vec![1, 2, 3])) as ArrayRef;
371    /// let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, false, true]));
372    /// let sa = StructArray::new(
373    ///     Fields::from(vec![Field::new("a", DataType::Int32, false)]),
374    ///     vec![child],
375    ///     Some(struct_nulls),
376    /// );
377    /// let (fields, columns) = sa.flatten();
378    /// assert!(fields[0].is_nullable());
379    /// assert!(columns[0].is_null(1));
380    /// ```
381    pub fn flatten(&self) -> (Fields, Vec<ArrayRef>) {
382        let schema_fields = self.fields();
383
384        let Some(struct_nulls) = &self.nulls else {
385            return (schema_fields.clone(), self.fields.clone());
386        };
387
388        let new_fields: Fields = schema_fields
389            .iter()
390            .map(|f| {
391                if f.is_nullable() {
392                    Arc::clone(f)
393                } else {
394                    Arc::new(f.as_ref().clone().with_nullable(true))
395                }
396            })
397            .collect::<Vec<_>>()
398            .into();
399
400        let new_columns = self
401            .fields
402            .iter()
403            .map(|child| {
404                let merged = NullBuffer::union(Some(struct_nulls), child.nulls());
405                // SAFETY: We only make the null buffer more restrictive (adding nulls).
406                // All data buffers and child data remain unchanged.
407                let data = child.to_data().into_builder().nulls(merged);
408                make_array(unsafe { data.build_unchecked() })
409            })
410            .collect();
411
412        (new_fields, new_columns)
413    }
414}
415
416impl From<ArrayData> for StructArray {
417    fn from(data: ArrayData) -> Self {
418        let (data_type, len, nulls, offset, _buffers, child_data) = data.into_parts();
419
420        let parent_offset = offset;
421        let parent_len = len;
422
423        let fields = child_data
424            .into_iter()
425            .map(|cd| {
426                if parent_offset != 0 || parent_len != cd.len() {
427                    make_array(cd.sliced(parent_offset, parent_len))
428                } else {
429                    make_array(cd)
430                }
431            })
432            .collect();
433
434        Self {
435            len,
436            data_type,
437            nulls,
438            fields,
439        }
440    }
441}
442
443impl From<StructArray> for ArrayData {
444    fn from(array: StructArray) -> Self {
445        let builder = ArrayDataBuilder::new(array.data_type)
446            .len(array.len)
447            .nulls(array.nulls)
448            .child_data(array.fields.iter().map(|x| x.to_data()).collect());
449
450        unsafe { builder.build_unchecked() }
451    }
452}
453
454impl TryFrom<Vec<(&str, ArrayRef)>> for StructArray {
455    type Error = ArrowError;
456
457    /// builds a StructArray from a vector of names and arrays.
458    fn try_from(values: Vec<(&str, ArrayRef)>) -> Result<Self, ArrowError> {
459        let (fields, arrays): (Vec<_>, _) = values
460            .into_iter()
461            .map(|(name, array)| {
462                (
463                    Field::new(name, array.data_type().clone(), array.is_nullable()),
464                    array,
465                )
466            })
467            .unzip();
468
469        StructArray::try_new(fields.into(), arrays, None)
470    }
471}
472
473/// SAFETY: Correctly implements the contract of Arrow Arrays
474unsafe impl Array for StructArray {
475    fn as_any(&self) -> &dyn Any {
476        self
477    }
478
479    fn to_data(&self) -> ArrayData {
480        self.clone().into()
481    }
482
483    fn into_data(self) -> ArrayData {
484        self.into()
485    }
486
487    fn data_type(&self) -> &DataType {
488        &self.data_type
489    }
490
491    fn slice(&self, offset: usize, length: usize) -> ArrayRef {
492        Arc::new(self.slice(offset, length))
493    }
494
495    fn len(&self) -> usize {
496        self.len
497    }
498
499    fn is_empty(&self) -> bool {
500        self.len == 0
501    }
502
503    fn shrink_to_fit(&mut self) {
504        if let Some(nulls) = &mut self.nulls {
505            nulls.shrink_to_fit();
506        }
507        self.fields.iter_mut().for_each(|n| n.shrink_to_fit());
508    }
509
510    fn offset(&self) -> usize {
511        0
512    }
513
514    fn nulls(&self) -> Option<&NullBuffer> {
515        self.nulls.as_ref()
516    }
517
518    fn logical_null_count(&self) -> usize {
519        // More efficient that the default implementation
520        self.null_count()
521    }
522
523    fn get_buffer_memory_size(&self) -> usize {
524        let mut size = self.fields.iter().map(|a| a.get_buffer_memory_size()).sum();
525        if let Some(n) = self.nulls.as_ref() {
526            size += n.buffer().capacity();
527        }
528        size
529    }
530
531    fn get_array_memory_size(&self) -> usize {
532        let mut size = self.fields.iter().map(|a| a.get_array_memory_size()).sum();
533        size += std::mem::size_of::<Self>();
534        if let Some(n) = self.nulls.as_ref() {
535            size += n.buffer().capacity();
536        }
537        size
538    }
539
540    #[cfg(feature = "pool")]
541    fn claim(&self, pool: &dyn arrow_buffer::MemoryPool) {
542        for field in &self.fields {
543            field.claim(pool);
544        }
545        if let Some(nulls) = &self.nulls {
546            nulls.claim(pool);
547        }
548    }
549}
550
551impl From<Vec<(FieldRef, ArrayRef)>> for StructArray {
552    fn from(v: Vec<(FieldRef, ArrayRef)>) -> Self {
553        let (fields, arrays): (Vec<_>, _) = v.into_iter().unzip();
554        StructArray::new(fields.into(), arrays, None)
555    }
556}
557
558impl std::fmt::Debug for StructArray {
559    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
560        writeln!(f, "StructArray")?;
561        writeln!(f, "-- validity:")?;
562        writeln!(f, "[")?;
563        print_long_array(self, f, &mut |_index, f| write!(f, "valid"))?;
564        writeln!(f, "]\n[")?;
565        for (child_index, name) in self.column_names().iter().enumerate() {
566            let column = self.column(child_index);
567            writeln!(
568                f,
569                "-- child {}: \"{}\" ({:?})",
570                child_index,
571                name,
572                column.data_type()
573            )?;
574            std::fmt::Debug::fmt(column, f)?;
575            writeln!(f)?;
576        }
577        write!(f, "]")
578    }
579}
580
581impl From<(Vec<(FieldRef, ArrayRef)>, Buffer)> for StructArray {
582    fn from(pair: (Vec<(FieldRef, ArrayRef)>, Buffer)) -> Self {
583        let len = pair.0.first().map(|x| x.1.len()).unwrap_or_default();
584        let (fields, arrays): (Vec<_>, Vec<_>) = pair.0.into_iter().unzip();
585        let nulls = NullBuffer::new(BooleanBuffer::new(pair.1, 0, len));
586        Self::new(fields.into(), arrays, Some(nulls))
587    }
588}
589
590impl From<RecordBatch> for StructArray {
591    fn from(value: RecordBatch) -> Self {
592        Self {
593            len: value.num_rows(),
594            data_type: DataType::Struct(value.schema().fields().clone()),
595            nulls: None,
596            fields: value.columns().to_vec(),
597        }
598    }
599}
600
601impl Index<&str> for StructArray {
602    type Output = ArrayRef;
603
604    /// Get a reference to a column's array by name.
605    ///
606    /// Note: A schema can currently have duplicate field names, in which case
607    /// the first field will always be selected.
608    /// This issue will be addressed in [ARROW-11178](https://issues.apache.org/jira/browse/ARROW-11178)
609    ///
610    /// # Panics
611    ///
612    /// Panics if the name is not in the schema.
613    fn index(&self, name: &str) -> &Self::Output {
614        self.column_by_name(name).unwrap()
615    }
616}
617
618#[cfg(test)]
619mod tests {
620    use super::*;
621
622    use crate::{
623        BooleanArray, Float32Array, Float64Array, Int32Array, Int64Array, NullArray, StringArray,
624        cast::AsArray, types::Int32Type,
625    };
626    use arrow_buffer::ToByteSlice;
627
628    #[test]
629    fn test_struct_array_builder() {
630        let boolean_array = BooleanArray::from(vec![false, false, true, true]);
631        let int_array = Int64Array::from(vec![42, 28, 19, 31]);
632
633        let fields = vec![
634            Field::new("a", DataType::Boolean, false),
635            Field::new("b", DataType::Int64, false),
636        ];
637        let struct_array_data = ArrayData::builder(DataType::Struct(fields.into()))
638            .len(4)
639            .add_child_data(boolean_array.to_data())
640            .add_child_data(int_array.to_data())
641            .build()
642            .unwrap();
643        let struct_array = StructArray::from(struct_array_data);
644
645        assert_eq!(struct_array.column(0).as_ref(), &boolean_array);
646        assert_eq!(struct_array.column(1).as_ref(), &int_array);
647    }
648
649    #[test]
650    fn test_struct_array_from() {
651        let boolean = Arc::new(BooleanArray::from(vec![false, false, true, true]));
652        let int = Arc::new(Int32Array::from(vec![42, 28, 19, 31]));
653
654        let struct_array = StructArray::from(vec![
655            (
656                Arc::new(Field::new("b", DataType::Boolean, false)),
657                boolean.clone() as ArrayRef,
658            ),
659            (
660                Arc::new(Field::new("c", DataType::Int32, false)),
661                int.clone() as ArrayRef,
662            ),
663        ]);
664        assert_eq!(struct_array.column(0).as_ref(), boolean.as_ref());
665        assert_eq!(struct_array.column(1).as_ref(), int.as_ref());
666        assert_eq!(4, struct_array.len());
667        assert_eq!(0, struct_array.null_count());
668        assert_eq!(0, struct_array.offset());
669    }
670
671    #[test]
672    fn test_struct_array_from_data_with_offset_and_length() {
673        // Various ways to make the struct array:
674        //
675        // [{x: 2}, {x: 3}, None]
676        //
677        // from slicing larger buffers/arrays with offsets and lengths
678        let int_arr = Int32Array::from(vec![1, 2, 3, 4, 5]);
679        let int_field = Field::new("x", DataType::Int32, false);
680        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, true, false]));
681        let int_data = int_arr.to_data();
682        // Case 1: Offset + length, nulls are not sliced
683        let case1 = ArrayData::builder(DataType::Struct(Fields::from(vec![int_field.clone()])))
684            .len(3)
685            .offset(1)
686            .nulls(Some(struct_nulls))
687            .add_child_data(int_data.clone())
688            .build()
689            .unwrap();
690
691        // Case 2: Offset + length, nulls are sliced
692        let struct_nulls =
693            NullBuffer::new(BooleanBuffer::from(vec![true, true, true, false, true]).slice(1, 3));
694        let case2 = ArrayData::builder(DataType::Struct(Fields::from(vec![int_field.clone()])))
695            .len(3)
696            .offset(1)
697            .nulls(Some(struct_nulls.clone()))
698            .add_child_data(int_data.clone())
699            .build()
700            .unwrap();
701
702        // Case 3: struct length is smaller than child length but no offset
703        let offset_int_data = int_data.slice(1, 4);
704        let case3 = ArrayData::builder(DataType::Struct(Fields::from(vec![int_field.clone()])))
705            .len(3)
706            .nulls(Some(struct_nulls))
707            .add_child_data(offset_int_data)
708            .build()
709            .unwrap();
710
711        let expected = StructArray::new(
712            Fields::from(vec![int_field.clone()]),
713            vec![Arc::new(int_arr)],
714            Some(NullBuffer::new(BooleanBuffer::from(vec![
715                true, true, true, false, true,
716            ]))),
717        )
718        .slice(1, 3);
719
720        for case in [case1, case2, case3] {
721            let struct_arr_from_data = StructArray::from(case);
722            assert_eq!(struct_arr_from_data, expected);
723            assert_eq!(struct_arr_from_data.column(0), expected.column(0));
724        }
725    }
726
727    #[test]
728    fn test_struct_array_data_slice() {
729        // Slicing a struct's `ArrayData` and rebuilding an array from it has to
730        // apply the offset to the children exactly once (#7595, #7750).
731        let x = Int32Array::from(vec![Some(0), Some(1), Some(2), Some(3), None, Some(5)]);
732        let struct_array = StructArray::new(
733            Fields::from(vec![Field::new("x", DataType::Int32, true)]),
734            vec![Arc::new(x.clone())],
735            Some(NullBuffer::from(vec![true, true, true, false, true, true])),
736        )
737        .into_data();
738        let sliced = struct_array.slice(1, 4);
739
740        let arr = make_array(sliced);
741        assert_eq!(
742            arr.as_struct().column(0).as_primitive::<Int32Type>(),
743            &x.slice(1, 4)
744        );
745
746        // A struct whose top-level `ArrayData` carries a non-zero offset over
747        // full-length children is how the C++ implementation of Arrow (and the
748        // C data interface) represents a sliced struct: the offset/length live
749        // on the struct, not on the children. arrow-rs must decode it to the
750        // same logical array its own `StructArray::slice` produces.
751        let x = Int32Array::from(vec![Some(0), Some(1), Some(2), Some(3), None, Some(5)]);
752        let y = Int32Array::from(vec![Some(5), Some(6), None, Some(8), Some(9), Some(10)]);
753        let struct_array = StructArray::new(
754            Fields::from(vec![
755                Field::new("x", DataType::Int32, true),
756                Field::new("y", DataType::Int32, true),
757            ]),
758            vec![Arc::new(x), Arc::new(y)],
759            Some(NullBuffer::from(vec![true, true, true, false, true, true])),
760        );
761        let struct_array = StructArray::new(
762            Fields::from(vec![Field::new(
763                "inner",
764                struct_array.data_type().clone(),
765                true,
766            )]),
767            vec![Arc::new(struct_array)],
768            Some(NullBuffer::from(vec![true, false, true, true, true, true])),
769        );
770
771        let cpp_sliced_array = make_array(
772            struct_array
773                .to_data()
774                .into_builder()
775                .offset(1)
776                .len(4)
777                .nulls(Some(NullBuffer::from(vec![false, true, true, true])))
778                .build()
779                .unwrap(),
780        );
781
782        assert_eq!(cpp_sliced_array.as_struct(), &struct_array.slice(1, 4));
783    }
784
785    #[test]
786    fn test_make_array_sliced_struct_data() {
787        // Exact reproducer from #7750: `make_array` on a sliced struct's
788        // `ArrayData`.
789        let strings: ArrayRef = Arc::new(StringArray::from(vec![
790            Some("joe"),
791            None,
792            None,
793            Some("mark"),
794            Some("doe"),
795        ]));
796        let ints: ArrayRef = Arc::new(Int32Array::from(vec![
797            Some(1),
798            Some(2),
799            Some(3),
800            Some(4),
801            Some(5),
802        ]));
803
804        let array = StructArray::try_from(vec![("f1", strings.clone()), ("f2", ints.clone())])
805            .unwrap()
806            .into_data()
807            .slice(1, 3);
808
809        let arr = make_array(array);
810        let expected = StructArray::try_from(vec![("f1", strings), ("f2", ints)])
811            .unwrap()
812            .slice(1, 3);
813        assert_eq!(arr.as_struct(), &expected);
814    }
815
816    #[test]
817    fn test_slice_struct_data_with_existing_offset() {
818        // Slicing a struct whose `ArrayData` already carries a non-zero offset
819        // over full-length children, which is how the C data interface hands us
820        // a sliced struct. The cumulative offset has to end up on the children
821        // only: anything left on the parent gets applied a second time by
822        // `From<ArrayData> for StructArray`.
823        let x = Int32Array::from(vec![Some(0), Some(1), Some(2), Some(3), None, Some(5)]);
824        let struct_array = StructArray::new(
825            Fields::from(vec![Field::new("x", DataType::Int32, true)]),
826            vec![Arc::new(x.clone())],
827            Some(NullBuffer::from(vec![true, true, true, false, true, true])),
828        );
829
830        let offset_data = struct_array
831            .to_data()
832            .into_builder()
833            .offset(1)
834            .len(5)
835            .nulls(Some(NullBuffer::from(vec![true, true, false, true, true])))
836            .build()
837            .unwrap();
838
839        let sliced = offset_data.slice(1, 3);
840        // The cumulative offset (1 + 1) lands on the child; the parent's own
841        // offset is reset to 0 so nothing re-applies it.
842        assert_eq!(sliced.offset(), 0);
843        assert_eq!(sliced.len(), 3);
844        assert_eq!(sliced.child_data()[0].offset(), 2);
845        assert_eq!(sliced.child_data()[0].len(), 3);
846
847        let arr = make_array(sliced);
848        assert_eq!(
849            arr.as_struct().column(0).as_primitive::<Int32Type>(),
850            &x.slice(2, 3)
851        );
852        assert_eq!(arr.as_struct(), &struct_array.slice(2, 3));
853    }
854
855    #[test]
856    fn test_struct_array_from_data_with_offset_and_length_error() {
857        let int_arr = Int32Array::from(vec![1, 2, 3, 4, 5]);
858        let int_field = Field::new("x", DataType::Int32, false);
859        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, true, false]));
860        let int_data = int_arr.to_data();
861        // If parent offset is 3 and len is 3 then child must have 6 items
862        let err = ArrayData::builder(DataType::Struct(Fields::from(vec![int_field.clone()])))
863            .len(3)
864            .offset(3)
865            .nulls(Some(struct_nulls))
866            .add_child_data(int_data)
867            .build()
868            .unwrap_err()
869            .to_string();
870
871        assert!(err.contains(
872            "child array #0 for field x has length smaller than expected for struct array (5 < 6)"
873        ));
874    }
875
876    /// validates that struct can be accessed using `column_name` as index i.e. `struct_array["column_name"]`.
877    #[test]
878    fn test_struct_array_index_access() {
879        let boolean = Arc::new(BooleanArray::from(vec![false, false, true, true]));
880        let int = Arc::new(Int32Array::from(vec![42, 28, 19, 31]));
881
882        let struct_array = StructArray::from(vec![
883            (
884                Arc::new(Field::new("b", DataType::Boolean, false)),
885                boolean.clone() as ArrayRef,
886            ),
887            (
888                Arc::new(Field::new("c", DataType::Int32, false)),
889                int.clone() as ArrayRef,
890            ),
891        ]);
892        assert_eq!(struct_array["b"].as_ref(), boolean.as_ref());
893        assert_eq!(struct_array["c"].as_ref(), int.as_ref());
894    }
895
896    #[test]
897    fn test_struct_array_field_access() {
898        let boolean = Arc::new(BooleanArray::from(vec![false, false, true, true]));
899        let int = Arc::new(Int32Array::from(vec![42, 28, 19, 31]));
900
901        let b_field = Arc::new(Field::new("b", DataType::Boolean, false));
902        let c_field = Arc::new(Field::new("c", DataType::Int32, false));
903
904        let struct_array = StructArray::from(vec![
905            (b_field.clone(), boolean as ArrayRef),
906            (c_field.clone(), int as ArrayRef),
907        ]);
908
909        assert_eq!(struct_array.field(0), &b_field);
910        assert_eq!(struct_array.field(1), &c_field);
911
912        assert_eq!(struct_array.field_by_name("b"), Some(&b_field));
913        assert_eq!(struct_array.field_by_name("c"), Some(&c_field));
914        assert_eq!(struct_array.field_by_name("d"), None);
915    }
916
917    /// validates that the in-memory representation follows [the spec](https://arrow.apache.org/docs/format/Columnar.html#struct-layout)
918    #[test]
919    fn test_struct_array_from_vec() {
920        let strings: ArrayRef = Arc::new(StringArray::from(vec![
921            Some("joe"),
922            None,
923            None,
924            Some("mark"),
925        ]));
926        let ints: ArrayRef = Arc::new(Int32Array::from(vec![Some(1), Some(2), None, Some(4)]));
927
928        let arr =
929            StructArray::try_from(vec![("f1", strings.clone()), ("f2", ints.clone())]).unwrap();
930
931        let struct_data = arr.into_data();
932        assert_eq!(4, struct_data.len());
933        assert_eq!(0, struct_data.null_count());
934
935        let expected_string_data = ArrayData::builder(DataType::Utf8)
936            .len(4)
937            .null_bit_buffer(Some(Buffer::from(&[9_u8])))
938            .add_buffer(Buffer::from([0, 3, 3, 3, 7].to_byte_slice()))
939            .add_buffer(Buffer::from(b"joemark"))
940            .build()
941            .unwrap();
942
943        let expected_int_data = ArrayData::builder(DataType::Int32)
944            .len(4)
945            .null_bit_buffer(Some(Buffer::from(&[11_u8])))
946            .add_buffer(Buffer::from([1, 2, 0, 4].to_byte_slice()))
947            .build()
948            .unwrap();
949
950        assert_eq!(expected_string_data, struct_data.child_data()[0]);
951        assert_eq!(expected_int_data, struct_data.child_data()[1]);
952    }
953
954    #[test]
955    fn test_struct_array_from_vec_error() {
956        let strings: ArrayRef = Arc::new(StringArray::from(vec![
957            Some("joe"),
958            None,
959            None,
960            // 3 elements, not 4
961        ]));
962        let ints: ArrayRef = Arc::new(Int32Array::from(vec![Some(1), Some(2), None, Some(4)]));
963
964        let err = StructArray::try_from(vec![("f1", strings.clone()), ("f2", ints.clone())])
965            .unwrap_err()
966            .to_string();
967
968        assert_eq!(
969            err,
970            "Invalid argument error: Incorrect array length for StructArray field \"f2\", expected 3 got 4"
971        )
972    }
973
974    #[test]
975    #[should_panic(
976        expected = "Incorrect datatype for StructArray field \\\"b\\\", expected Int16 got Boolean"
977    )]
978    fn test_struct_array_from_mismatched_types_single() {
979        drop(StructArray::from(vec![(
980            Arc::new(Field::new("b", DataType::Int16, false)),
981            Arc::new(BooleanArray::from(vec![false, false, true, true])) as Arc<dyn Array>,
982        )]));
983    }
984
985    #[test]
986    #[should_panic(
987        expected = "Incorrect datatype for StructArray field \\\"b\\\", expected Int16 got Boolean"
988    )]
989    fn test_struct_array_from_mismatched_types_multiple() {
990        drop(StructArray::from(vec![
991            (
992                Arc::new(Field::new("b", DataType::Int16, false)),
993                Arc::new(BooleanArray::from(vec![false, false, true, true])) as Arc<dyn Array>,
994            ),
995            (
996                Arc::new(Field::new("c", DataType::Utf8, false)),
997                Arc::new(Int32Array::from(vec![42, 28, 19, 31])),
998            ),
999        ]));
1000    }
1001
1002    #[test]
1003    fn test_struct_array_slice() {
1004        let boolean_data = ArrayData::builder(DataType::Boolean)
1005            .len(5)
1006            .add_buffer(Buffer::from([0b00010000]))
1007            .null_bit_buffer(Some(Buffer::from([0b00010001])))
1008            .build()
1009            .unwrap();
1010        let int_data = ArrayData::builder(DataType::Int32)
1011            .len(5)
1012            .add_buffer(Buffer::from([0, 28, 42, 0, 0].to_byte_slice()))
1013            .null_bit_buffer(Some(Buffer::from([0b00000110])))
1014            .build()
1015            .unwrap();
1016
1017        let field_types = vec![
1018            Field::new("a", DataType::Boolean, true),
1019            Field::new("b", DataType::Int32, true),
1020        ];
1021        let struct_array_data = ArrayData::builder(DataType::Struct(field_types.into()))
1022            .len(5)
1023            .add_child_data(boolean_data.clone())
1024            .add_child_data(int_data.clone())
1025            .null_bit_buffer(Some(Buffer::from([0b00010111])))
1026            .build()
1027            .unwrap();
1028        let struct_array = StructArray::from(struct_array_data);
1029
1030        assert_eq!(5, struct_array.len());
1031        assert_eq!(1, struct_array.null_count());
1032        assert!(struct_array.is_valid(0));
1033        assert!(struct_array.is_valid(1));
1034        assert!(struct_array.is_valid(2));
1035        assert!(struct_array.is_null(3));
1036        assert!(struct_array.is_valid(4));
1037        assert_eq!(boolean_data, struct_array.column(0).to_data());
1038        assert_eq!(int_data, struct_array.column(1).to_data());
1039
1040        let c0 = struct_array.column(0);
1041        let c0 = c0.as_any().downcast_ref::<BooleanArray>().unwrap();
1042        assert_eq!(5, c0.len());
1043        assert_eq!(3, c0.null_count());
1044        assert!(c0.is_valid(0));
1045        assert!(!c0.value(0));
1046        assert!(c0.is_null(1));
1047        assert!(c0.is_null(2));
1048        assert!(c0.is_null(3));
1049        assert!(c0.is_valid(4));
1050        assert!(c0.value(4));
1051
1052        let c1 = struct_array.column(1);
1053        let c1 = c1.as_any().downcast_ref::<Int32Array>().unwrap();
1054        assert_eq!(5, c1.len());
1055        assert_eq!(3, c1.null_count());
1056        assert!(c1.is_null(0));
1057        assert!(c1.is_valid(1));
1058        assert_eq!(28, c1.value(1));
1059        assert!(c1.is_valid(2));
1060        assert_eq!(42, c1.value(2));
1061        assert!(c1.is_null(3));
1062        assert!(c1.is_null(4));
1063
1064        let sliced_array = struct_array.slice(2, 3);
1065        let sliced_array = sliced_array.as_any().downcast_ref::<StructArray>().unwrap();
1066        assert_eq!(3, sliced_array.len());
1067        assert_eq!(1, sliced_array.null_count());
1068        assert!(sliced_array.is_valid(0));
1069        assert!(sliced_array.is_null(1));
1070        assert!(sliced_array.is_valid(2));
1071
1072        let sliced_c0 = sliced_array.column(0);
1073        let sliced_c0 = sliced_c0.as_any().downcast_ref::<BooleanArray>().unwrap();
1074        assert_eq!(3, sliced_c0.len());
1075        assert!(sliced_c0.is_null(0));
1076        assert!(sliced_c0.is_null(1));
1077        assert!(sliced_c0.is_valid(2));
1078        assert!(sliced_c0.value(2));
1079
1080        let sliced_c1 = sliced_array.column(1);
1081        let sliced_c1 = sliced_c1.as_any().downcast_ref::<Int32Array>().unwrap();
1082        assert_eq!(3, sliced_c1.len());
1083        assert!(sliced_c1.is_valid(0));
1084        assert_eq!(42, sliced_c1.value(0));
1085        assert!(sliced_c1.is_null(1));
1086        assert!(sliced_c1.is_null(2));
1087    }
1088
1089    #[test]
1090    #[should_panic(
1091        expected = "Incorrect array length for StructArray field \\\"c\\\", expected 1 got 2"
1092    )]
1093    fn test_invalid_struct_child_array_lengths() {
1094        drop(StructArray::from(vec![
1095            (
1096                Arc::new(Field::new("b", DataType::Float32, false)),
1097                Arc::new(Float32Array::from(vec![1.1])) as Arc<dyn Array>,
1098            ),
1099            (
1100                Arc::new(Field::new("c", DataType::Float64, false)),
1101                Arc::new(Float64Array::from(vec![2.2, 3.3])),
1102            ),
1103        ]));
1104    }
1105
1106    #[test]
1107    #[should_panic(expected = "use StructArray::try_new_with_length")]
1108    fn test_struct_array_from_empty() {
1109        // This can't work because we don't know how many rows the array should have.  Previously we inferred 0 but
1110        // that often led to bugs.
1111        let _ = StructArray::from(vec![]);
1112    }
1113
1114    #[test]
1115    fn test_empty_struct_array() {
1116        assert!(StructArray::try_new(Fields::empty(), vec![], None).is_err());
1117
1118        let arr = StructArray::new_empty_fields(10, None);
1119        assert_eq!(arr.len(), 10);
1120        assert_eq!(arr.null_count(), 0);
1121        assert_eq!(arr.num_columns(), 0);
1122
1123        let arr2 = StructArray::try_new_with_length(Fields::empty(), vec![], None, 10).unwrap();
1124        assert_eq!(arr2.len(), 10);
1125
1126        let arr = StructArray::new_empty_fields(10, Some(NullBuffer::new_null(10)));
1127        assert_eq!(arr.len(), 10);
1128        assert_eq!(arr.null_count(), 10);
1129        assert_eq!(arr.num_columns(), 0);
1130
1131        let arr2 = StructArray::try_new_with_length(
1132            Fields::empty(),
1133            vec![],
1134            Some(NullBuffer::new_null(10)),
1135            10,
1136        )
1137        .unwrap();
1138        assert_eq!(arr2.len(), 10);
1139    }
1140
1141    #[test]
1142    #[should_panic(expected = "Found unmasked nulls for non-nullable StructArray field \\\"c\\\"")]
1143    fn test_struct_array_from_mismatched_nullability() {
1144        drop(StructArray::from(vec![(
1145            Arc::new(Field::new("c", DataType::Int32, false)),
1146            Arc::new(Int32Array::from(vec![Some(42), None, Some(19)])) as ArrayRef,
1147        )]));
1148    }
1149
1150    #[test]
1151    fn test_struct_array_non_nullable_null_array_with_max_length() {
1152        // A non-nullable field backed by a NullArray of `usize::MAX` length
1153        // should be rejected with an error, not panic trying to materialize
1154        // a null buffer of ~2.3 EB
1155        let fields = Fields::from(vec![Field::new("a", DataType::Null, false)]);
1156        let array = Arc::new(NullArray::new(usize::MAX)) as ArrayRef;
1157
1158        let err =
1159            StructArray::try_new_with_length(fields, vec![array], None, usize::MAX).unwrap_err();
1160        assert_eq!(
1161            err.to_string(),
1162            "Invalid argument error: Found unmasked nulls for non-nullable StructArray field \"a\"",
1163        );
1164    }
1165
1166    #[test]
1167    fn test_struct_array_fmt_debug() {
1168        let arr = StructArray::new(
1169            vec![Arc::new(Field::new("c", DataType::Int32, true))].into(),
1170            vec![Arc::new(Int32Array::from((0..30).collect::<Vec<_>>())) as ArrayRef],
1171            Some(NullBuffer::new(BooleanBuffer::from(
1172                (0..30).map(|i| i % 2 == 0).collect::<Vec<_>>(),
1173            ))),
1174        );
1175        assert_eq!(
1176            format!("{arr:?}"),
1177            "StructArray\n-- validity:\n[\n  valid,\n  null,\n  valid,\n  null,\n  valid,\n  null,\n  valid,\n  null,\n  valid,\n  null,\n  ...10 elements...,\n  valid,\n  null,\n  valid,\n  null,\n  valid,\n  null,\n  valid,\n  null,\n  valid,\n  null,\n]\n[\n-- child 0: \"c\" (Int32)\nPrimitiveArray<Int32>\n[\n  0,\n  1,\n  2,\n  3,\n  4,\n  5,\n  6,\n  7,\n  8,\n  9,\n  ...10 elements...,\n  20,\n  21,\n  22,\n  23,\n  24,\n  25,\n  26,\n  27,\n  28,\n  29,\n]\n]"
1178        )
1179    }
1180
1181    #[test]
1182    fn test_struct_array_logical_nulls() {
1183        // Field is non-nullable
1184        let field = Field::new("a", DataType::Int32, false);
1185        let values = vec![1, 2, 3];
1186        // Create a NullBuffer with all bits set to valid (true)
1187        let nulls = NullBuffer::from(vec![true, true, true]);
1188        let array = Int32Array::new(values.into(), Some(nulls));
1189        let child = Arc::new(array) as ArrayRef;
1190        assert!(child.logical_nulls().is_some());
1191        assert_eq!(child.logical_nulls().unwrap().null_count(), 0);
1192
1193        let fields = Fields::from(vec![field]);
1194        let arrays = vec![child];
1195        let nulls = None;
1196
1197        StructArray::try_new(fields, arrays, nulls).expect("should not error");
1198    }
1199
1200    #[test]
1201    fn test_flatten_no_nulls() {
1202        let child = Arc::new(Int32Array::from(vec![1, 2, 3])) as ArrayRef;
1203        let sa = StructArray::from(vec![(
1204            Arc::new(Field::new("a", DataType::Int32, false)),
1205            child,
1206        )]);
1207
1208        let (fields, columns) = sa.flatten();
1209
1210        assert_eq!(columns.len(), 1);
1211        assert!(!fields[0].is_nullable());
1212        assert_eq!(columns[0].null_count(), 0);
1213        assert_eq!(columns[0].len(), 3);
1214    }
1215
1216    #[test]
1217    fn test_flatten_struct_nulls_child_no_nulls() {
1218        let child = Arc::new(Int32Array::from(vec![1, 2, 3])) as ArrayRef;
1219        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, false, true]));
1220        let sa = StructArray::new(
1221            Fields::from(vec![Field::new("a", DataType::Int32, false)]),
1222            vec![child],
1223            Some(struct_nulls),
1224        );
1225
1226        let (fields, columns) = sa.flatten();
1227
1228        assert!(fields[0].is_nullable());
1229        assert!(columns[0].is_valid(0));
1230        assert!(columns[0].is_null(1));
1231        assert!(columns[0].is_valid(2));
1232        assert_eq!(columns[0].null_count(), 1);
1233    }
1234
1235    #[test]
1236    fn test_flatten_both_have_nulls() {
1237        // struct validity: [valid, null,  valid, valid]
1238        // child validity:  [valid, valid, null,  valid]
1239        // expected:        [valid, null,  null,  valid]
1240        let child = Arc::new(Int32Array::from(vec![Some(1), Some(2), None, Some(4)])) as ArrayRef;
1241        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, false, true, true]));
1242        let sa = StructArray::new(
1243            Fields::from(vec![Field::new("a", DataType::Int32, true)]),
1244            vec![child],
1245            Some(struct_nulls),
1246        );
1247
1248        let (fields, columns) = sa.flatten();
1249
1250        assert!(fields[0].is_nullable());
1251        assert!(columns[0].is_valid(0));
1252        assert!(columns[0].is_null(1));
1253        assert!(columns[0].is_null(2));
1254        assert!(columns[0].is_valid(3));
1255        assert_eq!(columns[0].null_count(), 2);
1256    }
1257
1258    #[test]
1259    fn test_flatten_sliced_struct() {
1260        let child = Arc::new(Int32Array::from(vec![1, 2, 3, 4])) as ArrayRef;
1261        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, false, true, false]));
1262        let sa = StructArray::new(
1263            Fields::from(vec![Field::new("a", DataType::Int32, false)]),
1264            vec![child],
1265            Some(struct_nulls),
1266        );
1267        let sliced = sa.slice(1, 2);
1268
1269        let (fields, columns) = sliced.flatten();
1270
1271        assert!(fields[0].is_nullable());
1272        assert_eq!(columns[0].len(), 2);
1273        assert!(columns[0].is_null(0));
1274        assert!(columns[0].is_valid(1));
1275    }
1276
1277    #[test]
1278    fn test_flatten_multiple_children() {
1279        let int_child = Arc::new(Int32Array::from(vec![Some(1), Some(2), None])) as ArrayRef;
1280        let str_child = Arc::new(StringArray::from(vec![Some("a"), None, Some("c")])) as ArrayRef;
1281        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, false, true]));
1282        let sa = StructArray::new(
1283            Fields::from(vec![
1284                Field::new("ints", DataType::Int32, true),
1285                Field::new("strs", DataType::Utf8, true),
1286            ]),
1287            vec![int_child, str_child],
1288            Some(struct_nulls),
1289        );
1290
1291        let (fields, columns) = sa.flatten();
1292
1293        assert_eq!(fields.len(), 2);
1294        // int: [valid, null(struct), null(child)] => null_count=2
1295        assert_eq!(columns[0].null_count(), 2);
1296        assert!(columns[0].is_valid(0));
1297        assert!(columns[0].is_null(1));
1298        assert!(columns[0].is_null(2));
1299        // str: [valid, null(struct+child), valid] => null_count=1
1300        assert_eq!(columns[1].null_count(), 1);
1301        assert!(columns[1].is_valid(0));
1302        assert!(columns[1].is_null(1));
1303        assert!(columns[1].is_valid(2));
1304    }
1305
1306    #[test]
1307    fn test_flatten_empty_struct() {
1308        let sa = StructArray::new_empty_fields(5, Some(NullBuffer::new_null(5)));
1309
1310        let (fields, columns) = sa.flatten();
1311
1312        assert_eq!(fields.len(), 0);
1313        assert_eq!(columns.len(), 0);
1314    }
1315
1316    #[test]
1317    fn test_flatten_field_nullability_update() {
1318        let non_null_child = Arc::new(Int32Array::from(vec![1, 2, 3])) as ArrayRef;
1319        let nullable_child = Arc::new(Int32Array::from(vec![Some(1), None, Some(3)])) as ArrayRef;
1320        let struct_nulls = NullBuffer::new(BooleanBuffer::from(vec![true, true, false]));
1321        let sa = StructArray::new(
1322            Fields::from(vec![
1323                Field::new("non_null", DataType::Int32, false),
1324                Field::new("nullable", DataType::Int32, true),
1325            ]),
1326            vec![non_null_child, nullable_child],
1327            Some(struct_nulls),
1328        );
1329
1330        let (fields, _columns) = sa.flatten();
1331
1332        assert!(fields[0].is_nullable()); // was false, now true
1333        assert!(fields[1].is_nullable()); // was true, stays true
1334    }
1335}