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 { makeBuilder, 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.

Type Parameters

Constructors

constructor

Properties

children finished length nullValues? stride type

Accessors

ArrayType byteLength nullBitmap nullCount numChildren reservedByteLength reservedLength typeIds valueOffsets values

Methods

addChild append clear finish flush getChildAt isValid set setValid setValue toVector throughDOM throughNode

Constructors

constructor

  • new Builder<T, TNull>(options): Builder<T, TNull>

  • Construct a builder with the given Arrow DataType with optional null values, which will be interpreted as "null" when set or appended to the Builder.

    Type Parameters

    Parameters

    • options: BuilderOptions<T, TNull>

      A BuilderOptions object used to create this Builder.

    Returns Builder<T, TNull>

Properties

Readonlychildren

children: Builder<any, any>[]

Readonlyfinished

finished: boolean = false

A boolean indicating whether Builder.prototype.finish() has been called on this Builder.

Readonlylength

length: number = 0

The number of values written to the Builder that haven't been flushed yet.

Optional ReadonlynullValues

nullValues?: null | TNull[] | readonly TNull[]

The list of null-value sentinels for this Builder. When one of these values is written to the Builder (either via Builder.prototype.set() or Builder.prototype.append()), a 1-bit is written to this Builder's underlying null BitmapBufferBuilder.

Readonlystride

stride: number

The number of elements in the underlying values TypedArray that represent a single logical element, determined by this Builder's DataType. This is 1 for most types, but is larger when the DataType is Int64, Uint64, Decimal, DateMillisecond, certain variants of Interval, Time, or Timestamp, FixedSizeBinary, and FixedSizeList.

Readonlytype

type: T

The Builder's DataType instance.

Accessors

ArrayType

  • get ArrayType(): any

  • Returns any

byteLength

  • get byteLength(): number

  • Returns number

    The aggregate length (in bytes) of the values that have been written.

nullBitmap

  • get nullBitmap(): null | Uint8Array

  • Returns null | Uint8Array

nullCount

  • get nullCount(): number

  • Returns number

numChildren

  • get numChildren(): number

  • Returns number

reservedByteLength

  • get reservedByteLength(): number

  • Returns number

    The aggregate length (in bytes) that has been reserved to write new values.

reservedLength

  • get reservedLength(): number

  • Returns number

    The aggregate number of rows that have been reserved to write new values.

typeIds

  • get typeIds(): null | Int8Array

  • Returns null | Int8Array

valueOffsets

  • get valueOffsets(): null | T["TOffsetArray"]

  • Returns null | T["TOffsetArray"]

values

  • get values(): null | T["TArray"]

  • Returns null | T["TArray"]

Methods

addChild

  • addChild(child, name?): void

  • Parameters

    • child: Builder<any, any>
    • name: string = ...

    Returns void

append

  • append(value): Builder<T, TNull>

  • Appends a value (or null) to this Builder. This is equivalent to builder.set(builder.length, value).

    Parameters

    • value: TNull | T["TValue"]

      The value to append.

    Returns Builder<T, TNull>

clear

  • clear(): Builder<T, TNull>

  • Clear this Builder's internal state, including child Builders if applicable, and reset the length to 0.

    Returns Builder<T, TNull>

    The cleared Builder instance.

finish

  • finish(): Builder<T, TNull>

  • Finalize this Builder, and child builders if applicable.

    Returns Builder<T, TNull>

    The finalized Builder instance.

flush

  • flush(): Data<T>

  • Commit all the values that have been written to their underlying ArrayBuffers, including any child Builders if applicable, and reset the internal Builder state.

    Returns Data<T>

    A Data<T> of the buffers and children representing the values written.

getChildAt

  • getChildAt<R>(index): null | Builder<R, any>

  • Retrieve the child Builder at the supplied index, or null if no child exists at that index.

    Type Parameters

    Parameters

    • index: number

      The index of the child Builder to retrieve.

    Returns null | Builder<R, any>

    The child Builder at the supplied index or null.

isValid

  • isValid(value): boolean

  • Validates whether a value is valid (true), or null (false)

    Parameters

    • value: TNull | T["TValue"]

      The value to compare against null the value representations

    Returns boolean

set

  • set(index, value): Builder<T, TNull>

  • Write a value (or null-value sentinel) at the supplied index. If the value matches one of the null-value representations, a 1-bit is written to the null BitmapBufferBuilder. Otherwise, a 0 is written to the null BitmapBufferBuilder, and the value is passed to Builder.prototype.setValue().

    Parameters

    • index: number

      The index of the value to write.

    • value: TNull | T["TValue"]

      The value to write at the supplied index.

    Returns Builder<T, TNull>

    The updated Builder instance.

setValid

  • setValid(index, valid): boolean

  • Parameters

    • index: number
    • valid: boolean

    Returns boolean

setValue

  • setValue(index, value): void

  • Write a value to the underlying buffers at the supplied index, bypassing the null-value check. This is a low-level method that

    Parameters

    • index: number
    • value: T["TValue"]

    Returns void

toVector

  • toVector(): Vector<T>

  • Flush the Builder and return a Vector<T>.

    Returns Vector<T>

    A Vector<T> of the flushed values.

StaticthroughDOM

  • throughDOM<T, TNull>(options): BuilderTransform<T, TNull>

  • Type Parameters

    Parameters

    • options: BuilderTransformOptions<T, TNull>

    Returns BuilderTransform<T, TNull>

    Nocollapse

StaticthroughNode

  • throughNode<T, TNull>(options): Duplex

  • Type Parameters

    Parameters

    • options: BuilderDuplexOptions<T, TNull>

    Returns Duplex

    Nocollapse

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods