Class QuackClient

Client for DuckDB's Quack HTTP protocol.

A Quack connection runs one statement at a time; the server cancels a running statement when the next one starts. The client therefore queues statements issued concurrently on the same instance. Streams release the queue between batches, so a statement started while a stream is not yet drained interrupts that stream. Use separate clients for concurrent work.

Index

Properties

`Readonly`baseUrl

baseUrl: string

HTTP or HTTPS base URL used for Quack requests.

`Readonly`fetchImpl

fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>

Fetch implementation used by this client.

Type Declaration

- (input: RequestInfo | URL, init?: RequestInit): Promise<Response>
- MDN Reference
  Parameters
  - input: RequestInfo | URL
  - Optionalinit: RequestInit
  Returns Promise<Response>

info

info: QuackConnectionInfo | undefined

Server metadata populated after a successful connection.

Accessors

isConnected

get isConnected(): boolean
Whether this client currently has an open Quack connection.

Returns boolean
- Defined in src/client.ts:305

Methods

append

append(
    table: string,
    data: QuackDataChunk | readonly QuackDataChunk[],
    schemaName?: string,
): Promise<number>
Append one or more encoded DuckDB DataChunks to a table and return the number of inserted rows.

All chunks are inserted by one INSERT statement, so they succeed or fail together. Columns are matched by position against the target table.
Parameters
- table: string
- data: QuackDataChunk | readonly QuackDataChunk[]
- OptionalschemaName: string
Returns Promise<number>
- Defined in src/client.ts:531
append(
    table: string,
    data: QuackDataChunk | readonly QuackDataChunk[],
    options?: AppendOptions,
): Promise<number>
Append one or more encoded DuckDB DataChunks to a table and return the number of inserted rows.

All chunks are inserted by one INSERT statement, so they succeed or fail together. Columns are matched by position against the target table.
Parameters
- table: string
- data: QuackDataChunk | readonly QuackDataChunk[]
- Optionaloptions: AppendOptions
Returns Promise<number>
- Defined in src/client.ts:532
append(
    table: TableReference,
    data: QuackDataChunk | readonly QuackDataChunk[],
    options?: QuackRequestOptions,
): Promise<number>
Append one or more encoded DuckDB DataChunks to a table and return the number of inserted rows.

All chunks are inserted by one INSERT statement, so they succeed or fail together. Columns are matched by position against the target table.
Parameters
- table: TableReference
- data: QuackDataChunk | readonly QuackDataChunk[]
- Optionaloptions: QuackRequestOptions
Returns Promise<number>
- Defined in src/client.ts:533
append(
    table: string | TableReference,
    data: QuackDataChunk | readonly QuackDataChunk[],
    schemaOrOptions?: string | QuackRequestOptions | AppendOptions,
): Promise<number>
Append one or more encoded DuckDB DataChunks to a table and return the number of inserted rows.

All chunks are inserted by one INSERT statement, so they succeed or fail together. Columns are matched by position against the target table.
Parameters
- table: string | TableReference
- data: QuackDataChunk | readonly QuackDataChunk[]
- OptionalschemaOrOptions: string | QuackRequestOptions | AppendOptions
Returns Promise<number>
- Defined in src/client.ts:534

appendArrow

appendArrow(
    table: string | TableReference,
    input: QuackArrowInput,
    options?: AppendArrowOptions,
): Promise<number>
Append data from a Flechette Arrow Table or Arrow IPC bytes. Returns the number of inserted rows.
Parameters
- table: string | TableReference
- input: QuackArrowInput
- options: AppendArrowOptions = {}
Returns Promise<number>
- Defined in src/client.ts:616

appendRows

appendRows<T extends Record<string, unknown>>(
    table: string | TableReference,
    rows: readonly T[],
    options?: AppendRowsOptions<T>,
): Promise<number>
Encode row objects as flat DataChunks and append them to a table in one statement. Returns the number of inserted rows.

