Presto Client REST API¶
The Presto client allows users to submit Presto queries and view results. This note documents the REST API used by the Presto client.
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 will contain 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 Presto 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 header X-Presto-User
to the username for the session,
as well as a long list of other headers, documented below.
If the client request returns an HTTP 503, that means the server was busy, and the client should try again in 50-100 milliseconds. Any HTTP status other than 503 or 200 means that the query 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 will contain 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 below.
If the data
field of the JSON document is set, it contains a list of the rows
of data, and the columns
field will also be set to a list of the names and types of
the columns returned by the query. Most of the response headers should be treated like
browser cookies by the client, and echoed back as request headers in subsequent client requests,
as documented below.
To request the results in binary format, include binaryResults=true query parameter in the initial
/v1/statement
POST
request. The response JSON document will contain binaryData
field
with a list of base64-encoded pages in SerializedPage format. The
data
field will not be present.
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’s state on the server. It is not synchronized with the server’s query state and should 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. Refer to the class QueryResults
for more details.
Attribute |
Description |
---|---|
|
The ID of the query. |
|
If present, the URL that should be used in 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 |
Client Request Headers¶
This table lists all supported client request headers. Many of the headers can are updated in the client by response headers, and supplied in subsequent requests, just like browser cookies.
Request Header Name |
Description |
---|---|
|
Specifies the session user; must be supplied with every
request to |
|
For reporting purposes, this supplies the name of the software that submitted the query. |
|
The catalog to be used when running the query. Set by response header
|
|
The schema to be used when running the query. Set by response header
|
|
The timezone to be used when running the query, which by default is the timezone of the Presto engine. |
|
The language to be used when running the query and formatting results. The language
of the session can be set on a per-query basis using the |
|
Supplies a trace token to the Presto 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 Presto client run a |
|
Sets the catalog role that will be used in this request. 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 be used when running the query. Set by response header
|
|
Contains arbitrary information about the client program submitting the query. |
|
A comma-separated list of “tag” strings, used to identify Presto 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 that will be used in subsequent requests to be consistent with the response headers received.
Response Header Name |
Description |
---|---|
|
Instructs the client to set the catalog that will be sent in the
|
|
Instructs the client to set the schema that will be sent in the |
|
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
that will be sent 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 |
QueryResults
¶
When a query is executed by the client, a QueryResults
object is returned. QueryResults
contains
a long list of data members. These data members may be useful in tracking down problems:
Data Member |
Type |
Notes |
---|---|---|
|
|
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 |
PrestoHeaders
¶
Class PrestoHeaders
enumerates all the HTTP request and response headers allowed by the Presto client REST API.