Class FlightSqlClient

Arrow Flight SQL client for executing SQL queries and managing transactions.

FlightSqlClient wraps FlightClient using composition, providing Flight SQL specific operations while delegating core Flight RPC to the underlying client.

Example

const client = new FlightSqlClient({ url: "https://flight.example.com:8815" })

// Execute a query and get results as a Table
const table = await client.query("SELECT * FROM users")
console.log(`Got ${table.numRows} rows`)

// Execute an update
const result = await client.executeUpdate("INSERT INTO users (name) VALUES ('Alice')")
console.log(`Inserted ${result.recordCount} rows`)

// Use prepared statements
const stmt = await client.prepare("SELECT * FROM users WHERE id = ?")
// ... bind parameters and execute ...
await client.closePreparedStatement(stmt)

client.close()

Constructors

constructor

new FlightSqlClient(
optionsOrClient: FlightClientOptions | FlightClient,
): FlightSqlClient
Creates a new FlightSqlClient.
Parameters
- optionsOrClient: FlightClientOptions | FlightClient
  Either FlightClientOptions to create a new FlightClient, or an existing FlightClient instance to wrap.
Returns FlightSqlClient
- Defined in flight-sql-client.ts:274

Accessors

closed

get closed(): boolean
Whether the client has been closed.

Returns boolean
- Defined in flight-sql-client.ts:304

flight

get flight(): FlightClient
The underlying Flight client. Use this for advanced Flight operations not covered by Flight SQL.

Returns FlightClient
- Defined in flight-sql-client.ts:290

url

get url(): string
The base URL of the Flight server.

Returns string
- Defined in flight-sql-client.ts:297

Methods

authenticate

authenticate(): Promise<string | undefined>
Authenticate with the server using configured credentials.

Returns Promise<string | undefined>
- Defined in flight-sql-client.ts:318

beginTransaction

beginTransaction(): Promise<Transaction>

Begin a new transaction.

Returns Promise<Transaction>

Transaction handle

Example

const txn = await client.beginTransaction()
try {
  await client.executeUpdate("INSERT INTO users ...", { transactionId: txn.id })
  await client.executeUpdate("INSERT INTO logs ...", { transactionId: txn.id })
  await client.commit(txn)
} catch (e) {
  await client.rollback(txn)
  throw e
}

close

close(): void
Close the client and release resources.

Returns void
- Defined in flight-sql-client.ts:311

closePreparedStatement

closePreparedStatement(statement: PreparedStatement): Promise<void>
Close a prepared statement and release server resources.
Parameters
- statement: PreparedStatement
  Prepared statement to close
Returns Promise<void>
- Defined in flight-sql-client.ts:657

commit

commit(transaction: Transaction): Promise<void>
Commit a transaction.
Parameters
- transaction: Transaction
  Transaction to commit
Returns Promise<void>
- Defined in flight-sql-client.ts:726

executePrepared

executePrepared<T extends TypeMap = TypeMap>(
statement: PreparedStatement,
): Promise<Table<T>>
Execute a prepared query statement and return results as a Table.
Type Parameters
- T extends TypeMap = TypeMap
Parameters
- statement: PreparedStatement
  Prepared statement from prepare()
Returns Promise<Table<T>>
Arrow Table containing query results
- Defined in flight-sql-client.ts:546

executePreparedStream

executePreparedStream(statement: PreparedStatement): AsyncGenerator<FlightData>
Execute a prepared query statement and return results as a stream.
Parameters
- statement: PreparedStatement
  Prepared statement from prepare()
Returns AsyncGenerator<FlightData>
Yields
FlightData messages
- Defined in flight-sql-client.ts:559

executePreparedUpdate

executePreparedUpdate(
    statement: PreparedStatement,
    parameters?:
        | AsyncIterable<RecordBatch<any>, any, any>
        | Iterable<RecordBatch<any>, any, any>,
): Promise<UpdateResult>
Execute a prepared update statement and return affected row count.
Parameters
- statement: PreparedStatement
  Prepared statement from prepare()
- Optionalparameters: AsyncIterable<RecordBatch<any>, any, any> | Iterable<RecordBatch<any>, any, any>
  Optional parameter values as RecordBatches
Returns Promise<UpdateResult>
Update result with affected row count
- Defined in flight-sql-client.ts:587

executeUpdate

executeUpdate(
query: string,
options?: ExecuteUpdateOptions,
): Promise<UpdateResult>
Execute a SQL update statement (INSERT, UPDATE, DELETE, DDL).
Parameters
- query: string
  SQL update statement
- Optionaloptions: ExecuteUpdateOptions
  Update execution options
