Client

On this page

Calling a VGI worker from TypeScript, without DuckDB in the middle.

interface CatalogAttachOptions

source

export interface CatalogAttachOptions

Description

Options bag for VgiClient.catalogAttach.

Pass options as a plain key→value map — the client serializes to an Arrow RecordBatch with per-value type inference (see AttachOptionValue). For Arrow types that inference can’t express (Decimal, Timestamp, exact int width, nested struct), use optionsBytes to supply pre-serialized bytes. Providing both throws.

dataVersionSpec / implementationVersion are sent to versioned catalogs for attach-time validation; workers that aren’t versioned ignore them.

Fields

optionsRecord<string, AttachOptionValue>optional

optionsBytesUint8Arrayoptional

dataVersionSpecstring | nulloptional

implementationVersionstring | nulloptional

type ClientCatalogFunctionType

source

export type CatalogFunctionType = “SCALAR_FUNCTION” | “TABLE_FUNCTION”;

Description

DuckDB catalog function type filter (sent as uppercase wire values).

type OnCreateConflict

source

export type OnCreateConflict = “error” | “ignore” | “replace”;

Description

Conflict resolution strategy for create operations.

interface ScalarFunctionOptions

source

export interface ScalarFunctionOptions

Description

Options for calling a scalar function.

Fields

functionNamestring

Name of the function to call.

inputIterable<VgiBatch> | AsyncIterable<VgiBatch>

Input batches to process.

argumentsArgumentsoptional

Positional and named arguments.

settingsVgiBatchoptional

DuckDB settings to pass to the function.

secretsVgiBatchoptional

DuckDB secrets to pass to the function.

transactionOpaqueDataUint8Arrayoptional

Transaction ID for transactional catalogs.

attachOpaqueDataUint8Arrayoptional

Attach ID to bind this call to a specific catalog attach. Overrides the client-level attachOpaqueData.

onBindBindResultCallbackoptional

Invoked after bind, before init. Receives the bind response.

interface TableFunctionOptions

source

export interface TableFunctionOptions

Description

Options for calling a table function.

Fields

functionNamestring

Name of the function to call.

argumentsArgumentsoptional

Positional and named arguments.

projectionIdsnumber[]optional

Column indices to project (filter pushdown).

pushdownFiltersVgiBatchoptional

Filter pushdown batch.

settingsVgiBatchoptional

DuckDB settings to pass to the function.

transactionOpaqueDataUint8Arrayoptional

Transaction ID for transactional catalogs.

attachOpaqueDataUint8Arrayoptional

Attach ID to bind this call to a specific catalog attach. Overrides the client-level attachOpaqueData.

orderByOrderByPushdownoptional

ORDER BY pushdown hint from DuckDB’s RowGroupPruner.

tablesampleTablesamplePushdownoptional

TABLESAMPLE pushdown hint from DuckDB’s SamplingPushdown optimizer.

joinKeysVgiBatch[]optional

Join-key value batches, one per join-keys column.

onBindBindResultCallbackoptional

Invoked after bind, before init. Receives the bind response.

interface TableInOutFunctionOptions

source

export interface TableInOutFunctionOptions

Description

Options for calling a table-in-out function.

Fields

functionNamestring

Name of the function to call.

inputIterable<VgiBatch> | AsyncIterable<VgiBatch>

Input batches to process.

argumentsArgumentsoptional

Positional and named arguments.

projectionIdsnumber[]optional

Column indices to project (filter pushdown).

pushdownFiltersVgiBatchoptional

Filter pushdown batch.

settingsVgiBatchoptional

DuckDB settings to pass to the function.

transactionOpaqueDataUint8Arrayoptional

Transaction ID for transactional catalogs.

attachOpaqueDataUint8Arrayoptional

Attach ID to bind this call to a specific catalog attach. Overrides the client-level attachOpaqueData.

orderByOrderByPushdownoptional

ORDER BY pushdown hint from DuckDB’s RowGroupPruner.

tablesampleTablesamplePushdownoptional

TABLESAMPLE pushdown hint from DuckDB’s SamplingPushdown optimizer.

joinKeysVgiBatch[]optional

Join-key value batches, one per join-keys column.

onBindBindResultCallbackoptional

Invoked after bind, before init. Receives the bind response.

class VgiClient

source

export class VgiClient

Description

High-level client for calling VGI worker functions and catalog API.

Works with any RpcClient transport (subprocess or HTTP):

