Trino Queries API

openapi: 3.0.3
info:
  title: Trino Client REST Cluster Queries API
  description: 'The Trino Client REST API allows clients to submit SQL queries to a Trino coordinator and retrieve results. The protocol is HTTP-based: clients POST a query to /v1/statement, then poll GET on the returned nextUri until results are fully retrieved, and may DELETE nextUri to cancel a running query. Trino is a distributed SQL query engine for big data analytics supporting connectors to data lakes, relational databases, and NoSQL stores.'
  version: '480'
  contact:
    name: Trino Community
    url: https://trino.io/community.html
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://{host}:{port}
  description: Trino coordinator
  variables:
    host:
      default: localhost
      description: Trino coordinator hostname or IP
    port:
      default: '8080'
      description: Trino coordinator HTTP port
security: []
tags:
- name: Queries
  description: Submit and manage SQL queries
paths:
  /v1/statement:
    post:
      operationId: submitStatement
      summary: Submit SQL Statement
      description: Submits an SQL query string for execution. Returns an initial QueryResults response which may contain the first batch of results and/or a nextUri for polling subsequent results. Clients must include the X-Trino-User header at minimum. Additional context headers (catalog, schema, session properties) may be provided to configure the query environment.
      tags:
      - Queries
      parameters:
      - name: X-Trino-User
        in: header
        required: true
        description: The user identity submitting the query
        schema:
          type: string
        example: alice
      - name: X-Trino-Catalog
        in: header
        required: false
        description: Default catalog for the query session
        schema:
          type: string
        example: hive
      - name: X-Trino-Schema
        in: header
        required: false
        description: Default schema for the query session
        schema:
          type: string
        example: default
      - name: X-Trino-Source
        in: header
        required: false
        description: Identifies the client application submitting the query
        schema:
          type: string
        example: my-app
      - name: X-Trino-Session
        in: header
        required: false
        description: Comma-separated list of session property assignments in key=value format
        schema:
          type: string
        example: query_max_memory=10GB,query_max_run_time=5m
      - name: X-Trino-Transaction-Id
        in: header
        required: false
        description: Transaction identifier for query grouping. Use NONE for auto-commit.
        schema:
          type: string
        example: NONE
      - name: X-Trino-Client-Tags
        in: header
        required: false
        description: Comma-separated client tags for resource group matching
        schema:
          type: string
      - name: X-Trino-Client-Info
        in: header
        required: false
        description: Arbitrary client-supplied metadata about the client
        schema:
          type: string
      - name: X-Trino-Time-Zone
        in: header
        required: false
        description: Time zone for the query session (IANA tz database format)
        schema:
          type: string
        example: America/New_York
      - name: X-Trino-Language
        in: header
        required: false
        description: BCP 47 language tag for locale-sensitive operations
        schema:
          type: string
        example: en-US
      - name: X-Trino-Trace-Token
        in: header
        required: false
        description: External trace token for distributed tracing correlation
        schema:
          type: string
      - name: X-Trino-Extra-Credential
        in: header
        required: false
        description: Connector-specific extra credentials in name=value format. May appear multiple times.
        schema:
          type: string
      requestBody:
        required: true
        description: The SQL query string to execute
        content:
          text/plain:
            schema:
              type: string
            example: SELECT * FROM system.runtime.nodes
      responses:
        '200':
          description: Query accepted and initial results returned
          headers:
            X-Trino-Set-Catalog:
              description: New default catalog set by the query (USE CATALOG statement)
              schema:
                type: string
            X-Trino-Set-Schema:
              description: New default schema set by the query (USE SCHEMA statement)
              schema:
                type: string
            X-Trino-Set-Session:
              description: Session property set by the query
              schema:
                type: string
            X-Trino-Clear-Session:
              description: Session property cleared by the query
              schema:
                type: string
            X-Trino-Started-Transaction-Id:
              description: Transaction ID started by a START TRANSACTION statement
              schema:
                type: string
            X-Trino-Clear-Transaction-Id:
              description: Indicates the transaction was committed or rolled back
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResults'
        '400':
          description: Bad request — malformed SQL or invalid session parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryError'
        '429':
          description: Too many requests. Client must wait the duration specified in Retry-After header before retrying.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying
              schema:
                type: integer
        '503':
          description: Service unavailable — transient cluster error; retry after 50-100ms
  /v1/statement/{queryId}/{token}:
    get:
      operationId: getQueryResults
      summary: Get Query Results
      description: Retrieves the next batch of results for a running query. Clients should follow the nextUri from a previous QueryResults response. When no nextUri is present in the response, the query is complete.
      tags:
      - Queries
      parameters:
      - name: queryId
        in: path
        required: true
        description: The unique query identifier returned by POST /v1/statement
        schema:
          type: string
        example: 20240101_120000_00001_abcde
      - name: token
        in: path
        required: true
        description: Sequential token for paging through results
        schema:
          type: integer
          format: int64
        example: 1
      - name: X-Trino-User
        in: header
        required: true
        description: The user identity (must match original query submission)
        schema:
          type: string
      - name: maxWait
        in: query
        required: false
        description: Maximum duration to wait for results before returning empty batch
        schema:
          type: string
        example: 2s
      - name: targetResultSize
        in: query
        required: false
        description: Desired result batch size hint
        schema:
          type: string
        example: 1MB
      responses:
        '200':
          description: Next batch of results (may be empty if still processing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResults'
        '404':
          description: Query not found — expired or already cancelled
        '429':
          description: Too many concurrent polls; wait and retry
          headers:
            Retry-After:
              schema:
                type: integer
    delete:
      operationId: cancelQuery
      summary: Cancel Query
      description: Cancels a running query. Clients should DELETE the nextUri returned by the most recent QueryResults response to abort execution.
      tags:
      - Queries
      parameters:
      - name: queryId
        in: path
        required: true
        description: The unique query identifier
        schema:
          type: string
      - name: token
        in: path
        required: true
        description: Sequential token matching the current position
        schema:
          type: integer
          format: int64
      - name: X-Trino-User
        in: header
        required: true
        description: The user identity
        schema:
          type: string
      responses:
        '204':
          description: Query successfully cancelled
        '404':
          description: Query not found
  /v1/query:
    get:
      operationId: listQueries
      summary: List Active Queries
      description: Returns a list of currently running and recently completed queries on the Trino coordinator. Useful for monitoring and management UIs.
      tags:
      - Queries
      parameters:
      - name: state
        in: query
        required: false
        description: Filter queries by state
        schema:
          type: string
          enum:
          - QUEUED
          - PLANNING
          - STARTING
          - RUNNING
          - FINISHING
          - FINISHED
          - FAILED
      - name: limit
        in: query
        required: false
        description: Maximum number of queries to return
        schema:
          type: integer
          default: 100
      responses:
        '200':
          description: List of query summaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QuerySummary'
components:
  schemas:
    ErrorLocation:
      type: object
      description: Source location of a query error
      properties:
        lineNumber:
          type: integer
          description: 1-based line number in the SQL query
        columnNumber:
          type: integer
          description: 1-based column number in the SQL query
    Column:
      type: object
      description: Column metadata in a query result set
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: Column name
          example: node_id
        type:
          type: string
          description: Trino type name
          example: varchar
        typeSignature:
          type: object
          description: Structured type signature for complex types
          properties:
            rawType:
              type: string
            arguments:
              type: array
              items: {}
    StageStats:
      type: object
      description: Statistics for a single query stage
      properties:
        stageId:
          type: string
        state:
          type: string
        done:
          type: boolean
        nodes:
          type: integer
        totalSplits:
          type: integer
          format: int64
        queuedSplits:
          type: integer
          format: int64
        runningSplits:
          type: integer
          format: int64
        completedSplits:
          type: integer
          format: int64
        cpuTimeMillis:
          type: integer
          format: int64
        wallTimeMillis:
          type: integer
          format: int64
        processedRows:
          type: integer
          format: int64
        processedBytes:
          type: integer
          format: int64
        subStages:
          type: array
          items:
            $ref: '#/components/schemas/StageStats'
    QueryResults:
      type: object
      description: Response from /v1/statement or a nextUri GET containing query results
      properties:
        id:
          type: string
          description: Unique query identifier
          example: 20240101_120000_00001_abcde
        infoUri:
          type: string
          format: uri
          description: URI for human-readable query information in the Trino Web UI
        nextUri:
          type: string
          format: uri
          description: URI to fetch the next batch of results. Absent when the query is complete. Clients must GET this URI to continue receiving results.
        columns:
          type: array
          description: Column definitions for the result set
          items:
            $ref: '#/components/schemas/Column'
        data:
          type: array
          description: Result rows as arrays of values ordered by column definitions. Absent when no data is available yet.
          items:
            type: array
            items: {}
        updateType:
          type: string
          description: DDL/DML operation type for non-SELECT statements (e.g., "CREATE TABLE", "INSERT")
          example: CREATE TABLE
        updateCount:
          type: integer
          format: int64
          description: Number of rows affected by a DML statement
        stats:
          $ref: '#/components/schemas/QueryStats'
        error:
          $ref: '#/components/schemas/QueryError'
        warnings:
          type: array
          description: Non-fatal warnings from query execution
          items:
            $ref: '#/components/schemas/Warning'
    Warning:
      type: object
      description: Non-fatal warning from query execution
      properties:
        warningCode:
          type: object
          properties:
            code:
              type: integer
            name:
              type: string
        message:
          type: string
    QueryError:
      type: object
      description: Error information when a query fails
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Query exceeded maximum memory limit of 10GB
        sqlState:
          type: string
          description: ANSI SQL state code
          example: '42000'
        errorCode:
          type: integer
          description: Trino numeric error code
        errorName:
          type: string
          description: Symbolic error name
          example: QUERY_EXCEEDED_MEMORY_LIMIT
        errorType:
          type: string
          description: Error classification
          enum:
          - USER_ERROR
          - INTERNAL_ERROR
          - INSUFFICIENT_RESOURCES
          - EXTERNAL
        errorLocation:
          $ref: '#/components/schemas/ErrorLocation'
        failureInfo:
          type: object
          description: Detailed exception information
    QueryStats:
      type: object
      description: Runtime statistics for a query
      properties:
        state:
          type: string
          description: Current query state
          enum:
          - QUEUED
          - PLANNING
          - STARTING
          - RUNNING
          - FINISHING
          - FINISHED
          - FAILED
        queued:
          type: boolean
        scheduled:
          type: boolean
        nodes:
          type: integer
          description: Number of nodes participating in the query
        totalSplits:
          type: integer
          format: int64
        queuedSplits:
          type: integer
          format: int64
        runningSplits:
          type: integer
          format: int64
        completedSplits:
          type: integer
          format: int64
        cpuTimeMillis:
          type: integer
          format: int64
        wallTimeMillis:
          type: integer
          format: int64
        queuedTimeMillis:
          type: integer
          format: int64
        elapsedTimeMillis:
          type: integer
          format: int64
        processedRows:
          type: integer
          format: int64
        processedBytes:
          type: integer
          format: int64
        peakMemoryBytes:
          type: integer
          format: int64
        spilledBytes:
          type: integer
          format: int64
        rootStage:
          $ref: '#/components/schemas/StageStats'
        progressPercentage:
          type: number
          format: double
          minimum: 0
          maximum: 100
    QuerySummary:
      type: object
      description: Summary of a query for list views
      properties:
        queryId:
          type: string
          description: Unique query identifier
        state:
          type: string
          description: Current query state
        query:
          type: string
          description: The SQL text (may be truncated)
        self:
          type: string
          format: uri
          description: URI for the full query detail
        queryStats:
          $ref: '#/components/schemas/QueryStats'
        session:
          type: object
          description: Session context for the query
          properties:
            user:
              type: string
            catalog:
              type: string
            schema:
              type: string
            source:
              type: string
externalDocs:
  description: Trino Client REST API Documentation
  url: https://trino.io/docs/current/develop/client-protocol.html