Arrow types

On this page

The type factories, the erased facade shapes, and the predicates that discriminate them.

function binary

source

const binary = (): BinaryType => impl.binary() as unknown as BinaryType

function date

source

const date = (unit?: number): Date64Type => impl.date(unit) as unknown as Date64Type

function dateDay

source

const dateDay = (): Date32Type => impl.dateDay() as unknown as Date32Type

function dateMillisecond

source

const dateMillisecond = (): Date64Type => impl.dateMillisecond() as unknown as Date64Type

const DateUnit

source

DateUnit

function decimal

source

const decimal = (precision: number, scale: number, bitWidth?: 32 | 64 | 128 | 256): DecimalType =>
impl.decimal(precision, scale, bitWidth) as unknown as DecimalType

function decimal128

source

const decimal128 = (precision: number, scale: number): DecimalType =>
impl.decimal128(precision, scale) as unknown as DecimalType

function decimal256

source

const decimal256 = (precision: number, scale: number): DecimalType =>
impl.decimal256(precision, scale) as unknown as DecimalType

function denseUnion

source

const denseUnion = (
children: readonly (VgiField | VgiDataType)[],
typeIds?: number[],
): UnionType => impl.denseUnion(children as any, typeIds) as unknown as UnionType

function dictionary

source

export function dictionary<V extends VgiDataType>(
valueType: V,
indexType?: VgiDataType,
ordered?: boolean,
id?: number,
): DictionaryType<V>

function duration

source

export function duration<U extends TUnit = TUnit>(unit?: number): DurationType<U>

function durationMicros

source

const durationMicros = (): DurationType<"us"> =>
impl.duration(impl.TimeUnit.MICROSECOND) as unknown as DurationType<"us">

function durationMillis

source

const durationMillis = (): DurationType<"ms"> =>
impl.duration(impl.TimeUnit.MILLISECOND) as unknown as DurationType<"ms">

function durationNanos

source

const durationNanos = (): DurationType<"ns"> =>
impl.duration(impl.TimeUnit.NANOSECOND) as unknown as DurationType<"ns">

function durationSeconds

source

const durationSeconds = (): DurationType<"s"> =>
impl.duration(impl.TimeUnit.SECOND) as unknown as DurationType<"s">

function field

source

export function field<Name extends string, T extends VgiDataType>(
name: Name,
type: T,
nullable?: boolean,
metadata?: Map<string, string>,
): TypedField<Name, T>

Description

field(): preserve the precise name + type so struct() can carry a typed child tuple. Runtime is the backend field.

function fixedSizeBinary

source

const fixedSizeBinary = (byteWidth: number): FixedSizeBinaryType =>
impl.fixedSizeBinary(byteWidth) as unknown as FixedSizeBinaryType

function fixedSizeList

source

export function fixedSizeList<T extends VgiDataType>(
child: TypedField<string, T> | T,
listSize: number,
): FixedSizeListType<T>

function float16

source

const float16 = (): FloatType => impl.float16() as unknown as FloatType

function float64

source

const float64 = (): FloatType => impl.float64() as unknown as FloatType

function int16

source

const int16 = (): Int16Type => impl.int16() as unknown as Int16Type

function int64

source

const int64 = (): Int64Type => impl.int64() as unknown as Int64Type

function int8

source

const int8 = (): Int8Type => impl.int8() as unknown as Int8Type

function interval

source

const interval = (unit?: number): IntervalType => impl.interval(unit) as unknown as IntervalType

const IntervalUnit

source

IntervalUnit

function isBatch

source

export function isBatch(x: unknown): x is import(“./types.js”).VgiBatch

Description

Runtime check: does x quack like a VgiBatch? Used at API boundaries where callers may pass either a batch or a plain column dict. Duck-typed because arrow-js and flechette use unrelated classes.

function isBinary

source

export function isBinary(t: VgiDataType): boolean

function isBool

source

export function isBool(t: VgiDataType): boolean

function isDate

source

export function isDate(t: VgiDataType): boolean

function isDecimal

source

export function isDecimal(t: VgiDataType): boolean

function isDictionary

source

export function isDictionary(t: VgiDataType): boolean

function isDuration

source

export function isDuration(t: VgiDataType): boolean

function isFixedSizeBinary

source

export function isFixedSizeBinary(t: VgiDataType): boolean

function isFixedSizeList

source

export function isFixedSizeList(t: VgiDataType): boolean