import { subprocessConnect } from "@query-farm/vgi-rpc";
import { VgiClient, Arguments } from "@query-farm/vgi";

const rpc = subprocessConnect(["./my-worker"]);
const client = new VgiClient(rpc);

for await (const rows of client.tableFunctionRows({
functionName: "sequence",
arguments: new Arguments([10]),
})) {
console.log(rows);
}
client.close();

Methods

method tableFunction

source

async *tableFunction(
  opts: TableFunctionOptions,
): AsyncGenerator<VgiBatch>

Call a table function, yielding output as RecordBatch instances.

method scalarFunctionRows

source

async *scalarFunctionRows(
  opts: ScalarFunctionOptions,
): AsyncGenerator<Record<string, any>[]>

Call a scalar function, yielding output as row objects.

method scalarFunction

source

async *scalarFunction(
  opts: ScalarFunctionOptions,
): AsyncGenerator<VgiBatch>

Call a scalar function, yielding output as RecordBatch instances.

method tableInOutFunctionRows

source

async *tableInOutFunctionRows(
  opts: TableInOutFunctionOptions,
): AsyncGenerator<Record<string, any>[]>

Call a table-in-out function, yielding output as row objects.

method tableInOutFunction

source

async *tableInOutFunction(
  opts: TableInOutFunctionOptions,
): AsyncGenerator<VgiBatch>

Call a table-in-out function, yielding output as RecordBatch instances.

method tableFunctionRows

source

async *tableFunctionRows(
  opts: TableFunctionOptions,
): AsyncGenerator<Record<string, any>[]>

Call a table function, yielding output as row objects.

method catalogsInfo

source

async catalogsInfo(): Promise<CatalogInfo[]>

List all catalogs with their advertised version metadata.

Each entry has {name, implementation_version?, data_version_spec?}. Versioned workers populate the version fields; read-only workers leave both null.

method catalogs

source

async catalogs(): Promise<string[]>

List all available catalog names (shorthand for catalogsInfo().map(c => c.name)).

method catalogAttach

source

async catalogAttach(
  name: string,
  opts?: CatalogAttachOptions,
): Promise<CatalogAttachResult>

Attach a catalog by name. Returns connection details including the attachOpaqueData.

opts.options is a plain key→value map; column types are inferred from the value at runtime (see AttachOptionValue for the mapping). Use opts.optionsBytes instead when you need Arrow types the inference can’t express (Decimal, Timestamp, Int32 vs Int64, nested structs). Providing both throws.

Versioned catalogs (see vgi-example-versioned-worker) validate dataVersionSpec / implementationVersion at attach time and echo back the resolved values on the result — callers can read those from result.resolved_data_version / result.resolved_implementation_version.

method catalogDetach

source

async catalogDetach(attachOpaqueData: AttachOpaqueData): Promise<void>

Detach a previously-attached catalog.

method catalogCreate

source

