Couchbase Search Queries API

openapi: 3.2.0
info:
  title: Couchbase Search Service REST Search Queries API
  description: The Couchbase Search Service REST API allows developers to create, manage, and query Full Text Indexes on Couchbase Server. It supports full-text search queries with features like fuzzy matching, faceted search, highlighting, and geospatial queries. The API provides endpoints for index definition, index management, and executing search queries across JSON documents stored in Couchbase buckets.
  version: '7.6'
  contact:
    name: Couchbase Support
    url: https://support.couchbase.com
  termsOfService: https://www.couchbase.com/terms-of-use
servers:
- url: https://localhost:8094
  description: Search Service (default port)
- url: https://localhost:18094
  description: Search Service (SSL)
security:
- basicAuth: []
tags:
- name: Search Queries
  description: Endpoints for executing full-text search queries against search indexes.
paths:
  /api/index/{indexName}/query:
    post:
      operationId: querySearchIndex
      summary: Query a search index
      description: Executes a full-text search query against the specified index. Supports various query types including match, term, phrase, boolean, numeric range, date range, geospatial, and conjunction/disjunction queries. Results include relevance scores, highlighting, and faceted results.
      tags:
      - Search Queries
      parameters:
      - $ref: '#/components/parameters/indexName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchQueryRequest'
      responses:
        '200':
          description: Search query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchQueryResult'
        '400':
          description: Invalid search query
        '401':
          description: Unauthorized access
        '404':
          description: Index not found
components:
  parameters:
    indexName:
      name: indexName
      in: path
      required: true
      description: The name of the Full Text Search index
      schema:
        type: string
  schemas:
    SearchQueryResult:
      type: object
      description: Full-text search query result
      properties:
        status:
          type: object
          description: Query execution status
          properties:
            total:
              type: integer
              description: Total number of search partitions queried
            failed:
              type: integer
              description: Number of partitions that failed
            successful:
              type: integer
              description: Number of partitions that succeeded
            errors:
              type: object
              description: Error messages from failed partitions
        total_hits:
          type: integer
          description: Total number of matching documents
        max_score:
          type: number
          description: Maximum relevance score
        took:
          type: integer
          description: Time taken in nanoseconds
        hits:
          type: array
          description: Array of matching documents
          items:
            type: object
            properties:
              index:
                type: string
                description: Index partition that matched
              id:
                type: string
                description: Document ID
              score:
                type: number
                description: Relevance score
              fields:
                type: object
                description: Requested field values
              fragments:
                type: object
                description: Highlighted fragments
                additionalProperties:
                  type: array
                  items:
                    type: string
              sort:
                type: array
                description: Sort values
                items: {}
        facets:
          type: object
          description: Faceted results
          additionalProperties:
            type: object
            properties:
              field:
                type: string
                description: Facet field name
              total:
                type: integer
                description: Total count
              missing:
                type: integer
                description: Count of documents without this field
              other:
                type: integer
                description: Count not represented in terms
              terms:
                type: array
                description: Facet term values
                items:
                  type: object
                  properties:
                    term:
                      type: string
                      description: Facet value
                    count:
                      type: integer
                      description: Number of documents with this value
    SearchQueryRequest:
      type: object
      description: Full-text search query request
      required:
      - query
      properties:
        query:
          type: object
          description: The search query object. Supports match, term, phrase, boolean, numeric_range, date_range, geo_distance, geo_bounding_box, conjunction, and disjunction query types.
          properties:
            match:
              type: string
              description: Text to match against the index
            field:
              type: string
              description: Specific field to search
            analyzer:
              type: string
              description: Analyzer to use for the query
            fuzziness:
              type: integer
              description: Fuzziness level for approximate matching
              minimum: 0
              maximum: 2
            prefix_length:
              type: integer
              description: Minimum prefix length for fuzzy matches
            boost:
              type: number
              description: Boost factor for relevance scoring
        size:
          type: integer
          description: Maximum number of results to return
          default: 10
        from:
          type: integer
          description: Offset for paginating results
          default: 0
        fields:
          type: array
          description: Fields to include in the response
          items:
            type: string
        highlight:
          type: object
          description: Highlight configuration for matched terms
          properties:
            style:
              type: string
              description: Highlight style
              enum:
              - html
              - ansi
            fields:
              type: array
              description: Fields to highlight
              items:
                type: string
        facets:
          type: object
          description: Facet definitions for aggregating results
          additionalProperties:
            type: object
            properties:
              field:
                type: string
                description: Field to facet on
              size:
                type: integer
                description: Maximum number of facet values
        sort:
          type: array
          description: Sort order for results
          items:
            oneOf:
            - type: string
            - type: object
        explain:
          type: boolean
          description: Whether to include scoring explanation
        ctl:
          type: object
          description: Query control parameters
          properties:
            timeout:
              type: integer
              description: Query timeout in milliseconds
            consistency:
              type: object
              description: Consistency requirements
              properties:
                level:
                  type: string
                  description: Consistency level
                  enum:
                  - at_plus
                  - not_bounded
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Couchbase Server credentials.
externalDocs:
  description: Couchbase Search Service REST API Documentation
  url: https://docs.couchbase.com/server/current/rest-api/rest-fts.html