Trino client REST API#

The REST API allows clients to submit SQL queries to Trino and receive the results. Clients include the CLI, the JDBC driver, and others provided by the community. The preferred method to interact with Trino is using these existing clients. This document provides details about the API for reference. It can also be used to implement your own client, if necessary.

HTTP methods#

A POST to /v1/statement runs the query string in the POST body, and returns a JSON document containing the query results. If there are more results, the JSON document contains a nextUri URL attribute.
A GET to the nextUri attribute returns the next batch of query results.
A DELETE to nextUri terminates a running query.

Overview of query processing#

A Trino client request is initiated by an HTTP POST to the endpoint /v1/statement, with a POST body consisting of the SQL query string. The caller may set various Client request headers. The headers are only required in the initial POST request, and not when following the nextUri links.

If the client request returns an HTTP 502, 503, or 504, that means there was an intermittent problem processing request and the client should try again in 50-100 ms. Trino does not generate those codes by itself, but those can be generated by load balancers in front of Trino.

Additionally, if the request returns a 429 status code, the client should retry the request using the Retry-After header value provided.

Any HTTP status other than 502, 503, 504 or 200 means that query processing has failed.

The /v1/statement POST request returns a JSON document of type QueryResults, as well as a collection of response headers. The QueryResults document contains an error field of type QueryError if the query has failed, and if that object is not present, the query succeeded. Important aspects of QueryResults are documented in the following sections.

If the data field of the JSON document is set, it contains a list of the rows of data. The columns field is set to a list of the names and types of the columns returned by the query. Most of the response headers are treated like browser cookies by the client, and echoed back as request headers in subsequent client requests, as documented below.

If the JSON document returned by the POST to /v1/statement does not contain a nextUri link, the query has completed, either successfully or unsuccessfully, and no additional requests need to be made. If the nextUri link is present in the document, there are more query results to be fetched. The client should loop executing a GET request to the nextUri returned in the QueryResults response object until nextUri is absent from the response.

The status field of the JSON document is for human consumption only, and provides a hint about the query state. It cannot be used to tell if the query is finished.

Important `QueryResults` attributes#

The most important attributes of the QueryResults JSON document returned by the REST API endpoints are listed in this table. For more details, refer to the class io.trino.client.QueryResults in module trino-client in the client directory of the Trino source code.

QueryResults attributes#
Attribute	Description
`id`	The ID of the query.
`nextUri`	If present, the URL to use for subsequent `GET` or `DELETE` requests. If not present, the query is complete or ended in error.
`columns`	A list of the names and types of the columns returned by the query.
`data`	The `data` attribute contains a list of the rows returned by the query request. Each row is itself a list that holds values of the columns in the row, in the order specified by the `columns` attribute.
`updateType`	A human-readable string representing the operation. For a `CREATE TABLE` request, the `updateType` is “CREATE TABLE”; for `SET SESSION` it is “SET SESSION”; etc.
`error`	If query failed, the `error` attribute contains a `QueryError` object. That object contains a `message`, an `errorCode` and other information about the error. See the `io.trino.client.QueryError` class in module `trino-client` in the `client` directory for more details.

`QueryResults` diagnostic attributes#

These QueryResults data members may be useful in tracking down problems:

QueryResults diagnostic attributes#
Attribute	Type	Description
`queryError`	`QueryError`	Non-null only if the query resulted in an error.
`failureInfo`	`FailureInfo`	`failureInfo` has detail on the reason for the failure, including a stack trace, and `FailureInfo.errorLocation`, providing the query line number and column number where the failure was detected.
`warnings`	`List<TrinoWarning>`	A usually empty list of warnings.
`statementStats`	`StatementStats`	A class containing statistics about the query execution. Of particular interest is `StatementStats.rootStage`, of type `StageStats`, providing statistics on the execution of each of the stages of query processing.

Client request headers#

This table lists all supported client request headers. Many of the headers can be updated in the client as response headers, and supplied in subsequent requests, just like browser cookies.