async catalogCreate(
  name: string,
  onConflict: OnCreateConflict,
  options?:
    | Uint8Array
    |

Create a new catalog.

options is a plain key→value map; column types are inferred from the value at runtime (see AttachOptionValue). Use optionsBytes instead when you need Arrow types the inference can’t express. Providing both throws.

method catalogDrop

source

async catalogDrop(name: string): Promise<void>

Drop a catalog by name.

method catalogVersion

source

async catalogVersion(
  attachOpaqueData: AttachOpaqueData,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<number>

Get the current catalog version number.

method transactionBegin

source

async transactionBegin(attachOpaqueData: AttachOpaqueData): Promise<Uint8Array>

Begin a new transaction. Returns the transaction ID.

method transactionCommit

source

async transactionCommit(
  attachOpaqueData: AttachOpaqueData,
  transactionOpaqueData: TransactionOpaqueData,
): Promise<void>

Commit a transaction.

method transactionRollback

source

async transactionRollback(
  attachOpaqueData: AttachOpaqueData,
  transactionOpaqueData: TransactionOpaqueData,
): Promise<void>

Rollback a transaction.

method schemas

source

async schemas(
  attachOpaqueData: AttachOpaqueData,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<SchemaInfo[]>

List schemas in an attached catalog.

method schemaGet

source

async schemaGet(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<SchemaInfo | null>

Get a schema by name, or null if not found.

method schemaCreate

source

async schemaCreate(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  opts?:

Create a new schema.

method schemaDrop

source

async schemaDrop(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  ignoreNotFound?: boolean,
  cascade?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Drop a schema by name.

method schemaContentsTables

source

async schemaContentsTables(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<TableInfo[]>

List tables in a schema.

method schemaContentsViews

source

async schemaContentsViews(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<ViewInfo[]>

List views in a schema.

method schemaContentsFunctions

source

async schemaContentsFunctions(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  type: CatalogFunctionType,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<FunctionInfo[]>

List functions in a schema, filtered by type.

method tableGet

source

async tableGet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<TableInfo | null>

Get a table by name, or null if not found.

method tableCreate

source

async tableCreate(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columns: Uint8Array,
  onConflict: OnCreateConflict,
  notNullConstraints?: number[],
  uniqueConstraints?: number[][],
  checkConstraints?: string[],
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Create a new table.

method tableDrop

source

async tableDrop(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  ignoreNotFound?: boolean,
  cascade?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Drop a table by name.

method tableScanFunctionGet

source

async tableScanFunctionGet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  atUnit?: string | null,
  atValue?: string | null,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<ScanFunctionResult>

Get the scan function for a table — tells DuckDB which function to call to read the table data (e.g. read_parquet with a path argument). Used by the VGI extension during query planning.

method tableCommentSet

source

async tableCommentSet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  comment?: string | null,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Set or clear the comment on a table.

method tableRename

source

async tableRename(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  newName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Rename a table.

method tableColumnAdd

source

async tableColumnAdd(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  columnType: string,
  defaultValue?: string | null,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Add a column to a table.

method tableColumnDrop

source

async tableColumnDrop(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Drop a column from a table.

method tableColumnRename

source

async tableColumnRename(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  newName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Rename a column in a table.

method tableColumnDefaultSet

source

async tableColumnDefaultSet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  defaultValue: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Set the default value for a column.

method tableColumnDefaultDrop

source

async tableColumnDefaultDrop(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Remove the default value from a column.

method tableColumnTypeChange

source

async tableColumnTypeChange(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnDefinition: Uint8Array,
  expression?: string | null,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Change the type of a column.

columnDefinition is a serialized Arrow Schema with a single field whose name identifies the target column and whose type is the new column type. expression is an optional SQL expression used to convert existing values.

method tableNotNullSet

source

async tableNotNullSet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Set a NOT NULL constraint on a column.

method tableNotNullDrop

source

async tableNotNullDrop(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  columnName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Remove a NOT NULL constraint from a column.

method viewGet

source

async viewGet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<ViewInfo | null>

Get a view by name, or null if not found.

method viewCreate

source

async viewCreate(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  definition: string,
  onConflict: OnCreateConflict,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Create a new view.

method viewDrop

source

async viewDrop(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  ignoreNotFound?: boolean,
  cascade?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Drop a view by name.

method viewRename

source

async viewRename(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  newName: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Rename a view.

method viewCommentSet

source

async viewCommentSet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  comment?: string | null,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Set or clear the comment on a view.

method macroGet

source

async macroGet(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<MacroInfo | null>

Get a macro by name, or null if not found.

method schemaContentsMacros

source

async schemaContentsMacros(
  attachOpaqueData: AttachOpaqueData,
  name: string,
  type: CatalogMacroType,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<MacroInfo[]>

List macros in a schema, filtered by type.

method macroCreate

source

async macroCreate(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  macroType: MacroType,
  parameters: string[],
  definition: string,
  onConflict: OnCreateConflict,
  parameterDefaultValues?: Uint8Array | null,
  argumentsSchema?: Uint8Array | null,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Create a new macro.

method macroDrop

source

async macroDrop(
  attachOpaqueData: AttachOpaqueData,
  schemaName: string,
  name: string,
  ignoreNotFound?: boolean,
  transactionOpaqueData?: TransactionOpaqueData,
): Promise<void>

Drop a macro by name.

method close

source

close(): void

Close the underlying RPC connection.

class VgiClientError

source

export class VgiClientError extends Error

Description

Error thrown by VgiClient when an RPC call fails or returns unexpected data.

Properties

property remoteTraceback

source

readonly remoteTraceback?: string;

Remote traceback from the worker, when an RpcError carried one.

property errorType

source

readonly errorType?: string;

Underlying error type from the worker (e.g. “ValueError”), when known.

interface VgiClientOptions

source

export interface VgiClientOptions

Description

Options for constructing a VgiClient.

Fields

attachOpaqueDataUint8Arrayoptional

Pre-existing attach ID to bind this client to a specific catalog.