function isFloat

source

export function isFloat(t: VgiDataType): boolean

function isInt

source

export function isInt(t: VgiDataType): boolean

function isInterval

source

export function isInterval(t: VgiDataType): boolean

function isList

source

export function isList(t: VgiDataType): boolean

function isMap

source

export function isMap(t: VgiDataType): boolean

function isNull

source

export function isNull(t: VgiDataType): boolean

function isStruct

source

export function isStruct(t: VgiDataType): boolean

function isTime

source

export function isTime(t: VgiDataType): boolean

function isTimestamp

source

export function isTimestamp(t: VgiDataType): boolean

function isUnion

source

export function isUnion(t: VgiDataType): boolean

function isUtf8

source

export function isUtf8(t: VgiDataType): boolean

function list

source

export function list<T extends VgiDataType>(child: TypedField<string, T> | T): ListType<T>

function map

source

export function map<K extends VgiDataType, V extends VgiDataType>(
keyField: TypedField<string, K> | K,
valueField: TypedField<string, V> | V,
keysSorted?: boolean,
): MapType<K, V>

function nullType

source

const nullType = (): NullDescriptor => impl.nullType() as unknown as NullDescriptor

const schema

source

schema

function sparseUnion

source

const sparseUnion = (
children: readonly (VgiField | VgiDataType)[],
typeIds?: number[],
): UnionType => impl.sparseUnion(children as any, typeIds) as unknown as UnionType

function struct

source

export function struct<const C extends readonly TypedField<string, VgiDataType>[]>(
children: C,
): StructType<C>

interface TaggedUnion

source

export interface TaggedUnion

Description

A decoded union-typed value: which member is active (tag) and its value.

DuckDB UNION / Arrow union values are tagged — the discriminator (which member is present) lives in the union’s per-row type code, not in the member value. A plain scalar read returns only the member value and drops that tag, so union values are decoded into this wrapper instead: tag is the active member’s field name (or null for a null union) and value is its decoded canonical value. Mirrors vgi-python’s vgi.arguments.TaggedUnion.

Fields

tagstring | null

valueunknown

function time

source

export function time(unit?: number, bitWidth?: 32 | 64): Time32Type<“s” | “ms”> | Time64Type<“us” | “ns”>

function timeMicrosecond

source

const timeMicrosecond = (): Time64Type<“us”> => impl.timeMicrosecond() as unknown as Time64Type<“us”>

function timeMillisecond

source

const timeMillisecond = (): Time32Type<“ms”> => impl.timeMillisecond() as unknown as Time32Type<“ms”>

function timeNanosecond

source

const timeNanosecond = (): Time64Type<“ns”> => impl.timeNanosecond() as unknown as Time64Type<“ns”>

function timeSecond

source

const timeSecond = (): Time32Type<“s”> => impl.timeSecond() as unknown as Time32Type<“s”>

function timestamp

source

export function timestamp<U extends TUnit = TUnit>(
unit?: number,
timezone?: string | null,
): TimestampType<U>

Description

timestamp(unit): when called with a literal unit constant the result type carries that unit; with a runtime number it widens to TimestampType<TUnit>.

function timestampMicros

source

const timestampMicros = (timezone?: string | null): TimestampType<"us"> =>
impl.timestamp(impl.TimeUnit.MICROSECOND, timezone ?? null) as unknown as TimestampType<"us">

function timestampMillis

source

const timestampMillis = (timezone?: string | null): TimestampType<"ms"> =>
impl.timestamp(impl.TimeUnit.MILLISECOND, timezone ?? null) as unknown as TimestampType<"ms">

function timestampNanos

source

const timestampNanos = (timezone?: string | null): TimestampType<"ns"> =>
impl.timestamp(impl.TimeUnit.NANOSECOND, timezone ?? null) as unknown as TimestampType<"ns">

function timestampSeconds

source

const timestampSeconds = (timezone?: string | null): TimestampType<"s"> =>
impl.timestamp(impl.TimeUnit.SECOND, timezone ?? null) as unknown as TimestampType<"s">

const TimeUnit

source

TimeUnit

const TypeId

source

const TypeId

function typeSignature

source

export function typeSignature(t: VgiDataType | null | undefined): string

Description

Stable structural identity for an Arrow type, usable for equality.