Returns Promise<UpdateResult>
Update result with affected row count
Example
```
const result = await client.executeUpdate("DELETE FROM users WHERE inactive = true")
console.log(`Deleted ${result.recordCount} inactive users`)
```
- Defined in flight-sql-client.ts:451

getCatalogs

getCatalogs<T extends TypeMap = TypeMap>(): Promise<Table<T>>
Get the list of catalogs in the database.
Type Parameters
- T extends TypeMap = TypeMap
Returns Promise<Table<T>>
Arrow Table with catalog_name column
Example
```
const catalogs = await client.getCatalogs()
for (const row of catalogs) {
  console.log(row.catalog_name)
}
```
- Defined in flight-sql-client.ts:754

getDbSchemas

getDbSchemas<T extends TypeMap = TypeMap>(
options?: { catalog?: string; dbSchemaFilterPattern?: string },
): Promise<Table<T>>
Get the list of database schemas.
Type Parameters
- T extends TypeMap = TypeMap
Parameters
- Optionaloptions: { catalog?: string; dbSchemaFilterPattern?: string }
  Filter options
  - Optionalcatalog?: string
    Filter by catalog name
  - OptionaldbSchemaFilterPattern?: string
    Filter pattern for schema names (supports % and _ wildcards)
Returns Promise<Table<T>>
Arrow Table with catalog_name and db_schema_name columns
Example
```
const schemas = await client.getDbSchemas({ catalog: "my_catalog" })
```
- Defined in flight-sql-client.ts:771

getPrimaryKeys

getPrimaryKeys<T extends TypeMap = TypeMap>(
table: string,
options?: { catalog?: string; dbSchema?: string },
): Promise<Table<T>>
Get the primary keys for a table.
Type Parameters
- T extends TypeMap = TypeMap
Parameters
- table: string
  Table name (required)
- Optionaloptions: { catalog?: string; dbSchema?: string }
  Additional filter options
  - Optionalcatalog?: string
    Catalog containing the table
  - OptionaldbSchema?: string
    Schema containing the table
Returns Promise<Table<T>>
Arrow Table with catalog_name, db_schema_name, table_name, column_name, key_name, key_sequence columns
Example
```
const keys = await client.getPrimaryKeys("users", { catalog: "my_db" })
```
- Defined in flight-sql-client.ts:848

getQueryInfo

getQueryInfo(query: string, options?: ExecuteQueryOptions): Promise<FlightInfo>
Get FlightInfo for a SQL query without executing it.

Use this to inspect the query plan, schema, or endpoints before fetching data.
Parameters
- query: string
  SQL query string
- Optionaloptions: ExecuteQueryOptions
  Query execution options
Returns Promise<FlightInfo>
FlightInfo describing the query results
- Defined in flight-sql-client.ts:424

getTables

getTables<T extends TypeMap = TypeMap>(
    options?: {
        catalog?: string;
        dbSchemaFilterPattern?: string;
        includeSchema?: boolean;
        tableNameFilterPattern?: string;
        tableTypes?: string[];
    },
): Promise<Table<T>>
Get the list of tables.
Type Parameters
- T extends TypeMap = TypeMap
Parameters
- Optionaloptions: {
      catalog?: string;
      dbSchemaFilterPattern?: string;
      includeSchema?: boolean;
      tableNameFilterPattern?: string;
      tableTypes?: string[];
  }
  Filter options
  - Optionalcatalog?: string
    Filter by catalog name
  - OptionaldbSchemaFilterPattern?: string
    Filter pattern for schema names (supports % and _ wildcards)
  - OptionalincludeSchema?: boolean
    Include table schema in results
  - OptionaltableNameFilterPattern?: string
    Filter pattern for table names (supports % and _ wildcards)
  - OptionaltableTypes?: string[]
    Filter by table types (e.g., "TABLE", "VIEW")
Returns Promise<Table<T>>
Arrow Table with catalog_name, db_schema_name, table_name, table_type columns
Example
```
const tables = await client.getTables({ tableTypes: ["TABLE", "VIEW"] })
```
- Defined in flight-sql-client.ts:796

getTableTypes

getTableTypes<T extends TypeMap = TypeMap>(): Promise<Table<T>>
Get the list of table types supported by the server.
Type Parameters
- T extends TypeMap = TypeMap
Returns Promise<Table<T>>
Arrow Table with table_type column
Example
```
const tableTypes = await client.getTableTypes()
// Common types: TABLE, VIEW, SYSTEM TABLE
```
- Defined in flight-sql-client.ts:830

prepare

