Base error for Trino client errors.
Constructor
new TrinoClientError(message, statusCode?)Parameters
| Parameter | Type | Default Value |
|---|---|---|
| message | string | — |
| statusCode? | number | — |
Properties
| Property | Type | Default Value | |
|---|---|---|---|
| statusCode? | undefined | number | — | |
Modifiers: readonlyHTTP status code if available. | |||
Extends
ErrorError during Trino query execution (Trino returned an error in the response).
Constructor
new TrinoQueryError(message, queryId, errorCode, errorName, errorType)Parameters
| Parameter | Type | Default Value |
|---|---|---|
| message | string | — |
| queryId | string | — |
| errorCode | number | — |
| errorName | string | — |
| errorType | string | — |
Properties
| Property | Type | Default Value | |
|---|---|---|---|
| queryId | string | — | |
Modifiers: readonlyThe Trino query ID that failed. | |||
| errorCode | number | — | |
Modifiers: readonlyTrino error code. | |||
| errorName | string | — | |
Modifiers: readonlyTrino error name (e.g. “TABLE_NOT_FOUND”). | |||
| errorType | string | — | |
Modifiers: readonlyTrino error type (e.g. “USER_ERROR”, “INTERNAL_ERROR”). | |||
Extends
ErrorError when a query exceeds its timeout.
Constructor
new TrinoTimeoutError(message, queryId?)Parameters
| Parameter | Type | Default Value |
|---|---|---|
| message | string | — |
| queryId? | string | — |
Properties
| Property | Type | Default Value | |
|---|---|---|---|
| queryId? | undefined | string | — | |
Modifiers: readonlyThe query ID that timed out, if available. | |||
Extends
ErrorError when a query is cancelled via AbortSignal.
Constructor
new TrinoCancellationError(message, queryId?)Parameters
| Parameter | Type | Default Value |
|---|---|---|
| message | string | — |
| queryId? | string | — |
Properties
| Property | Type | Default Value | |
|---|---|---|---|
| queryId? | undefined | string | — | |
Modifiers: readonlyThe query ID that was cancelled. | |||
Extends
ErrorA 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.
Constructor
new TrinoClient({
host,
port,
auth,
catalog,
schema,
source,
retry,
timeout,
})Parameters
| Parameter | Type | Default Value |
|---|---|---|
| { host, port, auth, catalog, schema, source, retry, timeout, } | TrinoClientProps | — |
Creates a new TrinoClient instance.
Properties
| Property | Type | Default Value |
|---|---|---|
| host | string | — |
| port | number | — |
| headers | Headers | — |
Methods
| Method | Type | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| setHeader | (key: "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", value: string) => void | |||||||||||||
Sets a well-known Trino request header. Parameters
Returnsvoid | ||||||||||||||
| setRawHeader | (key: string, value: string) => void | |||||||||||||
Sets an arbitrary request header without key validation. Parameters
Returnsvoid | ||||||||||||||
| getHeaders | () => Record<…> | |||||||||||||
Returns all currently configured request headers as a plain object. ReturnsRecord<string, string> | ||||||||||||||
| query | <T>({
sql,
impersonateAs,
signal,
transform,
}: QueryProps<…>) => Promise<…> | |||||||||||||
Executes a SQL statement and collects all result pages into a single array.
Automatically follows Type Parameters
Parameters
ReturnsPromise<Array<T>>Modifiers: async | ||||||||||||||
| stream | <T>({
sql,
impersonateAs,
signal,
transform,
}: QueryProps<…>) => Promise<…> | |||||||||||||
Executes a SQL statement and returns an async generator that yields rows one at a time as pages are fetched. Type Parameters
Parameters
ReturnsPromise<AsyncGenerator<T, any, any>>Modifiers: async | ||||||||||||||
| cancelQuery | (queryId: string) => Promise<…> | |||||||||||||
Cancels a running query via its query ID. Parameters
ReturnsPromise<void>Modifiers: async | ||||||||||||||
| cancelAllQueries | () => Promise<…> | |||||||||||||
Cancels all currently active queries tracked by this client. ReturnsPromise<void>Modifiers: async | ||||||||||||||
| getActiveQueries | () => Array<…> | |||||||||||||
Returns the IDs of all currently active (in-flight) queries. ReturnsArray<string> | ||||||||||||||
| schemas | ({ catalog }: GetSchemasProps) => Promise<…> | |||||||||||||
Lists all schemas in the given catalog. Parameters
ReturnsPromise<Array<string>>Modifiers: async | ||||||||||||||
| tables | ({ catalog, schema }: GetTablesProps) => Promise<…> | |||||||||||||
Lists all base tables in the given catalog and schema. Parameters
ReturnsPromise<Array<string>>Modifiers: async | ||||||||||||||
| views | ({ catalog, schema }: GetViewsProps) => Promise<…> | |||||||||||||
Lists all views in the given catalog and schema. Parameters
ReturnsPromise<Array<string>>Modifiers: async | ||||||||||||||
| columns | (props: GetColumnsProps & { asObject: true; }) => Promise<…> (+1 overload) | |||||||||||||
Overload 1Lists all columns for the given table as typed objects. Parameters
ReturnsPromise<Array<ColumnInfo>>Modifiers: asyncOverload 2Lists all columns for the given table as raw tuples. Parameters
ReturnsPromise<Array<[name: string, type: string, extra: string, description: string]>>Modifiers: async | ||||||||||||||
| dropTable | ({ catalog, schema, table }: DropTableProps) => Promise<…> | |||||||||||||
Drops a table if it exists. Parameters
ReturnsPromise<void>Modifiers: async | ||||||||||||||
| createTable | ({
catalog,
schema,
table,
columns,
properties,
ifNotExists = true,
}?: CreateTableProps) => Promise<…> | |||||||||||||
Creates an external table with the given column definitions and storage properties. Parameters
ReturnsPromise<void>Modifiers: async | ||||||||||||||
Configuration for automatic retry behavior.
Properties
| Property | Type | Modifiers |
|---|---|---|
| maxRetries? | number | — |
Maximum number of retry attempts. | ||
| initialDelay? | number | — |
Initial delay between retries in ms. | ||
| maxDelay? | number | — |
Maximum delay between retries in ms. | ||
| backoffMultiplier? | number | — |
Multiplier for exponential backoff. | ||
| retryableStatusCodes? | Array<number> | — |
HTTP status codes that trigger a retry. | ||
Members
| Member | Value |
|---|---|
| "QUEUED" | "QUEUED" |
| "PLANNING" | "PLANNING" |
| "STARTING" | "STARTING" |
| "RUNNING" | "RUNNING" |
| "FINISHED" | "FINISHED" |
| "CANCELED" | "CANCELED" |
| "FAILED" | "FAILED" |
Basic authentication using username and password.
Properties
| Property | Type | Modifiers |
|---|---|---|
| type | "basic" | — |
| username | string | — |
The authentication username. | ||
| password | string | — |
The authentication password. | ||
Bearer token authentication (e.g. OAuth2 or JWT).
Properties
| Property | Type | Modifiers |
|---|---|---|
| type | "bearer" | — |
| token | string | — |
The bearer token value. | ||
Type
BasicAuth | BearerAuthWell-known Trino request headers.
Members
| Member | Value |
|---|---|
| "X-Trino-User" | 0 |
| "X-Trino-Original-User" | 1 |
| "X-Trino-Source" | 2 |
| "X-Trino-Catalog" | 3 |
| "X-Trino-Schema" | 4 |
| "X-Trino-Time-Zone" | 5 |
| "X-Trino-Language" | 6 |
| "X-Trino-Trace-Token" | 7 |
| "X-Trino-Session" | 8 |
| "X-Trino-Role" | 9 |
| "X-Trino-Prepared-Statement" | 10 |
| "X-Trino-Transaction-Id" | 11 |
| "X-Trino-Client-Info" | 12 |
| "X-Trino-Client-Tags" | 13 |
| "X-Trino-Resource-Estimate" | 14 |
| "X-Trino-Extra-Credential" | 15 |
A well-known Trino request header 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"Location in the query where an error occurred.
Properties
| Property | Type | Modifiers |
|---|---|---|
| lineNumber | number | — |
| columnNumber | number | — |
Detailed failure information including stack trace.
Properties
| Property | Type | Modifiers |
|---|---|---|
| type | string | — |
| message? | string | — |
| cause? | FailureInfo | — |
| suppressed | Array<FailureInfo> | — |
| stack | Array<string> | — |
| errorLocation? | ErrorLocation | — |
Error information when a query fails.
Properties
| Property | Type | Modifiers |
|---|---|---|
| message | string | — |
| sqlState? | string | — |
| errorCode | number | — |
| errorName | string | — |
| errorType | "USER_ERROR" | "INTERNAL_ERROR" | "EXTERNAL" | "INSUFFICIENT_RESOURCES" | — |
| errorLocation? | ErrorLocation | — |
| failureInfo? | FailureInfo | — |
Warning from Trino during query execution.
Properties
| Property | Type | Modifiers |
|---|---|---|
| warningCode | { code: number; name: string; } | — |
| message | string | — |
Type signature for complex column types.
Properties
| Property | Type | Modifiers |
|---|---|---|
| rawType | string | — |
| arguments | Array<ClientTypeSignatureParameter> | — |
Type
{ kind: "TYPE"; typeSignature: ClientTypeSignature; } | { kind: "LONG"; longLiteral: number; } | { kind: "VARIABLE"; namedTypeSignature: { name?: string; typeSignature: ClientTypeSignature; }; }Column definition in query results.
Properties
| Property | Type | Modifiers |
|---|---|---|
| name | string | — |
Column name. | ||
| type | string | — |
Type string (e.g. “varchar”, “bigint”, “array(varchar)”). | ||
| typeSignature? | ClientTypeSignature | — |
Detailed type signature for complex types. | ||
Statistics for a query execution stage.
Properties
| Property | Type | Modifiers |
|---|---|---|
| stageId | string | — |
| state | string | — |
| done | boolean | — |
| nodes | number | — |
| totalSplits | number | — |
| queuedSplits | number | — |
| runningSplits | number | — |
| completedSplits | number | — |
| cpuTimeMillis | number | — |
| wallTimeMillis | number | — |
| processedRows | number | — |
| processedBytes | number | — |
| physicalInputBytes | number | — |
| failedTasks | number | — |
| coordinatorOnly | boolean | — |
| subStages | Array<StageStats> | — |
Statistics about query execution.
Properties
| Property | Type | Modifiers |
|---|---|---|
| state | State | — |
| queued | boolean | — |
| scheduled | boolean | — |
| progressPercentage? | number | — |
| runningPercentage? | number | — |
| nodes | number | — |
| totalSplits | number | — |
| queuedSplits | number | — |
| runningSplits | number | — |
| completedSplits | number | — |
| cpuTimeMillis | number | — |
| wallTimeMillis | number | — |
| queuedTimeMillis | number | — |
| elapsedTimeMillis | number | — |
| processedRows | number | — |
| processedBytes | number | — |
| physicalInputBytes | number | — |
| peakMemoryBytes | number | — |
| spilledBytes | number | — |
| rootStage? | StageStats | — |
Main query results response from Trino.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
T | — | unknown |
Properties
| Property | Type | Modifiers |
|---|---|---|
| id | string | — |
The unique query ID. | ||
| infoUri | 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? | Array<Column> | — |
Column definitions for the result set. | ||
| data? | Array<T> | — |
Result data rows. | ||
| stats | Stats | — |
Statistics about query execution. | ||
| error? | QueryError | — |
Error information if query failed. | ||
| warnings | Array<Warning> | — |
List of warnings. | ||
| updateType? | string | — |
Type of update operation (e.g. “CREATE TABLE”). | ||
| updateCount? | number | — |
Number of rows updated (for DML operations). | ||
Configuration options for creating a TrinoClient instance.
Properties
| Property | Type | Modifiers |
|---|---|---|
| host | string | — |
Trino coordinator hostname including protocol (e.g. | ||
| port | number | — |
Port the Trino coordinator listens on. | ||
| auth | Auth | — |
Authentication credentials — either basic (username/password) or bearer (token). | ||
| catalog | string | — |
Default catalog used for all queries. | ||
| schema? | string | — |
Optional default schema used for all queries. | ||
| source? | string | — |
Source identifier sent as | ||
| retry? | RetryConfig | — |
Retry configuration for failed requests. | ||
| timeout? | number | — |
Default timeout for queries in milliseconds. No timeout when omitted. | ||
Parameters for executing a SQL query or stream.
Type Parameters
| Parameter | Constraint | Default |
|---|---|---|
T | — | unknown |
Properties
| Property | Type | Modifiers |
|---|---|---|
| sql | string | — |
The SQL statement to execute. | ||
| impersonateAs? | string | — |
Optional Trino user to impersonate via | ||
| signal? | AbortSignal | — |
Abort signal for cancelling the query. | ||
| transform? | (row: unknown[], columns: Column[]) => T | — |
Optional transform function to map raw row arrays to typed objects. | ||
Parameters for listing schemas in a catalog.
Properties
| Property | Type | Modifiers |
|---|---|---|
| catalog | string | — |
The catalog to inspect. | ||
Parameters for listing tables in a catalog and schema.
Extends
GetSchemasPropsProperties
| Property | Type | Modifiers |
|---|---|---|
| schema | string | — |
The schema to inspect. | ||
| catalog | string | — |
The catalog to inspect. | ||
Parameters for listing views in a catalog and schema.
Extends
GetSchemasPropsProperties
| Property | Type | Modifiers |
|---|---|---|
| schema | string | — |
The schema to inspect. | ||
| catalog | string | — |
The catalog to inspect. | ||
Parameters for listing columns of a table.
Extends
GetTablesPropsProperties
| Property | Type | Modifiers |
|---|---|---|
| table | string | — |
The table to describe. | ||
| asObject? | boolean | — |
When true, returns typed objects instead of raw tuples. | ||
| schema | string | — |
The schema to inspect. | ||
| catalog | string | — |
The catalog to inspect. | ||
Column metadata returned by columns() when asObject is true.
Properties
| Property | Type | Modifiers |
|---|---|---|
| name | string | — |
Column name. | ||
| type | string | — |
Trino data type (e.g. “varchar”, “integer”, “timestamp(3)”). | ||
| extra | string | — |
Extra column metadata (e.g. partition key info). | ||
| description | string | — |
Column description/comment. | ||
Parameters for dropping a table.
Properties
| Property | Type | Modifiers |
|---|---|---|
| catalog | string | — |
The catalog containing the table. | ||
| schema | string | — |
The schema containing the table. | ||
| table | string | — |
The table name to drop. | ||
A column definition for CREATE TABLE statements.
Properties
| Property | Type | Modifiers |
|---|---|---|
| name | string | — |
The column name. | ||
| type | string | — |
The Trino column type (e.g., “VARCHAR”, “INTEGER”, “TIMESTAMP(3)”). | ||
Parameters for creating a table.
Properties
| Property | Type | Modifiers |
|---|---|---|
| catalog | string | — |
The catalog to create the table in. | ||
| schema | string | — |
The schema to create the table in. | ||
| table | string | — |
The table name to create. | ||
| columns | Array<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). | ||