openapi: 3.0.3
info:
  title: Couchbase Search Advanced API
  description: |-
    The Advanced Search REST APIs are provided by the Search service.
    These APIs enable you to manage and query Search index partitions and to specify advanced settings.
  version: '7.6'
servers:
  - url: '{scheme}://{host}:{port}'
    description: The URL scheme, host, and port are as follows.
    variables:
      scheme:
        default: http
        description: |-
          The URL scheme.
          Use `https` for secure access.
        enum:
          - http
          - https
      host:
        default: localhost
        description: The host name or IP address of a node running the Search Service.
      port:
        default: '8094'
        description: |-
          The Search Service REST port.
          Use `18094` for secure access.
        enum:
          - '8094'
          - '18094'
tags:
  - name: Definition
    x-displayName: Index Partition Definition
    description: Operations for Search index partition definition.
  - name: Query
    x-displayName: Index Partition Querying
    description: Operations for querying Search index partitions.
  - name: Quota
    x-displayName: Search Memory Quota
    description: Operations for managing Search memory quota.
paths:
  /api/pindex:
    get:
      operationId: getPartition
      summary: Get Index Partition Information
      description: Get information about a Search index partition.
      tags:
        - Definition
      responses:
        '200':
          description: A JSON object containing the Search index partition information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/indexPartition'
              example:
                pindexes:
                  myFirstIndex_6cc599ab7a85bf3b_0:
                    indexName: myFirstIndex
                    indexParams: ''
                    indexType: blackhole
                    indexUUID: 6cc599ab7a85bf3b
                    name: myFirstIndex_6cc599ab7a85bf3b_0
                    sourceName: ''
                    sourceParams: ''
                    sourcePartitions: ''
                    sourceType: nil
                    sourceUUID: ''
                    uuid: 2d9ecb8b574a9f6a
                status: ok
      security:
        - Read: []
  /api/pindex/{pindexName}:
    get:
      operationId: getPartitionName
      summary: Get Index Partition by Name
      description: Get information about a specific Search index partition by name.
      tags:
        - Definition
      parameters:
        - name: pindexName
          in: path
          required: true
          schema:
            type: string
          description: The name of the Search index partition.
      responses:
        '200':
          description: Success
      security:
        - Read: []
  /api/pindex/{pindexName}/count:
    get:
      operationId: getPartitionCount
      summary: Get Index Partition Document Count
      description: Get the document count of a specific Search index partition.
      tags:
        - Query
      parameters:
        - name: pindexName
          in: path
          required: true
          schema:
            type: string
          description: The name of the Search index partition.
      responses:
        '200':
          description: The Search Service returns a response that includes the status `ok`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentCount'
      security:
        - Read: []
  /api/pindex/{pindexName}/query:
    post:
      operationId: queryPartition
      summary: Query Index Partition
      description: Execute a query against a specific Search index partition by name.
      tags:
        - Query
      parameters:
        - name: pindexName
          in: path
          required: true
          schema:
            type: string
          description: The name of the Search index partition.
      requestBody:
        required: true
        description: |-
          A JSON object to define the settings for your Search query.
          For more information about how to create a Search query JSON object, see [Search Request JSON Properties](../search/search-request-params.html).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: |-
            The response object has a status section that must be checked for every request.
            Under nearly all circumstances, the query response will be HTTP 200 even though individual index shards (partitions) may encounter a timeout or return an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
      security:
        - Write: []
  /pools/default:
    post:
      operationId: setFtsMemoryQuota
      summary: Set Search Memory Quota
      description: Sets the memory quota for the Search Service.
      tags:
        - Quota
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                ftsMemoryQuota:
                  type: integer
                  description: The memory quota for the Search service.
                  example: 512
                  x-has-example: true
      responses:
        '200':
          description: Memory quota set.
      security:
        - Manage: []