prepare(
query: string,
transactionId?: Uint8Array<ArrayBufferLike>,
): Promise<PreparedStatement>
Prepare a SQL statement for repeated execution.
Parameters
- query: string
  SQL query with optional parameter placeholders
- OptionaltransactionId: Uint8Array<ArrayBufferLike>
  Optional transaction to associate with the statement
Returns Promise<PreparedStatement>
Prepared statement handle
Example
```
const stmt = await client.prepare("SELECT * FROM users WHERE id = ?")
// Use executePrepared() to execute with parameters
await client.closePreparedStatement(stmt)
```
- Defined in flight-sql-client.ts:509

query

query<T extends TypeMap = TypeMap>(
query: string,
options?: ExecuteQueryOptions,
): Promise<Table<T>>
Execute a SQL query and return results as an Arrow Table.

This is a convenience method that combines getFlightInfo and doGet to fetch all query results into memory.
Type Parameters
- T extends TypeMap = TypeMap
Parameters
- query: string
  SQL query string
- Optionaloptions: ExecuteQueryOptions
  Query execution options
Returns Promise<Table<T>>
Arrow Table containing query results
Example
```
const table = await client.query("SELECT * FROM users WHERE active = true")
console.log(`Found ${table.numRows} active users`)
```
- Defined in flight-sql-client.ts:340

queryBatches

queryBatches<T extends TypeMap = TypeMap>(
query: string,
options?: ExecuteQueryOptions,
): AsyncGenerator<RecordBatch<T>>
Execute a SQL query and return results as a stream of RecordBatches.

Use this for large result sets to avoid loading all data into memory.
Type Parameters
- T extends TypeMap = TypeMap
Parameters
- query: string
  SQL query string
- Optionaloptions: ExecuteQueryOptions
  Query execution options
Returns AsyncGenerator<RecordBatch<T>>
Yields
RecordBatch objects
Example
```
for await (const batch of client.queryBatches("SELECT * FROM large_table")) {
  processBatch(batch)
}
```
- Defined in flight-sql-client.ts:364

queryStream

queryStream(
query: string,
options?: ExecuteQueryOptions,
): AsyncGenerator<FlightData>
Execute a SQL query and return the raw FlightData stream.

This is the lowest-level query method, useful when you need access to raw Flight data or custom decoding.
Parameters
- query: string
  SQL query string
- Optionaloptions: ExecuteQueryOptions
  Query execution options
Returns AsyncGenerator<FlightData>
Yields
FlightData messages
- Defined in flight-sql-client.ts:384

rollback

rollback(transaction: Transaction): Promise<void>
Roll back a transaction.
Parameters
- transaction: Transaction
  Transaction to roll back
Returns Promise<void>
- Defined in flight-sql-client.ts:735

Class FlightSqlClient

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns FlightSqlClient

Accessors

closed

Returns boolean

flight

Returns FlightClient

url

Returns string

Methods

authenticate

Returns Promise<string | undefined>

beginTransaction

Returns Promise<Transaction>

Example

close

Returns void

closePreparedStatement

Parameters

Returns Promise<void>

commit

Parameters

Returns Promise<void>

executePrepared

Type Parameters

Parameters

Returns Promise<Table<T>>

executePreparedStream

Parameters

Returns AsyncGenerator<FlightData>

Yields

executePreparedUpdate

Parameters

Returns Promise<UpdateResult>

executeUpdate

Parameters

Returns Promise<UpdateResult>

Example

getCatalogs

Type Parameters

Returns Promise<Table<T>>

Example

getDbSchemas

Type Parameters

Parameters

Optionalcatalog?: string

OptionaldbSchemaFilterPattern?: string

Returns Promise<Table<T>>

Example

getPrimaryKeys

Type Parameters

Parameters

Optionalcatalog?: string

OptionaldbSchema?: string

Returns Promise<Table<T>>

Example

getQueryInfo

Parameters

Returns Promise<FlightInfo>

getTables

Type Parameters

Parameters

Optionalcatalog?: string

OptionaldbSchemaFilterPattern?: string

OptionalincludeSchema?: boolean

OptionaltableNameFilterPattern?: string

OptionaltableTypes?: string[]

Returns Promise<Table<T>>

Example

getTableTypes

Type Parameters

Returns Promise<Table<T>>

`Optional`catalog?: string

`Optional`dbSchemaFilterPattern?: string

`Optional`catalog?: string

`Optional`dbSchema?: string

`Optional`catalog?: string

`Optional`dbSchemaFilterPattern?: string

`Optional`includeSchema?: boolean

`Optional`tableNameFilterPattern?: string

`Optional`tableTypes?: string[]