Provide explicit column types for stable production use, especially for empty row sets or columns containing only null.
Type Parameters
- T extends Record<string, unknown>
Parameters
- table: string | TableReference
- rows: readonly T[]
- options: AppendRowsOptions<T> = {}
Returns Promise<number>
- Defined in src/client.ts:595

cancel

cancel(options?: QuackRequestOptions): Promise<boolean>
Cancel the statement currently running on this client.

Resolves to false when no statement is running.
Parameters
- options: QuackRequestOptions = {}
Returns Promise<boolean>
- Defined in src/client.ts:650

close

close(options?: QuackRequestOptions): Promise<void>
Alias for disconnect.
Parameters
- options: QuackRequestOptions = {}
Returns Promise<void>
- Defined in src/client.ts:698

disconnect

disconnect(options?: QuackRequestOptions): Promise<void>
Disconnect from the Quack server. Safe to call more than once.
Parameters
- options: QuackRequestOptions = {}
Returns Promise<void>
- Defined in src/client.ts:677

first

first<T extends QuackRow = QuackRow>(
sql: string,
options?: QuackQueryOptions,
): Promise<T | null>
Run SQL and return the first row, or null when the result is empty.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- Optionaloptions: QuackQueryOptions
Returns Promise<T | null>
- Defined in src/client.ts:387
first<T extends QuackRow = QuackRow>(
    sql: string,
    params: SqlParameters,
    options?: QuackRequestOptions,
): Promise<T | null>
Run SQL and return the first row, or null when the result is empty.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackRequestOptions
Returns Promise<T | null>
- Defined in src/client.ts:388

heartbeat

heartbeat(options?: QuackRequestOptions): Promise<void>
Send a heartbeat request, renewing the connection lease.
Parameters
- options: QuackRequestOptions = {}
Returns Promise<void>
- Defined in src/client.ts:666

one

one<T extends QuackRow = QuackRow>(
sql: string,
options?: QuackQueryOptions,
): Promise<T>
Run SQL and return exactly one row, throwing when the row count is not one.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- Optionaloptions: QuackQueryOptions
Returns Promise<T>
- Defined in src/client.ts:403
one<T extends QuackRow = QuackRow>(
    sql: string,
    params: SqlParameters,
    options?: QuackRequestOptions,
): Promise<T>
Run SQL and return exactly one row, throwing when the row count is not one.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackRequestOptions
Returns Promise<T>
- Defined in src/client.ts:404

query

query<T extends QuackRow = QuackRow>(
sql: string,
options?: QuackQueryOptions,
): Promise<QuackQueryResult<T>>
Run SQL and collect all result chunks.

Use the generic parameter to type the materialized rows returned by QuackQueryResult.rows.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- Optionaloptions: QuackQueryOptions
Returns Promise<QuackQueryResult<T>>
- Defined in src/client.ts:315
query<T extends QuackRow = QuackRow>(
    sql: string,
    params: SqlParameters,
    options?: QuackRequestOptions,
): Promise<QuackQueryResult<T>>
Run SQL and collect all result chunks.

Use the generic parameter to type the materialized rows returned by QuackQueryResult.rows.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackRequestOptions
Returns Promise<QuackQueryResult<T>>
- Defined in src/client.ts:316

queryArrow

queryArrow(
sql: string,
options?: QuackArrowQueryOptions,
): Promise<ArrowTable<TypeMap>>
Run SQL and collect the result as a Flechette Arrow Table.
Parameters
- sql: string
- Optionaloptions: QuackArrowQueryOptions
Returns Promise<ArrowTable<TypeMap>>
- Defined in src/client.ts:353
queryArrow(
    sql: string,
    params: SqlParameters,
    options?: QuackArrowQueryOptions,
): Promise<ArrowTable<TypeMap>>
Run SQL and collect the result as a Flechette Arrow Table.
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackArrowQueryOptions
Returns Promise<ArrowTable<TypeMap>>
- Defined in src/client.ts:354