String(type) is NOT usable for this: arrow-js DataTypes are class instances with a meaningful toString() (“Int64”, “Utf8”, …), while flechette types are plain object literals that stringify to “[object Object]”. Comparing with toString() therefore reports every flechette type as equal to every other, and never equal to a declared arrow-js type — which collapsed overload resolution to a first-match tie (type_info(42::BIGINT) picked the INTEGER overload).

Both libraries agree on typeId and on the parameter values; they differ only on a few property names, so those are read under both spellings. The output is an opaque key — compare it, don’t display it.

function uint16

source

const uint16 = (): Uint16Type => impl.uint16() as unknown as Uint16Type

function uint32

source

const uint32 = (): Uint32Type => impl.uint32() as unknown as Uint32Type

function uint64

source

const uint64 = (): Uint64Type => impl.uint64() as unknown as Uint64Type

function uint8

source

const uint8 = (): Uint8Type => impl.uint8() as unknown as Uint8Type

function union

source

export function union(
mode: number,
children: readonly (VgiField | VgiDataType)[],
typeIds?: number[],
): UnionType

const UnionMode

source

UnionMode

function utf8

source

const utf8 = (): Utf8Type => impl.utf8() as unknown as Utf8Type

interface VgiBackendInfo

source

export interface VgiBackendInfo

Fields

name“arrow-js” | “flechette”

interface VgiBatch

source

export interface VgiBatch

Fields

schemaVgiSchema

numRowsnumber

getChild(name: string): VgiColumn | null

See {@link VgiColumn} — this does NOT run the codec.

getChildAt(index: number): VgiColumn | null

See {@link VgiColumn} — this does NOT run the codec.

interface VgiColumn

source

export interface VgiColumn

Description

Column view over one column of a batch.

The value type is erased by default: arrow-js parameterizes on DataType and flechette on value type, so the facade cannot name one without picking a backend. Supply T at the use site — the column’s declared type makes it known there — and the cast disappears:

const ns = batch.getChildAt(0)! as Iterable<bigint | null>;
for (const v of ns) { ... }        // v: bigint | null

A type parameter here would read better, but it cannot be had cheaply: both backends’ native batches are assigned to VgiBatch structurally, and a concrete get(): unknown does not satisfy a generic get(): T. Adding one would mean casting at ~25 internal sites to remove one cast in user code.

These are the backend’s own values, not codec output. get() and iteration return whatever the Arrow implementation stores, which for some types is not the value the SDK documents:

Arrow type	here	{@link iterRows }
int64	bigint	bigint (same)
utf8, float64	string, number	same
decimal128	backend limbs (DecimalBigNum)	bigint, unscaled
timestamp[us]	millisecond number	microsecond bigint
date32	millisecond number	Date

repr: "raw" on a function selects the codec’s representation and has no effect on this path.

So: reach for getChildAt on integer, float, boolean, string and binary columns, where it is the cheapest correct thing. For temporal, decimal and nested types go through {@link iterRows }, which runs the codec.

Fields

typeVgiDataType

lengthnumber

get(index: number): unknown

[Symbol.iterator](): Iterator<unknown>

type VgiColumnData

source

export type VgiColumnData = unknown;

Description

Low-level handle for a single column’s underlying Arrow Data. The shape differs per backend (arrow-js: a Data instance; flechette: the inner Column.data[0]-style object), so this is treated opaquely; it’s only meant to be passed back into facade builders that know how to consume it.

interface VgiDataType

source

export interface VgiDataType

Fields

typeIdVgiTypeId

interface VgiField

source

export interface VgiField

Fields

namestring

typeVgiDataType

nullableboolean

metadataMap<string, string>

Always defined (possibly empty) so callers don’t need null-checks. Both arrow-js Field.metadata and flechette’s field.metadata are a Map; the field-factory in each backend ensures presence.

interface VgiSchema

source

export interface VgiSchema

Fields

fieldsreadonly VgiField[]

metadataMap<string, string>

type VgiTypeId

source

export type VgiTypeId = number;

Description

Numeric Arrow type discriminator. Values match the Arrow Type enum (Null=1, Int=2, Float=3, Binary=4, Utf8=5, Bool=6, Decimal=7, Date=8, Time=9, Timestamp=10, Interval=11, List=12, Struct=13, Union=14, FixedSizeBinary=15, FixedSizeList=16, Map=17, Duration=18, LargeBinary=19, LargeUtf8=20, Dictionary=-1). Both backends agree.