Struct VariantArrayBuilder

pub struct VariantArrayBuilder {
    nulls: NullBufferBuilder,
    metadata_buffer: Vec<u8>,
    metadata_locations: Vec<(usize, usize)>,
    value_buffer: Vec<u8>,
    value_locations: Vec<(usize, usize)>,
    fields: Fields,
}

A builder for VariantArray

This builder is used to construct a VariantArray and allows APIs for adding metadata

This builder always creates a VariantArray using [BinaryViewArray] for both the metadata and value fields.

TODO

1. Support shredding: https://github.com/apache/arrow-rs/issues/7895

Example:

// Create a new VariantArrayBuilder with a capacity of 100 rows
let mut builder = VariantArrayBuilder::new(100);
// append variant values
builder.append_variant(Variant::from(42));
// append a null row (note not a Variant::Null)
builder.append_null();
// append an object to the builder
let mut vb = builder.variant_builder();
vb.new_object()
  .with_field("foo", "bar")
  .finish()
  .unwrap();
 vb.finish(); // must call finish to write the variant to the buffers

// create the final VariantArray
let variant_array = builder.build();
assert_eq!(variant_array.len(), 3);
// // Access the values
// row 1 is not null and is an integer
assert!(!variant_array.is_null(0));
assert_eq!(variant_array.value(0), Variant::from(42i32));
// row 1 is null
assert!(variant_array.is_null(1));
// row 2 is not null and is an object
assert!(!variant_array.is_null(2));
let value = variant_array.value(2);
let obj = value.as_object().expect("expected object");
assert_eq!(obj.get("foo"), Some(Variant::from("bar")));

Fields

nulls: NullBufferBuilder

Nulls

metadata_buffer: Vec<u8>

buffer for all the metadata

metadata_locations: Vec<(usize, usize)>

(offset, len) pairs for locations of metadata in the buffer

value_buffer: Vec<u8>

buffer for values

value_locations: Vec<(usize, usize)>

(offset, len) pairs for locations of values in the buffer

fields: Fields

The fields of the final StructArray

TODO: 1) Add extension type metadata TODO: 2) Add support for shredding

Implementations

impl VariantArrayBuilder

pub fn new(row_capacity: usize) -> Self

pub fn build(self) -> VariantArray

Build the final builder

pub fn append_null(&mut self)

Appends a null row to the builder.

pub fn append_variant(&mut self, variant: Variant<'_, '_>)

Append the [Variant] to the builder as the next row

pub fn variant_builder(&mut self) -> VariantArrayVariantBuilder<'_>

Return a VariantArrayVariantBuilder that writes directly to the buffers of this builder.

You must call VariantArrayVariantBuilder::finish to complete the builder

Example

let mut array_builder = VariantArrayBuilder::new(10);

// First row has a string
let mut variant_builder = array_builder.variant_builder();
variant_builder.append_value("Hello, World!");
// must call finish to write the variant to the buffers
variant_builder.finish();

// Second row is an object
let mut variant_builder = array_builder.variant_builder();
variant_builder
    .new_object()
    .with_field("my_field", 42i64)
    .finish()
    .unwrap();
variant_builder.finish();

// finalize the array
let variant_array: VariantArray = array_builder.build();

// verify what we wrote is still there
assert_eq!(variant_array.value(0), Variant::from("Hello, World!"));
assert!(variant_array.value(1).as_object().is_some());

Trait Implementations

impl Debug for VariantArrayBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.