Presto Client REST API

    • 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 will contain a nextUri URL attribute.

    • A DELETE to nextUri 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.

    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.

    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.

    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.

    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.

    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:

    Class PrestoHeaders enumerates all the HTTP request and response headers allowed by the Presto client REST API.