Presto Foundation Statement API

openapi: 3.1.0
info:
  title: Presto Client REST Statement API
  description: 'The Presto Client REST API is the HTTP protocol used by Presto clients to

    submit SQL queries to a Presto coordinator and stream back results. Queries

    are submitted with POST /v1/statement, subsequent result pages are fetched

    by following the nextUri returned in each response, and queries can be

    cancelled by issuing DELETE on the nextUri. Session context such as user,

    catalog, schema, time zone, and language is conveyed through X-Presto-*

    request headers; coordinators echo back X-Presto-Set-* / X-Presto-Clear-*

    response headers that clients must propagate on subsequent requests.


    Supported authentication mechanisms on the coordinator include Kerberos,

    LDAP, password files, OAuth 2.0, and custom authenticators.

    '
  version: '0.290'
  contact:
    name: Presto Foundation
    url: https://prestodb.io/
  license:
    name: Apache 2.0
    url: https://github.com/prestodb/presto/blob/master/LICENSE
servers:
- url: http://{coordinator}:{port}
  description: Presto coordinator
  variables:
    coordinator:
      default: localhost
    port:
      default: '8080'
security: []
tags:
- name: Statement
  description: Submit, page, and cancel SQL queries.
paths:
  /v1/statement:
    post:
      tags:
      - Statement
      summary: Submit a SQL statement
      description: 'Submits a SQL query to the Presto coordinator. The request body is the

        raw SQL text. Returns a QueryResults JSON document that may include an

        initial columns/data batch and a nextUri to follow for subsequent pages.

        '
      operationId: submitStatement
      parameters:
      - name: X-Presto-User
        in: header
        required: true
        schema:
          type: string
        description: Session user.
      - name: X-Presto-Source
        in: header
        schema:
          type: string
        description: Client software name.
      - name: X-Presto-Catalog
        in: header
        schema:
          type: string
      - name: X-Presto-Schema
        in: header
        schema:
          type: string
      - name: X-Presto-Time-Zone
        in: header
        schema:
          type: string
      - name: X-Presto-Language
        in: header
        schema:
          type: string
      - name: X-Presto-Session
        in: header
        schema:
          type: string
        description: Comma-separated session properties (name=value).
      - name: X-Presto-Role
        in: header
        schema:
          type: string
      - name: X-Presto-Transaction-Id
        in: header
        schema:
          type: string
      - name: X-Presto-Trace-Token
        in: header
        schema:
          type: string
      - name: binaryResults
        in: query
        schema:
          type: boolean
          default: false
        description: Request binary-format result pages.
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              example: SELECT 1
      responses:
        '200':
          description: Initial QueryResults document.
          headers:
            X-Presto-Set-Catalog:
              schema:
                type: string
            X-Presto-Set-Schema:
              schema:
                type: string
            X-Presto-Set-Session:
              schema:
                type: string
            X-Presto-Clear-Session:
              schema:
                type: string
            X-Presto-Started-Transaction-Id:
              schema:
                type: string
            X-Presto-Clear-Transaction-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResults'
        '503':
          description: Server busy. The client should retry after a delay.
  /v1/statement/{queryId}/{token}:
    get:
      tags:
      - Statement
      summary: Fetch the next batch of results
      description: 'Follows the nextUri returned by a previous response to retrieve the next

        batch of results for the given query. The path shape here mirrors the

        coordinator''s nextUri scheme; clients should always use the literal

        nextUri returned in the previous response rather than constructing it.

        '
      operationId: getStatementResults
      parameters:
      - name: queryId
        in: path
        required: true
        schema:
          type: string
      - name: token
        in: path
        required: true
        schema:
          type: string
      - name: X-Presto-User
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Next QueryResults batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResults'
        '503':
          description: Server busy. Retry the same nextUri after a delay.
    delete:
      tags:
      - Statement
      summary: Cancel a running query
      description: 'DELETE on a query''s nextUri cancels the running query. Clients should

        delete the most recent nextUri received for the query.

        '
      operationId: cancelStatement
      parameters:
      - name: queryId
        in: path
        required: true
        schema:
          type: string
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Cancellation accepted.
components:
  schemas:
    QueryResults:
      type: object
      description: One page of query results returned by the coordinator.
      properties:
        id:
          type: string
          description: Server-assigned query id.
        infoUri:
          type: string
          format: uri
        nextUri:
          type: string
          format: uri
          description: URI to fetch the next page; absent when the query is complete.
        partialCancelUri:
          type: string
          format: uri
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
        data:
          type: array
          items:
            type: array
            items: {}
        stats:
          type: object
          additionalProperties: true
        error:
          type: object
          additionalProperties: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic auth, typically used with LDAP or password-file authenticators.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authenticator (when enabled on the coordinator).
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes: {}