Couchbase Query Execution API

openapi: 3.2.0
info:
  title: Couchbase Query Service REST Query Execution API
  description: The Couchbase Query Service REST API enables developers to execute SQL++ (formerly N1QL) queries against Couchbase Server and manage query service settings. It supports ad-hoc queries, prepared statements, and request-level parameter configuration. The API provides endpoints for query execution, monitoring active requests, and managing query service configuration across cluster nodes.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:8093
  description: Query Service (default port)
- url: https://localhost:18093
  description: Query Service (SSL)
security:
- basicAuth: []
tags:
- name: Query Execution
  description: Endpoints for executing SQL++ queries and managing query results.
paths:
  /query/service:
    get:
      operationId: executeQueryGet
      summary: Execute a SQL++ query via GET
      description: Executes a SQL++ query specified as a query parameter. This endpoint is intended for situations where use of the POST method is restricted.
      tags:
      - Query Execution
      parameters:
      - name: statement
        in: query
        required: true
        description: The SQL++ statement to execute
        schema:
          type: string
      - name: timeout
        in: query
        required: false
        description: Maximum execution time for the query (e.g., 10s, 5m)
        schema:
          type: string
      - name: readonly
        in: query
        required: false
        description: Whether to restrict the query to read-only operations
        schema:
          type: boolean
      - name: pretty
        in: query
        required: false
        description: Whether to format the query results with indentation
        schema:
          type: boolean
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Invalid query syntax or parameters
        '401':
          description: Unauthorized access
    post:
      operationId: executeQueryPost
      summary: Execute a SQL++ query via POST
      description: Executes a SQL++ query specified in the request body. Supports both application/json and application/x-www-form-urlencoded content types. This is the primary method for executing queries and supports all query parameters including named and positional parameters.
      tags:
      - Query Execution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '400':
          description: Invalid query syntax or parameters
        '401':
          description: Unauthorized access
components:
  schemas:
    QueryRequest:
      type: object
      description: SQL++ query execution request
      required:
      - statement
      properties:
        statement:
          type: string
          description: The SQL++ statement to execute
        timeout:
          type: string
          description: Maximum execution time (e.g., 10s, 5m)
        readonly:
          type: boolean
          description: Whether to restrict to read-only operations
        pretty:
          type: boolean
          description: Whether to format results with indentation
        scan_consistency:
          type: string
          description: Consistency requirement for the query
          enum:
          - not_bounded
          - at_plus
          - request_plus
          - statement_plus
        args:
          type: array
          description: Positional parameters for the query
          items: {}
        prepared:
          type: string
          description: Name of a prepared statement to execute
        client_context_id:
          type: string
          description: Client-provided context identifier for tracking
        max_parallelism:
          type: string
          description: Maximum parallelism for the query
        metrics:
          type: boolean
          description: Whether to include metrics in the response
    QueryResult:
      type: object
      description: SQL++ query execution result
      properties:
        requestID:
          type: string
          description: Unique identifier for the request
        clientContextID:
          type: string
          description: Client-provided context identifier
        signature:
          type: object
          description: Schema signature of the results
        results:
          type: array
          description: Array of result documents
          items: {}
        status:
          type: string
          description: Query execution status
          enum:
          - success
          - running
          - errors
          - completed
          - stopped
          - timeout
          - fatal
        metrics:
          type: object
          description: Query execution metrics
          properties:
            elapsedTime:
              type: string
              description: Total elapsed time
            executionTime:
              type: string
              description: Execution time excluding fetch
            resultCount:
              type: integer
              description: Number of results returned
            resultSize:
              type: integer
              description: Size of results in bytes
            mutationCount:
              type: integer
              description: Number of mutations performed
            errorCount:
              type: integer
              description: Number of errors encountered
            warningCount:
              type: integer
              description: Number of warnings generated
        errors:
          type: array
          description: List of errors if any occurred
          items:
            type: object
            properties:
              code:
                type: integer
                description: Error code
              msg:
                type: string
                description: Error message
        warnings:
          type: array
          description: List of warnings if any
          items:
            type: object
            properties:
              code:
                type: integer
                description: Warning code
              msg:
                type: string
                description: Warning message
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Couchbase Server credentials.
externalDocs:
  description: Couchbase Query Service REST API Documentation
  url: https://docs.couchbase.com/server/current/n1ql/n1ql-rest-api/index.html