Client request headers#
Header name	Description
`X-Trino-User`	Specifies the session user. If not supplied, the session user is automatically determined via User mapping.
`X-Trino-Original-User`	Specifies the session’s original user.
`X-Trino-Source`	For reporting purposes, this supplies the name of the software that submitted the query.
`X-Trino-Catalog`	The catalog context for query processing. Set by response header `X-Trino-Set-Catalog`.
`X-Trino-Schema`	The schema context for query processing. Set by response header `X-Trino-Set-Schema`.
`X-Trino-Time-Zone`	The timezone for query processing. Defaults to the timezone of the Trino cluster, and not the timezone of the client.
`X-Trino-Language`	The language to use when processing the query and formatting results, formatted as a Java `Locale` string, for example `en-US` for US English. The language of the session can be set on a per-query basis using the `X-Trino-Language` HTTP header.
`X-Trino-Trace-Token`	Supplies a trace token to the Trino engine to help identify log lines that originate with this query request.
`X-Trino-Session`	Supplies a comma-separated list of name=value pairs as session properties. When the Trino client run a `SET SESSION name=value` query, the name=value pair is returned in the `X-Set-Trino-Session` response header, and added to the client’s list of session properties. If the response header `X-Trino-Clear-Session` is returned, its value is the name of a session property that is removed from the client’s accumulated list.
`X-Trino-Role`	Sets the “role” for query processing. A “role” represents a collection of permissions. Set by response header `X-Trino-Set-Role`. See CREATE ROLE to understand roles.
`X-Trino-Prepared-Statement`	A comma-separated list of the name=value pairs, where the names are names of previously prepared SQL statements, and the values are keys that identify the executable form of the named prepared statements.
`X-Trino-Transaction-Id`	The transaction ID to use for query processing. Set by response header `X-Trino-Started-Transaction-Id` and cleared by `X-Trino-Clear-Transaction-Id`.
`X-Trino-Client-Info`	Contains arbitrary information about the client program submitting the query.
`X-Trino-Client-Tags`	A comma-separated list of “tag” strings, used to identify Trino resource groups.
`X-Trino-Resource-Estimate`	A comma-separated list of `resource=value` type assignments. The possible choices of `resource` are `EXECUTION_TIME`, `CPU_TIME`, `PEAK_MEMORY` and `PEAK_TASK_MEMORY`. `EXECUTION_TIME` and `CPU_TIME` have values specified as airlift `Duration` strings The format is a double precision number followed by a `TimeUnit` string, for example `s` for seconds, `m` for minutes, `h` for hours, etc. “PEAK_MEMORY” and “PEAK_TASK_MEMORY” are specified as airlift `DataSize` strings, whose format is an integer followed by `B` for bytes; `kB` for kilobytes; `mB` for megabytes, `gB` for gigabytes, etc.
`X-Trino-Extra-Credential`	Provides extra credentials to the connector. The header is a name=value string that is saved in the session `Identity` object. The name and value are only meaningful to the connector.

Client response headers#

This table lists the supported client response headers. After receiving a response, a client must update the request headers used in subsequent requests to be consistent with the response headers received.

Client response headers#
Header name	Description
`X-Trino-Set-Catalog`	Instructs the client to set the catalog in the `X-Trino-Catalog` request header in subsequent client requests.
`X-Trino-Set-Schema`	Instructs the client to set the schema in the `X-Trino-Schema` request header in subsequent client requests.
`X-Trino-Set-Authorization-User`	Instructs the client to set the session authorization user in the `X-Trino-User` request header in subsequent client requests. `X-Trino-Original-User` should also be set.
`X-Trino-Reset-Authorization-User`	Instructs the client to reset `X-Trino-User` request header to its original value in subsequent client requests and remove `X-Trino-Original-User` to reset the authorization user back to the original user.
`X-Trino-Set-Session`	The value of the `X-Trino-Set-Session` response header is a string of the form property = value. It instructs the client include session property property with value value in the `X-Trino-Session` header of subsequent client requests.
`X-Trino-Clear-Session`	Instructs the client to remove the session property whose name is the value of the `X-Trino-Clear-Session` header from the list of session properties in the `X-Trino-Session` header in subsequent client requests.
`X-Trino-Set-Role`	Instructs the client to set `X-Trino-Role` request header to the catalog role supplied by the `X-Trino-Set-Role` header in subsequent client requests.
`X-Trino-Added-Prepare`	Instructs the client to add the name=value pair to the set of prepared statements in the `X-Trino-Prepared-Statement` request header in subsequent client requests.
`X-Trino-Deallocated-Prepare`	Instructs the client to remove the prepared statement whose name is the value of the `X-Trino-Deallocated-Prepare` header from the client’s list of prepared statements sent in the `X-Trino-Prepared-Statement` request header in subsequent client requests.
`X-Trino-Started-Transaction-Id`	Provides the transaction ID that the client should pass back in the `X-Trino-Transaction-Id` request header in subsequent requests.
`X-Trino-Clear-Transaction-Id`	Instructs the client to clear the `X-Trino-Transaction-Id` request header in subsequent requests.

`ProtocolHeaders`#

Class io.trino.client.ProtocolHeaders in module trino-client in the client directory of Trino source enumerates all the HTTP request and response headers allowed by the Trino client REST API.