Class Builder<T, TNull>Abstract

An abstract base class for types that construct Arrow Vectors from arbitrary JavaScript values.

A Builder is responsible for writing arbitrary JavaScript values to ArrayBuffers and/or child Builders according to the Arrow specification for each DataType, creating or resizing the underlying ArrayBuffers as necessary.

The Builder for each Arrow DataType handles converting and appending values for a given DataType. The high-level makeBuilder() convenience method creates the specific Builder subclass for the supplied DataType.

Once created, Builder instances support both appending values to the end of the Builder, and random-access writes to specific indices (Builder.prototype.append(value) is a convenience method for builder.set(builder.length, value)). Appending or setting values beyond the Builder's current length may cause the builder to grow its underlying buffers or child Builders (if applicable) to accommodate the new values.

After enough values have been written to a Builder, Builder.prototype.flush() will commit the values to the underlying ArrayBuffers (or child Builders). The internal Builder state will be reset, and an instance of Data<T> is returned. Alternatively, Builder.prototype.toVector() will flush the Builder and return an instance of Vector<T> instead.

When there are no more values to write, use Builder.prototype.finish() to finalize the Builder. This does not reset the internal state, so it is necessary to call Builder.prototype.flush() or toVector() one last time if there are still values queued to be flushed.

Note: calling Builder.prototype.finish() is required when using a DictionaryBuilder, because this is when it flushes the values that have been enqueued in its internal dictionary's Builder, and creates the dictionaryVector for the Dictionary DataType.

Example

import { Builder, Utf8 } from 'apache-arrow';

const utf8Builder = makeBuilder({
    type: new Utf8(),
    nullValues: [null, 'n/a']
});

utf8Builder
    .append('hello')
    .append('n/a')
    .append('world')
    .append(null);

const utf8Vector = utf8Builder.finish().toVector();

console.log(utf8Vector.toJSON());
// > ["hello", null, "world", null]

Typeparam

T The DataType of this Builder.

Typeparam

TNull The type(s) of values which will be considered null-value sentinels.