components:
  schemas:
    indexPartition:
      type: object
      title: Index Partitions
      properties:
        pindexes:
          $ref: '#/components/schemas/indexPartitionPIndex'
        status:
          description: The status of the request.
          type: string
    indexPartitionPIndex:
      type: object
      title: Index Partitions Wrapper
      description: An object containing information about 1 or more Search index partitions.
      additionalProperties:
        x-additionalPropertiesName: Partition Name
        $ref: '#/components/schemas/indexPartitionPIndexInner'
    indexPartitionPIndexInner:
      type: object
      title: Index Partition
      description: |-
        An object containing information about a single Search index partition.
        The name of the property is the name of the Search index partition.
      properties:
        indexName:
          $ref: '#/components/schemas/CommonIndexName'
        indexParams:
          $ref: '#/components/schemas/CommonIndexParams'
        indexType:
          $ref: '#/components/schemas/CommonIndexType'
        indexUUID:
          $ref: '#/components/schemas/CommonIndexUUID'
        name:
          $ref: '#/components/schemas/CommonPIndexName'
        sourceName:
          $ref: '#/components/schemas/CommonSourceName'
        sourceParams:
          $ref: '#/components/schemas/CommonSourceParams'
        sourcePartitions:
          type: string
        sourceType:
          $ref: '#/components/schemas/CommonSourceType'
        sourceUUID:
          $ref: '#/components/schemas/CommonSourceUUID'
        uuid:
          $ref: '#/components/schemas/CommonPIndexUUID'
    CommonIndexName:
      type: string
      title: Index Name
      description: |-
        The name of the Search index.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonIndexParams:
      type: object
      title: Index Parameters
      description: |-
        The Search index's type identifier, type mappings, and analyzers.
        For more information, see [Params Object](../search/search-index-params.html#params).
    CommonIndexType:
      type: string
      title: Index Type
      description: |-
        The type of the Search index.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonIndexUUID:
      type: string
      title: Index UUID
      description: |-
        The UUID of the Search index.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonPIndexName:
      type: string
      title: Partition Name
      description: The name of the Search index partition.
    CommonSourceName:
      type: string
      title: Source Name
      description: |-
        The name of the bucket where the Search index is stored.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonSourceParams:
      type: object
      title: Source Parameters
      description: |-
        Advanced settings for Search index behavior.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonSourceType:
      type: string
      title: Source Type
      description: |-
        The type of the bucket where the Search index is stored.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonSourceUUID:
      type: string
      title: Source UUID
      description: |-
        The UUID of the bucket where the Search index is stored.
        For more information, see [Initial Settings](../search/search-index-params.html#initial).
    CommonPIndexUUID:
      type: string
      title: Partition UUID
      description: The UUID of the Search index partition.
    CommonStatus:
      type: string
      title: Status
      description: The status of the operation.
    DocumentCount:
      type: object
      title: Document Count
      properties:
        status:
          $ref: '#/components/schemas/CommonStatus'
        count:
          type: integer
          description: The document count for the specified index.
    QueryRequest:
      type: object
      title: Query Request
      properties:
        query:
          type: object
          description: |-
            An object that contains the properties for one of the supported query types.
            For more information, see [Query Object](../search/search-request-params.html#query-object).
        knn:
          type: array
          description: |-
            An array that contains objects that describe a Vector Search query.
            For more information, see [Knn Objects](../search/search-request-params.html#knn-object).
          items:
            type: object
        ctl:
          type: object
          description: |-
            An object that contains properties for query consistency.
            For more information, see [Ctl Object](../search/search-request-params.html#ctl).
        size:
          type: integer
          description: Set the total number of results to return for a single page of search results.
        from:
          type: integer
          description: Set an offset value to change where pagination starts for search results.
        highlight:
          type: object
          description: |-
            Contains properties to control search result highlighting.
            For more information, see [Highlight Objects](../search/search-request-params.html#highlight).
        fields:
          type: array
          description: An array of strings to specify each indexed field you want to return in search results.
          items:
            type: string
        facets:
          type: object
          description: |-
            Contains nested objects to define each facet you want to return with search results.
            For more information, see [Facet Objects](../search/search-request-params.html#facet-name).
        explain:
          type: boolean
          description: Whether to create an explanation for a search result's score in search results.
        sort:
          type: array
          description: |-
            Contains an array of strings or JSON objects to set how to sort search results.
            For more information, see [Sort Object](../search/search-request-params.html#sort).
          items: {}
        includeLocations:
          type: boolean
          description: Whether to return the position of each occurrence of a search term inside a document.
        score:
          type: string
          description: Whether to include document relevancy scoring in search results.
        search_after:
          type: array
          description: Use to control pagination in search results.
          items:
            type: string
        search_before:
          type: array
          description: Use to control pagination in search results.
          items:
            type: string
        collections:
          type: array
          description: An array of strings that specify the collections where you want to run the query.
          items:
            type: string
    QueryResponse:
      type: object
      title: Query Response
      properties:
        status:
          $ref: '#/components/schemas/CommonStatus'
        results:
          type: array
          description: The results of the Search query.
          items:
            type: object
  securitySchemes:
    Manage:
      type: http
      scheme: basic
      description: You must have the **Search Admin** role, with FTS Manage permissions on the required bucket.
    Read:
      type: http
      scheme: basic
      description: You must have the **Search Reader** or **Search Admin** role, with FTS Read permissions on the required bucket.
    Write:
      type: http
      scheme: basic
      description: You must have the **Search Admin** role, with FTS Write permissions on the required bucket.
