1use 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#[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 pub fn new(fields: Fields, arrays: Vec<ArrayRef>, nulls: Option<NullBuffer>) -> Self {
78 Self::try_new(fields, arrays, nulls).unwrap()
79 }
80
81 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 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 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 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 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 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 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 pub fn column(&self, pos: usize) -> &ArrayRef {
275 &self.fields[pos]
276 }
277
278 pub fn num_columns(&self) -> usize {
280 self.fields.len()
281 }
282
283 pub fn columns(&self) -> &[ArrayRef] {
285 &self.fields
286 }
287
288 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 pub fn fields(&self) -> &Fields {
301 match self.data_type() {
302 DataType::Struct(f) => f,
303 _ => unreachable!(),
304 }
305 }
306
307 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 pub fn field(&self, pos: usize) -> &FieldRef {
320 &self.fields()[pos]
321 }
322
323 pub fn field_by_name(&self, field_name: &str) -> Option<&FieldRef> {
329 self.fields().find(field_name).map(|(_, field)| field)
330 }
331
332 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 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 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 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
473unsafe 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 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 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 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 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 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 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 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 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 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 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 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 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 #[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 #[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 ]));
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 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 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 let field = Field::new("a", DataType::Int32, false);
1185 let values = vec![1, 2, 3];
1186 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 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 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 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()); assert!(fields[1].is_nullable()); }
1335}