Scalar functions

On this page

One row in, one value out — the simplest function shape.

function defineScalarFunction

source

export function defineScalarFunction<
P extends Record<string, VgiDataType> = Record<string, VgiDataType>,
R extends VgiDataType = VgiDataType,
M extends Repr = "rich",
>(config: ScalarFunctionConfig<P, R, M>): VgiFunction

interface ScalarBindParameters

source

export interface ScalarBindParameters

Fields

constArgsRecord<string, any>

Constant argument values (resolved at bind time)

argumentsSchemaVgiSchema

Schema of all arguments including columnar params

settingsRecord<string, any>

Settings from DuckDB

secretsRecord<string, Record<string, any>>

Secrets from DuckDB

bindCallBindRequest

Original bind request — exposes attach_opaque_data, transaction_opaque_data, function_type, etc.

type ScalarComputeResult

source

export type ScalarComputeResult<R extends VgiDataType, M extends Repr> =
| Array<ScalarOutputValue<R, M>>
| Iterable<ScalarOutputValue<R, M>>
| VgiBatch;

Description

Accepted compute return shapes: an array (or iterable) of output values in the declared representation, or a pre-built VgiBatch. The representation is enforced statically — returning a Date under repr: 'raw' (which expects a branded Date32/Date64Ms), or a branded value under repr: 'rich' (which expects a Date), is a COMPILE error.

type ScalarComputeRow

source

export type ScalarComputeRow<
P extends Record<string, VgiDataType>,
M extends Repr,
> = { [K in keyof P]: ValueFor<P[K], M> | null };

Description

The typed compute row for a scalar function: one property per declared columnar param, valued in the representation (rich / raw) selected by the function’s repr. (Provided as a convenience type for authors who build rows out of the input batch.)

interface ScalarFunctionConfig

source

export interface ScalarFunctionConfig<
P extends Record<string, VgiDataType> = Record<string, VgiDataType>,
R extends VgiDataType = VgiDataType,
M extends Repr = "rich",
>

Fields

namestring

compute( batch: VgiBatch, consts: Record<string, any>, info: { settings: Record<string, any>; secrets: Record<string, Record<string, any>>; auth: AuthContext; } // NoInfer pins R/M from returns/repr so the compute return type is // CHECKED against them rather than widening them to fit a wrong value. ) => ScalarComputeResult<NoInfer<R>, NoInfer<M>>

Process: receives the columnar input batch + const values, returns the output column as an array/iterable of values (statically typed from returns and repr) or a pre-built VgiBatch.

descriptionstringoptional

paramsPoptional

Columnar params (receive Arrow arrays at process time)

constParamsRecord<string, VgiDataType>optional

Constant params (receive scalar values resolved at bind time)

argDocsRecord<string, string>optional

Per-argument descriptions keyed by param name, surfaced as vgi_doc field metadata (and via the extension’s vgi_function_arguments()). Applies to params and constParams; for the ordered parameters list use each entry’s doc field instead.

parametersScalarParameterDef[]optional

Ordered parameter list. When provided, overrides params and constParams. Use this when parameters need non-default ordering (e.g. const, param, const).

returnsRoptional

Output type (static)

outputType(params: ScalarBindParameters) => VgiDataType | Promise<VgiDataType>optional

Dynamic output type at bind time

reprMoptional

Value representation for compute I/O. 'rich' (default) uses JS Date for date32/date64 and plain number/bigint elsewhere. 'raw' uses the branded unit-carrying aliases (Date32, TimestampMicros, UnscaledDecimal, …). The choice flows into compute()’s statically-checked return type and selects the runtime converter used to build the output column.

stabilityFunctionStabilityoptional

nullHandlingNullHandlingoptional

examplesFunctionExample[]optional

categoriesstring[]optional

tagsRecord<string, string>optional

maxWorkersnumberoptional

requiredSettingsstring[]optional

requiredSecretsstring[]optional

cacheControlCacheControloptional

Result-cache opt-in: when set, this CacheControl’s vgi.cache.* metadata rides every output batch’s custom metadata (per-batch — NOT the schema, which the IPC stream fixes at open). A pure, deterministic scalar only — advertising this on a non-pure scalar serves stale rows. Mirrors vgi-python’s ScalarFunction.CACHE_CONTROL.

Per-VALUE memoization (the extension remembering one output per distinct input value) additionally requires perValue: true, which is off by default because a memo serve only beats a worker call when the call is expensive — see {@link CacheControl.perValue}.

type ScalarOutputValue

source

export type ScalarOutputValue<R extends VgiDataType, M extends Repr> =
ValueFor<R, M> | null;

Description

A single output value for a scalar function under representation M.

interface ScalarParameterDef

source

export interface ScalarParameterDef

Description

Ordered parameter definition for scalar functions.

Fields

namestring

typeVgiDataType

constbooleanoptional

If true, this is a constant parameter (scalar value resolved at bind time).

varargsbooleanoptional

If true, this parameter accepts variable number of arguments.

docstringoptional

Human-readable per-argument description (surfaced as vgi_doc).

choicesreadonly unknown[]optional

Closed set of allowed values (surfaced as vgi_choices).

genumberoptional

Inclusive lower bound, >= (folded into vgi_range).

lenumberoptional

Inclusive upper bound, <= (folded into vgi_range).

gtnumberoptional

Exclusive lower bound, > (folded into vgi_range).

ltnumberoptional

Exclusive upper bound, < (folded into vgi_range).

patternstringoptional

Regex the value must match (surfaced as vgi_pattern).

defaultunknownoptional

Default value (surfaced as vgi_default, JSON-encoded).