A client for interacting with a Trino cluster via its REST API.
Uses native fetch — no external HTTP dependencies. Supports automatic pagination, streaming via async generators, query cancellation, and configurable retry with exponential backoff.
Properties
| Name | Type |
|---|---|
| hostRequired | string |
| portRequired | number |
| headersRequired | Headers |
Methods
Sets a well-known Trino request header.
Parameters
| Name | Type |
|---|---|
| keyRequired | TrinoHeaderName |
| valueRequired | string |
Sets an arbitrary request header without key validation.
Parameters
| Name | Type |
|---|---|
| keyRequired | string |
| valueRequired | string |
Returns all currently configured request headers as a plain object.
Returns
Record<string, string>Executes a SQL statement and collects all result pages into a single array. Automatically follows nextUri pagination until the result set is complete.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TRow | — | — |
Parameters
| Name | Type |
|---|---|
| queryPropsRequired | QueryProps<TRow> |
Returns
Promise<TRow[]>Executes a SQL statement and returns an async generator that yields rows one at a time as pages are fetched.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TRow | — | — |
Parameters
| Name | Type |
|---|---|
| queryPropsRequired | QueryProps<TRow> |
Returns
Promise<AsyncGenerator<TRow>>Cancels a running query via its query ID.
Parameters
| Name | Type |
|---|---|
| queryIdRequired | string |
Returns
Promise<void>Cancels all currently active queries tracked by this client.
Returns
Promise<void>Returns the IDs of all currently active (in-flight) queries.
Returns
string[]Lists all schemas in the given catalog.
Parameters
| Name | Type |
|---|---|
| getSchemasPropsRequired | GetSchemasProps |
Returns
Promise<string[]>Lists all base tables in the given catalog and schema.
Parameters
| Name | Type |
|---|---|
| getTablesPropsRequired | GetTablesProps |
Returns
Promise<string[]>Lists all views in the given catalog and schema.
Parameters
| Name | Type |
|---|---|
| getViewsPropsRequired | GetViewsProps |
Returns
Promise<string[]>Parameters
| Name | Type |
|---|---|
| getColumnsPropsRequired | GetColumnsProps |
Returns
Promise<
| ColumnInfo[]
| [name: string, type: string, extra: string, description: string][]
>Drops a table if it exists.
Parameters
| Name | Type |
|---|---|
| dropTablePropsRequired | DropTableProps |
Returns
Promise<void>true if the statement executed successfully
Creates an external table with the given column definitions and storage properties.
Parameters
| Name | Type |
|---|---|
| createTablePropsRequired | CreateTableProps |
Returns
Promise<void>Base error for Trino client errors.
Constructor
| Name | Type |
|---|---|
| messageRequired | string |
Human-readable error message. | |
| statusCode? | number |
HTTP status code from the Trino response. | |
Properties
| Name | Type |
|---|---|
| statusCode? | number |
HTTP status code if available. | |
Error when a query is cancelled via AbortSignal.
Constructor
| Name | Type |
|---|---|
| messageRequired | string |
Human-readable cancellation message. | |
| queryId? | string |
The query ID that was cancelled, if known. | |
Properties
| Name | Type |
|---|---|
| queryId? | string |
The query ID that was cancelled. | |
Error during Trino query execution (Trino returned an error in the response).
Constructor
| Name | Type |
|---|---|
| messageRequired | string |
Human-readable error message from Trino. | |
| queryIdRequired | string |
The Trino query ID that produced the error. | |
| errorCodeRequired | number |
Numeric Trino error code. | |
| errorNameRequired | string |
Trino error name (e.g. “TABLE_NOT_FOUND”). | |
| errorTypeRequired | string |
Trino error type (e.g. “USER_ERROR”, “INTERNAL_ERROR”). | |
Properties
| Name | Type |
|---|---|
| queryIdRequired | string |
The Trino query ID that failed. | |
| errorCodeRequired | number |
Trino error code. | |
| errorNameRequired | string |
Trino error name (e.g. “TABLE_NOT_FOUND”). | |
| errorTypeRequired | string |
Trino error type (e.g. “USER_ERROR”, “INTERNAL_ERROR”). | |
Error when a query exceeds its timeout.
Constructor
| Name | Type |
|---|---|
| messageRequired | string |
Human-readable timeout error message. | |
| queryId? | string |
The query ID that timed out, if known. | |
Properties
| Name | Type |
|---|---|
| queryId? | string |
The query ID that timed out, if available. | |
Configuration for automatic retry behavior.
Properties
| Name | Type |
|---|---|
| maxRetries? | number |
Maximum number of retry attempts. 3 | |
| initialDelay? | number |
Initial delay between retries in ms. 1000 | |
| maxDelay? | number |
Maximum delay between retries in ms. 30000 | |
| backoffMultiplier? | number |
Multiplier for exponential backoff. 2 | |
| retryableStatusCodes? | number[] |
HTTP status codes that trigger a retry. [429, 500, 502, 503, 504] | |
| Name | Type |
|---|---|
| QUEUED | "QUEUED" |
| PLANNING | "PLANNING" |
| STARTING | "STARTING" |
| RUNNING | "RUNNING" |
| FINISHED | "FINISHED" |
| CANCELED | "CANCELED" |
| FAILED | "FAILED" |
Well-known Trino request headers.
| Name | Type |
|---|---|
| "X-Trino-User" | |
| "X-Trino-Original-User" | |
| "X-Trino-Source" | |
| "X-Trino-Catalog" | |
| "X-Trino-Schema" | |
| "X-Trino-Time-Zone" | |
| "X-Trino-Language" | |
| "X-Trino-Trace-Token" | |
| "X-Trino-Session" | |
| "X-Trino-Role" | |
| "X-Trino-Prepared-Statement" | |
| "X-Trino-Transaction-Id" | |
| "X-Trino-Client-Info" | |
| "X-Trino-Client-Tags" | |
| "X-Trino-Resource-Estimate" | |
| "X-Trino-Extra-Credential" | |
Authentication credentials — either basic or bearer.
Basic authentication using username and password.
Properties
| Name | Type |
|---|---|
| typeRequired | "basic" |
| usernameRequired | string |
The authentication username. | |
| passwordRequired | string |
The authentication password. | |
Bearer token authentication (e.g. OAuth2 or JWT).
Properties
| Name | Type |
|---|---|
| typeRequired | "bearer" |
| tokenRequired | string |
The bearer token value. | |
Type signature for complex column types.
Properties
| Name | Type |
|---|---|
| rawTypeRequired | string |
| argumentsRequired | ClientTypeSignatureParameter[] |
Parameter for type signatures (discriminated union).
Definition
| { kind: "TYPE"; typeSignature: ClientTypeSignature }
| { kind: "LONG"; longLiteral: number }
| {
kind: "VARIABLE"
namedTypeSignature: {
name?: string
typeSignature: ClientTypeSignature
}
}Column definition in query results.
Properties
| Name | Type |
|---|---|
| nameRequired | string |
Column name. | |
| typeRequired | string |
Type string (e.g. “varchar”, “bigint”, “array(varchar)”). | |
| typeSignature? | ClientTypeSignature |
Detailed type signature for complex types. | |
A column definition for CREATE TABLE statements.
Properties
| Name | Type |
|---|---|
| nameRequired | string |
The column name. | |
| typeRequired | string |
The Trino column type (e.g., “VARCHAR”, “INTEGER”, “TIMESTAMP(3)”). | |
Column metadata returned by columns() when asObject is true.
Properties
| Name | Type |
|---|---|
| nameRequired | string |
Column name. | |
| typeRequired | string |
Trino data type (e.g. “varchar”, “integer”, “timestamp(3)”). | |
| extraRequired | string |
Extra column metadata (e.g. partition key info). | |
| descriptionRequired | string |
Column description/comment. | |
Parameters for creating a table.
Properties
| Name | Type |
|---|---|
| catalogRequired | string |
The catalog to create the table in. | |
| schemaRequired | string |
The schema to create the table in. | |
| tableRequired | string |
The table name to create. | |
| columnsRequired | ColumnDefinition[] |
Column definitions (name + type pairs). | |
| properties? | Record<string, string> |
Optional WITH clause properties (e.g., external_location, format). | |
| ifNotExists? | boolean |
Whether to use IF NOT EXISTS (default: true). | |
Parameters for dropping a table.
Properties
| Name | Type |
|---|---|
| catalogRequired | string |
The catalog containing the table. | |
| schemaRequired | string |
The schema containing the table. | |
| tableRequired | string |
The table name to drop. | |
Location in the query where an error occurred.
Properties
| Name | Type |
|---|---|
| lineNumberRequired | number |
| columnNumberRequired | number |
Detailed failure information including stack trace.
Properties
| Name | Type |
|---|---|
| typeRequired | string |
| message? | string |
| cause? | FailureInfo |
| suppressedRequired | FailureInfo[] |
| stackRequired | string[] |
| errorLocation? | ErrorLocation |
Parameters for listing columns of a table.
Properties
| Name | Type |
|---|---|
| tableRequired | string |
The table to describe. | |
| asObject? | boolean |
When true, returns typed objects instead of raw tuples. false | |
Parameters for listing schemas in a catalog.
Properties
| Name | Type |
|---|---|
| catalogRequired | string |
The catalog to inspect. | |
Parameters for listing tables in a catalog and schema.
Properties
| Name | Type |
|---|---|
| schemaRequired | string |
The schema to inspect. | |
Parameters for listing views in a catalog and schema.
Properties
| Name | Type |
|---|---|
| schemaRequired | string |
The schema to inspect. | |
Error information when a query fails.
Properties
| Name | Type |
|---|---|
| messageRequired | string |
| sqlState? | string |
| errorCodeRequired | number |
| errorNameRequired | string |
| errorTypeRequired | | "USER_ERROR"
| "INTERNAL_ERROR"
| "EXTERNAL"
| "INSUFFICIENT_RESOURCES" |
| errorLocation? | ErrorLocation |
| failureInfo? | FailureInfo |
Parameters for executing a SQL query or stream.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TRow | — | unknown |
Properties
| Name | Type |
|---|---|
| sqlRequired | string |
The SQL statement to execute. | |
| impersonateAs? | string |
Optional Trino user to impersonate via X-Trino-User. | |
| signal? | AbortSignal |
Abort signal for cancelling the query. | |
| transform? | (row: unknown[], columns: Column[]) => TRow |
Optional transform function to map raw row arrays to typed objects. | |
Main query results response from Trino.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
TRow | — | unknown |
Properties
| Name | Type |
|---|---|
| idRequired | string |
The unique query ID. | |
| infoUriRequired | string |
URI for the query info page. | |
| partialCancelUri? | string |
URI for partial cancellation. | |
| nextUri? | string |
URI to fetch next batch of results. If absent, query is complete. | |
| columns? | Column[] |
Column definitions for the result set. | |
| data? | TRow[] |
Result data rows. | |
| statsRequired | Stats |
Statistics about query execution. | |
| error? | QueryError |
Error information if query failed. | |
| warningsRequired | Warning[] |
List of warnings. | |
| updateType? | string |
Type of update operation (e.g. “CREATE TABLE”). | |
| updateCount? | number |
Number of rows updated (for DML operations). | |
Statistics for a query execution stage.
Properties
| Name | Type |
|---|---|
| stageIdRequired | string |
| stateRequired | string |
| doneRequired | boolean |
| nodesRequired | number |
| totalSplitsRequired | number |
| queuedSplitsRequired | number |
| runningSplitsRequired | number |
| completedSplitsRequired | number |
| cpuTimeMillisRequired | number |
| wallTimeMillisRequired | number |
| processedRowsRequired | number |
| processedBytesRequired | number |
| physicalInputBytesRequired | number |
| failedTasksRequired | number |
| coordinatorOnlyRequired | boolean |
| subStagesRequired | StageStats[] |
Statistics about query execution.
Properties
| Name | Type |
|---|---|
| stateRequired | State |
| queuedRequired | boolean |
| scheduledRequired | boolean |
| progressPercentage? | number |
| runningPercentage? | number |
| nodesRequired | number |
| totalSplitsRequired | number |
| queuedSplitsRequired | number |
| runningSplitsRequired | number |
| completedSplitsRequired | number |
| cpuTimeMillisRequired | number |
| wallTimeMillisRequired | number |
| queuedTimeMillisRequired | number |
| elapsedTimeMillisRequired | number |
| processedRowsRequired | number |
| processedBytesRequired | number |
| physicalInputBytesRequired | number |
| peakMemoryBytesRequired | number |
| spilledBytesRequired | number |
| rootStage? | StageStats |
Configuration options for creating a TrinoClient instance.
Properties
| Name | Type |
|---|---|
| hostRequired | string |
Trino coordinator hostname including protocol (e.g. "https://trino.example.com"). | |
| portRequired | number |
Port the Trino coordinator listens on. | |
| authRequired | Auth |
Authentication credentials — either basic (username/password) or bearer (token). | |
| catalogRequired | string |
Default catalog used for all queries. | |
| schema? | string |
Optional default schema used for all queries. | |
| source? | string |
Source identifier sent as X-Trino-Source header. "nodejs" | |
| retry? | RetryConfig |
Retry configuration for failed requests. | |
| timeout? | number |
Default timeout for queries in milliseconds. No timeout when omitted. | |
A well-known Trino request header name.
Warning from Trino during query execution.
Properties
| Name | Type |
|---|---|
| warningCodeRequired | { code: number; name: string } |
| messageRequired | string |