Struct SchemaBuilder

pub struct SchemaBuilder {
    fields: Vec<Arc<Field>>,
    metadata: Metadata,
}

Expand description

A builder to facilitate building a Schema iteratively from FieldRef

§Examples

Build a schema from scratch:

let schema = {
    let mut builder = SchemaBuilder::new();
    builder.push(Field::new("id", DataType::Int64, false));
    builder.push(Field::new("name", DataType::Utf8, true));
    builder.finish()
};
assert_eq!(schema.fields().len(), 2);

Derive a new schema from an existing one, keeping all fields and metadata while appending new columns:

let base = Schema::new_with_metadata(
    vec![
        Field::new("id", DataType::Int64, false),
        Field::new("name", DataType::Utf8, true),
    ],
    [("created_by", "myapp")],
);

// Build a new schema that extends `base` with an extra field.
let mut builder = SchemaBuilder::from(&base); // copies all fields *and* metadata.
builder.push(Field::new("score", DataType::Float64, true));
let extended = builder.finish();

assert_eq!(extended.fields().len(), 3);
assert_eq!(extended.field(0).name(), "id");     // original fields preserved
assert_eq!(extended.field(2).name(), "score");  // new field appended
assert_eq!(extended.metadata()["created_by"], "myapp"); // metadata carried over

Fields§

§fields: Vec<Arc<Field>>§metadata: Metadata

Implementations§

§

impl SchemaBuilder

pub fn new() -> SchemaBuilder

Creates a new empty SchemaBuilder

pub fn with_capacity(capacity: usize) -> SchemaBuilder

Creates a new empty SchemaBuilder with space for capacity fields

pub fn push(&mut self, field: impl Into<Arc<Field>>)

Appends a FieldRef to this SchemaBuilder without checking for collision

pub fn remove(&mut self, idx: usize) -> Arc<Field> ⓘ

Removes and returns the FieldRef as index idx

§Panics

Panics if index out of bounds

pub fn field(&mut self, idx: usize) -> &Arc<Field> ⓘ

Returns an immutable reference to the FieldRef at index idx

§Panics

Panics if index out of bounds

pub fn field_mut(&mut self, idx: usize) -> &mut Arc<Field> ⓘ

Returns a mutable reference to the FieldRef at index idx

§Example

let original = Schema::new(vec![
    Field::new("id", DataType::Int32, false),
    Field::new("value", DataType::Utf8, true),
]);

let mut builder = SchemaBuilder::from(&original);
// Widen the "id" column from Int32 to Int64
*builder.field_mut(0) = Arc::new(Field::new("id", DataType::Int64, false));
let widened = builder.finish();

assert_eq!(widened.field(0).data_type(), &DataType::Int64);
assert_eq!(widened.field(1).name(), "value"); // unchanged

§Panics

Panics if index out of bounds

pub fn metadata(&mut self) -> &Metadata

Returns an immutable reference to the Map of custom metadata key-value pairs.

pub fn metadata_mut(&mut self) -> &mut Metadata

Returns a mutable reference to the Map of custom metadata key-value pairs.

pub fn reverse(&mut self)

Reverse the fields

pub fn try_merge(&mut self, field: &Arc<Field>) -> Result<(), ArrowError>

Appends a FieldRef to this SchemaBuilder checking for collision

If an existing field exists with the same name, calls Field::try_merge

pub fn finish(self) -> Schema

Consume this SchemaBuilder yielding the final Schema

pub fn project(self, indices: &[usize]) -> Result<Schema, ArrowError>

Consume this SchemaBuilder yielding a Schema with fields reordered or subsetted according to indices.

Fields appear in the output in the order given by indices. Metadata is carried over from the builder unchanged.

§Errors

Returns an error if any index is out of bounds or if any index is repeated.

§Example: reorder fields

let schema = Schema::new(vec![
    Field::new("id", DataType::Int64, false),
    Field::new("name", DataType::Utf8, true),
    Field::new("score", DataType::Float64, true),
]);

let reordered = SchemaBuilder::from(&schema).project(&[2, 0, 1]).unwrap();
assert_eq!(reordered.field(0).name(), "score");
assert_eq!(reordered.field(1).name(), "id");
assert_eq!(reordered.field(2).name(), "name");

§Example: select a subset of fields

let schema = Schema::new(vec![
    Field::new("id", DataType::Int64, false),
    Field::new("name", DataType::Utf8, true),
    Field::new("score", DataType::Float64, true),
]);

let subset = SchemaBuilder::from(&schema).project(&[0, 2]).unwrap();
assert_eq!(subset.fields().len(), 2);
assert_eq!(subset.field(0).name(), "id");
assert_eq!(subset.field(1).name(), "score");