Struct StructArray
pub struct StructArray {
len: usize,
data_type: DataType,
nulls: Option<NullBuffer>,
fields: Vec<Arc<dyn Array>>,
}
Expand description
An array of structs
Each child (called field) is represented by a separate array.
§Comparison with RecordBatch
Both RecordBatch
and StructArray
represent a collection of columns / arrays with the
same length.
However, there are a couple of key differences:
StructArray
can be nested within otherArray
, including itselfRecordBatch
can contain top-level metadata on its associatedSchema
StructArray
can contain top-level nulls, i.e.null
RecordBatch
can only represent nulls in its child columns, i.e.{"field": null}
StructArray
is therefore a more general data container than RecordBatch
, and as such
code that needs to handle both will typically share an implementation in terms of
StructArray
and convert to/from RecordBatch
as necessary.
From
implementations are provided to facilitate this conversion, however, converting
from a StructArray
containing top-level nulls to a RecordBatch
will panic, as there
is no way to preserve them.
§Example: Create an array from a vector of fields
use std::sync::Arc;
use arrow_array::{Array, ArrayRef, BooleanArray, Int32Array, StructArray};
use arrow_schema::{DataType, Field};
let boolean = Arc::new(BooleanArray::from(vec![false, false, true, true]));
let int = Arc::new(Int32Array::from(vec![42, 28, 19, 31]));
let struct_array = StructArray::from(vec![
(
Arc::new(Field::new("b", DataType::Boolean, false)),
boolean.clone() as ArrayRef,
),
(
Arc::new(Field::new("c", DataType::Int32, false)),
int.clone() as ArrayRef,
),
]);
assert_eq!(struct_array.column(0).as_ref(), boolean.as_ref());
assert_eq!(struct_array.column(1).as_ref(), int.as_ref());
assert_eq!(4, struct_array.len());
assert_eq!(0, struct_array.null_count());
assert_eq!(0, struct_array.offset());
Fields§
§len: usize
§data_type: DataType
§nulls: Option<NullBuffer>
§fields: Vec<Arc<dyn Array>>
Implementations§
§impl StructArray
impl StructArray
pub fn new(
fields: Fields,
arrays: Vec<Arc<dyn Array>>,
nulls: Option<NullBuffer>,
) -> StructArray
pub fn new( fields: Fields, arrays: Vec<Arc<dyn Array>>, nulls: Option<NullBuffer>, ) -> StructArray
Create a new StructArray
from the provided parts, panicking on failure
§Panics
Panics if Self::try_new
returns an error
pub fn try_new(
fields: Fields,
arrays: Vec<Arc<dyn Array>>,
nulls: Option<NullBuffer>,
) -> Result<StructArray, ArrowError>
pub fn try_new( fields: Fields, arrays: Vec<Arc<dyn Array>>, nulls: Option<NullBuffer>, ) -> Result<StructArray, ArrowError>
Create a new StructArray
from the provided parts, returning an error on failure
§Errors
Errors if
fields.len() != arrays.len()
fields[i].data_type() != arrays[i].data_type()
arrays[i].len() != arrays[j].len()
arrays[i].len() != nulls.len()
!fields[i].is_nullable() && !nulls.contains(arrays[i].nulls())
pub fn new_null(fields: Fields, len: usize) -> StructArray
pub fn new_null(fields: Fields, len: usize) -> StructArray
Create a new StructArray
of length len
where all values are null
pub unsafe fn new_unchecked(
fields: Fields,
arrays: Vec<Arc<dyn Array>>,
nulls: Option<NullBuffer>,
) -> StructArray
pub unsafe fn new_unchecked( fields: Fields, arrays: Vec<Arc<dyn Array>>, nulls: Option<NullBuffer>, ) -> StructArray
Create a new StructArray
from the provided parts without validation
§Safety
Safe if Self::new
would not panic with the given arguments
pub fn new_empty_fields(len: usize, nulls: Option<NullBuffer>) -> StructArray
pub fn new_empty_fields(len: usize, nulls: Option<NullBuffer>) -> StructArray
pub fn into_parts(self) -> (Fields, Vec<Arc<dyn Array>>, Option<NullBuffer>)
pub fn into_parts(self) -> (Fields, Vec<Arc<dyn Array>>, Option<NullBuffer>)
Deconstruct this array into its constituent parts
pub fn num_columns(&self) -> usize
pub fn num_columns(&self) -> usize
Return the number of fields in this struct array
pub fn column_names(&self) -> Vec<&str>
pub fn column_names(&self) -> Vec<&str>
Return field names in this struct array
pub fn fields(&self) -> &Fields
pub fn fields(&self) -> &Fields
Returns the Fields
of this StructArray
pub fn column_by_name(&self, column_name: &str) -> Option<&Arc<dyn Array>>
pub fn column_by_name(&self, column_name: &str) -> Option<&Arc<dyn Array>>
Return child array whose field name equals to column_name
Note: A schema can currently have duplicate field names, in which case the first field will always be selected. This issue will be addressed in ARROW-11178
pub fn slice(&self, offset: usize, len: usize) -> StructArray
pub fn slice(&self, offset: usize, len: usize) -> StructArray
Returns a zero-copy slice of this array with the indicated offset and length.
Trait Implementations§
§impl Array for StructArray
impl Array for StructArray
§fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
fn slice(&self, offset: usize, length: usize) -> Arc<dyn Array>
§fn shrink_to_fit(&mut self)
fn shrink_to_fit(&mut self)
§fn offset(&self) -> usize
fn offset(&self) -> usize
0
. Read more§fn nulls(&self) -> Option<&NullBuffer>
fn nulls(&self) -> Option<&NullBuffer>
§fn logical_null_count(&self) -> usize
fn logical_null_count(&self) -> usize
§fn get_buffer_memory_size(&self) -> usize
fn get_buffer_memory_size(&self) -> usize
§fn get_array_memory_size(&self) -> usize
fn get_array_memory_size(&self) -> usize
get_buffer_memory_size()
and
includes the overhead of the data structures that contain the pointers to the various buffers.§fn logical_nulls(&self) -> Option<NullBuffer>
fn logical_nulls(&self) -> Option<NullBuffer>
NullBuffer
that represents the logical
null values of this array, if any. Read more§fn null_count(&self) -> usize
fn null_count(&self) -> usize
§fn is_nullable(&self) -> bool
fn is_nullable(&self) -> bool
false
if the array is guaranteed to not contain any logical nulls Read more§impl Clone for StructArray
impl Clone for StructArray
§fn clone(&self) -> StructArray
fn clone(&self) -> StructArray
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more§impl Debug for StructArray
impl Debug for StructArray
§impl From<&StructArray> for RecordBatch
impl From<&StructArray> for RecordBatch
§fn from(struct_array: &StructArray) -> RecordBatch
fn from(struct_array: &StructArray) -> RecordBatch
§impl From<ArrayData> for StructArray
impl From<ArrayData> for StructArray
§fn from(data: ArrayData) -> StructArray
fn from(data: ArrayData) -> StructArray
§impl From<RecordBatch> for StructArray
impl From<RecordBatch> for StructArray
§fn from(value: RecordBatch) -> StructArray
fn from(value: RecordBatch) -> StructArray
§impl From<StructArray> for ArrayData
impl From<StructArray> for ArrayData
§fn from(array: StructArray) -> ArrayData
fn from(array: StructArray) -> ArrayData
§impl From<StructArray> for RecordBatch
impl From<StructArray> for RecordBatch
§fn from(value: StructArray) -> RecordBatch
fn from(value: StructArray) -> RecordBatch
§impl Index<&str> for StructArray
impl Index<&str> for StructArray
§fn index(&self, name: &str) -> &<StructArray as Index<&str>>::Output
fn index(&self, name: &str) -> &<StructArray as Index<&str>>::Output
Get a reference to a column’s array by name.
Note: A schema can currently have duplicate field names, in which case the first field will always be selected. This issue will be addressed in ARROW-11178
§Panics
Panics if the name is not in the schema.
§impl PartialEq for StructArray
impl PartialEq for StructArray
§impl TryFrom<Vec<(&str, Arc<dyn Array>)>> for StructArray
impl TryFrom<Vec<(&str, Arc<dyn Array>)>> for StructArray
§fn try_from(
values: Vec<(&str, Arc<dyn Array>)>,
) -> Result<StructArray, ArrowError>
fn try_from( values: Vec<(&str, Arc<dyn Array>)>, ) -> Result<StructArray, ArrowError>
builds a StructArray from a vector of names and arrays.