queryArrowIPC

queryArrowIPC(
sql: string,
options?: QuackArrowQueryIPCOptions,
): Promise<Uint8Array<ArrayBufferLike>>
Run SQL and collect the result as Arrow IPC bytes.
Parameters
- sql: string
- Optionaloptions: QuackArrowQueryIPCOptions
Returns Promise<Uint8Array<ArrayBufferLike>>
- Defined in src/client.ts:370
queryArrowIPC(
    sql: string,
    params: SqlParameters,
    options?: QuackArrowQueryIPCOptions,
): Promise<Uint8Array<ArrayBufferLike>>
Run SQL and collect the result as Arrow IPC bytes.
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackArrowQueryIPCOptions
Returns Promise<Uint8Array<ArrayBufferLike>>
- Defined in src/client.ts:371

send

send(
message: QuackMessage,
options?: QuackRequestOptions,
): Promise<QuackMessage>
Send a raw Quack protocol message.

This is an escape hatch for protocol tests and advanced clients; most application code should use higher-level methods.
Parameters
- message: QuackMessage
- options: QuackRequestOptions = {}
Returns Promise<QuackMessage>
- Defined in src/client.ts:708

stream

stream(
sql: string,
options?: QuackQueryOptions,
): AsyncGenerator<QuackDataChunk, void, void>
Run SQL and stream decoded DuckDB DataChunks without materializing all rows.

Breaking out of the loop cancels the remaining result on the server. A statement started on this client before the stream is drained interrupts the stream.
Parameters
- sql: string
- Optionaloptions: QuackQueryOptions
Returns AsyncGenerator<QuackDataChunk, void, void>
- Defined in src/client.ts:448
stream(
    sql: string,
    params: SqlParameters,
    options?: QuackRequestOptions,
): AsyncGenerator<QuackDataChunk, void, void>
Run SQL and stream decoded DuckDB DataChunks without materializing all rows.

Breaking out of the loop cancels the remaining result on the server. A statement started on this client before the stream is drained interrupts the stream.
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackRequestOptions
Returns AsyncGenerator<QuackDataChunk, void, void>
- Defined in src/client.ts:449

streamArrow

streamArrow(
sql: string,
options?: QuackArrowQueryOptions,
): AsyncGenerator<ArrowTable<TypeMap>, void, void>
Run SQL and stream result chunks as Flechette Arrow Tables.
Parameters
- sql: string
- Optionaloptions: QuackArrowQueryOptions
Returns AsyncGenerator<ArrowTable<TypeMap>, void, void>
- Defined in src/client.ts:512
streamArrow(
    sql: string,
    params: SqlParameters,
    options?: QuackArrowQueryOptions,
): AsyncGenerator<ArrowTable<TypeMap>, void, void>
Run SQL and stream result chunks as Flechette Arrow Tables.
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackArrowQueryOptions
Returns AsyncGenerator<ArrowTable<TypeMap>, void, void>
- Defined in src/client.ts:513

streamRows

streamRows<T extends QuackRow = QuackRow>(
sql: string,
options?: QuackQueryOptions,
): AsyncGenerator<T, void, void>
Run SQL and stream materialized rows.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- Optionaloptions: QuackQueryOptions
Returns AsyncGenerator<T, void, void>
- Defined in src/client.ts:493
streamRows<T extends QuackRow = QuackRow>(
    sql: string,
    params: SqlParameters,
    options?: QuackRequestOptions,
): AsyncGenerator<T, void, void>
Run SQL and stream materialized rows.
Type Parameters
- T extends QuackRow = QuackRow
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackRequestOptions
Returns AsyncGenerator<T, void, void>
- Defined in src/client.ts:494

transaction

transaction<T>(
fn: (client: this) => T | Promise<T>,
options?: QuackRequestOptions,
): Promise<T>
Run a callback inside a DuckDB transaction.

