Struct StructDataParts 

pub struct StructDataParts {
    pub struct_fields: StructFields,
    pub fields: Arc<[ArrayRef]>,
    pub validity: Validity,
}

A struct array that stores multiple named fields as columns, similar to a database row.

This mirrors the Apache Arrow Struct array encoding and provides a columnar representation of structured data where each row contains multiple named fields of potentially different types.

Data Layout

The struct array uses a columnar layout where:

• Each field is stored as a separate child array
• All fields must have the same length (number of rows)
• Field names and types are defined in the struct’s dtype
• An optional validity mask indicates which entire rows are null

Row-level nulls

The StructArray contains its own top-level nulls, which are superimposed on top of the field-level validity values. This can be the case even if the fields themselves are non-nullable, accessing a particular row can yield nulls even if all children are valid at that position.

use vortex_array::arrays::{StructArray, BoolArray};
use vortex_array::validity::Validity;
use vortex_array::dtype::FieldNames;
use vortex_array::IntoArray;
use vortex_buffer::buffer;

// Create struct with all non-null fields but struct-level nulls
let struct_array = StructArray::try_new(
    FieldNames::from(["a", "b", "c"]),
    vec![
        buffer![1i32, 2i32].into_array(),  // non-null field a
        buffer![10i32, 20i32].into_array(), // non-null field b
        buffer![100i32, 200i32].into_array(), // non-null field c
    ],
    2,
    Validity::Array(BoolArray::from_iter([true, false]).into_array()), // row 1 is null
).unwrap();

// Row 0 is valid - returns a struct scalar with field values
let row0 = struct_array.scalar_at(0).unwrap();
assert!(!row0.is_null());

// Row 1 is null at struct level - returns null even though fields have values
let row1 = struct_array.scalar_at(1).unwrap();
assert!(row1.is_null());

Name uniqueness

It is valid for a StructArray to have multiple child columns that have the same name. In this case, any accessors that use column names will find the first column in sequence with the name.

use vortex_array::arrays::StructArray;
use vortex_array::arrays::struct_::StructArrayExt;
use vortex_array::validity::Validity;
use vortex_array::dtype::FieldNames;
use vortex_array::IntoArray;
use vortex_buffer::buffer;

// Create struct with duplicate "data" field names
let struct_array = StructArray::try_new(
    FieldNames::from(["data", "data"]),
    vec![
        buffer![1i32, 2i32].into_array(),   // first "data"
        buffer![3i32, 4i32].into_array(),   // second "data"
    ],
    2,
    Validity::NonNullable,
).unwrap();

// field_by_name returns the FIRST "data" field
let first_data = struct_array.unmasked_field_by_name("data").unwrap();
assert_eq!(first_data.scalar_at(0).unwrap(), 1i32.into());

Field Operations

Struct arrays support efficient column operations:

• Projection: Select/reorder fields without copying data
• Field access: Get columns by name or index
• Column addition: Add new fields to create extended structs
• Column removal: Remove fields to create narrower structs

Validity Semantics

• Row-level nulls are tracked in the struct’s validity child
• Individual field nulls are tracked in each field’s own validity
• A null struct row means all fields in that row are conceptually null
• Field-level nulls can exist independently of struct-level nulls

Examples

use vortex_array::arrays::{StructArray, PrimitiveArray};
use vortex_array::arrays::struct_::StructArrayExt;
use vortex_array::validity::Validity;
use vortex_array::dtype::FieldNames;
use vortex_array::IntoArray;
use vortex_buffer::buffer;

// Create arrays for each field
let ids = PrimitiveArray::new(buffer![1i32, 2, 3], Validity::NonNullable);
let names = PrimitiveArray::new(buffer![100u64, 200, 300], Validity::NonNullable);

// Create struct array with named fields
let struct_array = StructArray::try_new(
    FieldNames::from(["id", "score"]),
    vec![ids.into_array(), names.into_array()],
    3,
    Validity::NonNullable,
).unwrap();

assert_eq!(struct_array.len(), 3);
assert_eq!(struct_array.names().len(), 2);

// Access field by name
let id_field = struct_array.unmasked_field_by_name("id").unwrap();
assert_eq!(id_field.len(), 3);

Fields

struct_fields: StructFields

fields: Arc<[ArrayRef]>

validity: Validity