Couchbase Analytics Query API

openapi: 3.2.0
info:
  title: Couchbase Analytics Service REST Analytics Query API
  description: The Couchbase Analytics Service REST API provides access to the Analytics service for running complex analytical queries on operational data without impacting performance of key-value operations. It supports SQL++ queries for analytics, management of links to external data sources, and configuration of user-defined libraries. The service enables real-time analytics on JSON data alongside transactional workloads.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:8095
  description: Analytics Service (default port)
- url: https://localhost:18095
  description: Analytics Service (SSL)
security:
- basicAuth: []
tags:
- name: Analytics Query
  description: Endpoints for executing SQL++ analytics queries and retrieving results.
paths:
  /analytics/service:
    post:
      operationId: executeAnalyticsQuery
      summary: Execute an analytics query
      description: Executes a SQL++ analytics query against the Analytics service. The endpoint implements the same HTTP interface as the Couchbase Query service but targets the Analytics engine for complex analytical workloads.
      tags:
      - Analytics Query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsQueryRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AnalyticsQueryRequest'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryResult'
        '400':
          description: Invalid query syntax or parameters
        '401':
          description: Unauthorized access
components:
  schemas:
    AnalyticsQueryResult:
      type: object
      description: Analytics 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
            resultCount:
              type: integer
              description: Number of results returned
            resultSize:
              type: integer
              description: Size of results in bytes
            processedObjects:
              type: integer
              description: Number of objects processed
            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
    AnalyticsQueryRequest:
      type: object
      description: Analytics query execution request
      required:
      - statement
      properties:
        statement:
          type: string
          description: The SQL++ analytics statement to execute
        pretty:
          type: boolean
          description: Whether to format the results with indentation
        readonly:
          type: boolean
          description: Whether to restrict to read-only operations
        client_context_id:
          type: string
          description: Client-provided context identifier for request tracking
        timeout:
          type: string
          description: Maximum execution time for the query (e.g., 10s, 5m)
        scan_consistency:
          type: string
          description: Consistency requirement for the query
          enum:
          - not_bounded
          - request_plus
        args:
          type: array
          description: Positional parameters for the query
          items: {}
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Couchbase Server credentials.
externalDocs:
  description: Couchbase Analytics Service REST API Documentation
  url: https://docs.couchbase.com/server/current/analytics/rest-analytics.html