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 thePOST
body, and returns a JSON document containing the query results. If there are more results, the JSON document contains anextUri
URL attribute.A
GET
to thenextUri
attribute returns the next batch of query results.A
DELETE
tonextUri
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 on 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 intermittent problem processing request and the client should try again in 50-100 milliseconds. Trino does not generate those codes by itself but those can be generated by gateways/load balancers in front of Trino. 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 members 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 can not 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.
Attribute |
Description |
---|---|
|
The ID of the query. |
|
If present, the URL to use for subsequent |
|
A list of the names and types of the columns returned by the query. |
|
The |
|
A human-readable string representing the operation. For a |
|
If query failed, the |
QueryResults
diagnostic attributes#
These QueryResults
data members may be useful in tracking down problems:
Attribute |
Type |
Description |
---|---|---|
|
|
Non-null only if the query resulted in an error. |
|
|
|
|
|
A usually-empty list of warnings. |
|
|
A class containing statistics about the query execution. Of particular
interest is |
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.
Header name |
Description |
---|---|
|
Specifies the session user. If not supplied, the session user is automatically determined via User mapping. |
|
Specifies the session’s original user. |
|
For reporting purposes, this supplies the name of the software that submitted the query. |
|
The catalog context for query processing. Set by response header
|
|
The schema context for query processing. Set by response header
|
|
The timezone for query processing. Defaults to the timezone of the Trino clusßter, and not the timezone of the client. |
|
The language to use when processing the query and formatting results,
formatted as a Java |
|
Supplies a trace token to the Trino engine to help identify log lines that originate with this query request. |
|
Supplies a comma-separated list of name=value pairs as session properties.
When the Trino client run a |
|
Sets the “role” for query processing. A “role” represents a collection of
permissions. Set by response header |
|
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. |
|
The transaction ID to use for query processing. Set by response header
|
|
Contains arbitrary information about the client program submitting the query. |
|
A comma-separated list of “tag” strings, used to identify Trino resource groups. |
|
A comma-separated list of |
|
Provides extra credentials to the connector. The header is a name=value
string that is saved in the session |
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.
Header name |
Description |
---|---|
|
Instructs the client to set the catalog in the |
|
Instructs the client to set the schema in the |
|
Instructs the client to set the session authorization user in the
|
|
Instructs the client to reset |
|
The value of the |
|
Instructs the client to remove the session property with the whose name is
the value of the |
|
Instructs the client to set |
|
Instructs the client to add the name=value pair to the set of prepared
statements in the |
|
Instructs the client to remove the prepared statement whose name is the
value of the |
|
Provides the transaction ID that the client should pass back in the
|
|
Instructs the client to clear the |
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.