Commits when the callback succeeds and attempts rollback when it throws.
Type Parameters
- T
Parameters
- fn: (client: this) => T | Promise<T>
- options: QuackRequestOptions = {}
Returns Promise<T>
- Defined in src/client.ts:629

values

values<T extends QuackValue = QuackValue>(
sql: string,
options?: QuackQueryOptions,
): Promise<T[]>
Run SQL and return the first column from every materialized row.
Type Parameters
- T extends QuackValue = QuackValue
Parameters
- sql: string
- Optionaloptions: QuackQueryOptions
Returns Promise<T[]>
- Defined in src/client.ts:422
values<T extends QuackValue = QuackValue>(
    sql: string,
    params: SqlParameters,
    options?: QuackRequestOptions,
): Promise<T[]>
Run SQL and return the first column from every materialized row.
Type Parameters
- T extends QuackValue = QuackValue
Parameters
- sql: string
- params: SqlParameters
- Optionaloptions: QuackRequestOptions
Returns Promise<T[]>
- Defined in src/client.ts:423

`Static`connect

connect(uri: string, options?: QuackClientOptions): Promise<QuackClient>
Open a Quack connection.

Accepts bare host strings such as localhost:9494, DuckDB-style quack: URIs, and direct HTTP(S) URLs.
Parameters
- uri: string
- options: QuackClientOptions = {}
Returns Promise<QuackClient>
- Defined in src/client.ts:222

`Static`withConnection

withConnection<T>(
uri: string,
fn: (client: QuackClient) => T | Promise<T>,
): Promise<T>
Open a connection, run a callback, and always disconnect afterwards.
Type Parameters
- T
Parameters
- uri: string
- fn: (client: QuackClient) => T | Promise<T>
Returns Promise<T>
- Defined in src/client.ts:277
withConnection<T>(
    uri: string,
    options: QuackClientOptions,
    fn: (client: QuackClient) => T | Promise<T>,
): Promise<T>
Open a connection, run a callback, and always disconnect afterwards.
Type Parameters
- T
Parameters
- uri: string
- options: QuackClientOptions
- fn: (client: QuackClient) => T | Promise<T>
Returns Promise<T>
- Defined in src/client.ts:281

Class QuackClient

Index

Properties

Accessors

Methods

Properties

ReadonlybaseUrl

ReadonlyfetchImpl

Type Declaration

Parameters

Returns Promise<Response>

info

Accessors

isConnected

Returns boolean

Methods

append

Parameters

Returns Promise<number>

Parameters

Returns Promise<number>

Parameters

Returns Promise<number>

Parameters

Returns Promise<number>

appendArrow

Parameters

Returns Promise<number>

appendRows

Type Parameters

Parameters

Returns Promise<number>

cancel

Parameters

Returns Promise<boolean>

close

Parameters

Returns Promise<void>

disconnect

Parameters

Returns Promise<void>

first

Type Parameters

Parameters

Returns Promise<T | null>

Type Parameters

Parameters

Returns Promise<T | null>

heartbeat

Parameters

Returns Promise<void>

one

Type Parameters

Parameters

Returns Promise<T>

Type Parameters

Parameters

Returns Promise<T>

query

Type Parameters

Parameters

Returns Promise<QuackQueryResult<T>>

Type Parameters

Parameters

Returns Promise<QuackQueryResult<T>>

queryArrow

Parameters

Returns Promise<ArrowTable<TypeMap>>

Parameters

Returns Promise<ArrowTable<TypeMap>>

queryArrowIPC

Parameters

Returns Promise<Uint8Array<ArrayBufferLike>>

Parameters

Returns Promise<Uint8Array<ArrayBufferLike>>

send

Parameters

Returns Promise<QuackMessage>

stream

Parameters

`Readonly`baseUrl

`Readonly`fetchImpl

`Static`connect

`Static`withConnection