Asynchronous search namespace (#525)

.github/workflows/test-spec.yml

@@ -37,7 +37,7 @@ jobs:
             ref: '@sha256:ed4274522a50228f41b50f1a7ea86e6b52fa6737072fc151b2624d22aff80d56'
           - version: 3.0.0
             hub: opensearchstaging
-            ref: '@sha256:cab6f71b284485c44306f8f4849ad520283c2a32ece617109b38183ba29cc401'
+            ref: '@sha256:9f4eba4fe7e75368d70f0a7f09d737bff4742d2139087fa637a689bb9fcd9788'
 
     name: test-opensearch-spec (version=${{ matrix.entry.version }}, hub=${{ matrix.entry.hub || 'opensearchproject' }}, tests=${{ matrix.entry.tests || 'default' }})
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -79,6 +79,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `cancelled_task_percentage` and `current_cancellation_eligible_tasks_count` to `ShardSearchBackpressureTaskCancellationStats` ([#483](https://github.com/opensearch-project/opensearch-api-specification/pull/483))
 - Added detailed test coverage report ([#513](https://github.com/opensearch-project/opensearch-api-specification/pull/513))
 - Added 404 responses to `/_alias/{name}` and `/{index}/_alias/{name}` ([#519](https://github.com/opensearch-project/opensearch-api-specification/pull/519))
+- Added `asynchronous_search` ([#525](https://github.com/opensearch-project/opensearch-api-specification/pull/525))
 
 ### Changed
 

spec/namespaces/asynchronous_search.yaml

@@ -0,0 +1,127 @@
+openapi: 3.1.0
+info:
+  title: OpenSearch Asynchronous Search API
+  description: OpenSearch Asynchronous Search API.
+  version: 1.0.0
+paths:
+  /_plugins/_asynchronous_search:
+    post:
+      operationId: asynchronous_search.search.0
+      x-operation-group: asynchronous_search.search
+      x-version-added: '1.0'
+      description: Perform an asynchronous search.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/async/index/#rest-api
+      parameters:
+        - $ref: '#/components/parameters/asynchronous_search.search::query.index'
+        - $ref: '#/components/parameters/asynchronous_search.search::query.keep_alive'
+        - $ref: '#/components/parameters/asynchronous_search.search::query.keep_on_completion'
+        - $ref: '#/components/parameters/asynchronous_search.search::query.wait_for_completion_timeout'
+      requestBody:
+        $ref: '#/components/requestBodies/asynchronous_search.search'
+      responses:
+        '200':
+          $ref: '#/components/responses/asynchronous_search.search@200'
+  /_plugins/_asynchronous_search/{id}:
+    get:
+      operationId: asynchronous_search.get.0
+      x-operation-group: asynchronous_search.get
+      x-version-added: '1.0'
+      description: Get partial responses from asynchronous search.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/async/index/#get-partial-results
+      parameters:
+        - $ref: '#/components/parameters/asynchronous_search.get::path.id'
+      responses:
+        '200':
+          $ref: '#/components/responses/asynchronous_search.get@200'
+    delete:
+      operationId: asynchronous_search.delete.0
+      x-operation-group: asynchronous_search.delete
+      x-version-added: '1.0'
+      description: Delete asynchronous search.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/async/index/#delete-searches-and-results
+      parameters:
+        - $ref: '#/components/parameters/asynchronous_search.delete::path.id'
+      responses:
+        '200':
+          $ref: '#/components/responses/asynchronous_search.delete@200'
+  /_plugins/_asynchronous_search/stats:
+    get:
+      operationId: asynchronous_search.stats.0
+      x-operation-group: asynchronous_search.stats
+      x-version-added: '1.0'
+      description: Monitoring of asynchronous searches that are running, completed, and/or persisted.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/search-plugins/async/index/#monitor-stats
+      responses:
+        '200':
+          $ref: '#/components/responses/asynchronous_search.stats@200'
+
+components:
+  parameters:
+    asynchronous_search.search::query.wait_for_completion_timeout:
+      name: wait_for_completion_timeout
+      in: query
+      description: The amount of time that you plan to wait for the results.
+      schema:
+        type: string
+    asynchronous_search.search::query.keep_on_completion:
+      name: keep_on_completion
+      in: query
+      description: Whether you want to save the results in the cluster after the search is complete.
+      schema:
+        type: boolean
+    asynchronous_search.search::query.keep_alive:
+      name: keep_alive
+      in: query
+      description: The amount of time that the result is saved in the cluster.
+      schema:
+        type: string
+    asynchronous_search.search::query.index:
+      name: index
+      in: query
+      description: The name of the index to be searched.
+      schema:
+        type: string
+    asynchronous_search.get::path.id:
+      name: id
+      in: path
+      schema:
+        type: string
+    asynchronous_search.delete::path.id:
+      name: id
+      in: path
+      schema:
+        type: string
+  requestBodies:
+    asynchronous_search.search:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/asynchronous_search._common.yaml#/components/schemas/Search'
+  responses:
+    asynchronous_search.search@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/asynchronous_search._common.yaml#/components/schemas/ResponseBody'
+    asynchronous_search.get@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/asynchronous_search._common.yaml#/components/schemas/ResponseBody'
+    asynchronous_search.delete@200:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              acknowledged:
+                type: boolean
+    asynchronous_search.stats@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/asynchronous_search._common.yaml#/components/schemas/StatsResponse'

spec/schemas/asynchronous_search._common.yaml

@@ -0,0 +1,188 @@
+openapi: 3.1.0
+info:
+  title: Schemas of asynchronous_search._common category
+  description: Schemas of asynchronous_search._common category
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    ResponseBody:
+      type: object
+      properties:
+        id:
+          type: string
+        state:
+          type: string
+        start_time_in_millis: 
+          type: number
+        expiration_time_in_millis:
+          type: number
+        took: 
+          type: number
+        response:
+          $ref: '_core.search.yaml#/components/schemas/ResponseBody'
+    StatsResponse:
+      type: object
+      properties:
+        _nodes:
+          $ref: '_common.yaml#/components/schemas/NodeStatistics'
+        cluster_name:
+          type: string
+        nodes:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/NodesStats'
+    NodesStats:
+      type: object
+      properties:
+        asynchronous_search_stats:
+          $ref: '#/components/schemas/AsynchronousSearchStats'
+    Search:
+      type: object
+      properties:
+        aggregations:
+          description: Defines the aggregations that are run as part of the search request.
+          type: object
+          additionalProperties:
+            $ref: '_common.aggregations.yaml#/components/schemas/AggregationContainer'
+        collapse:
+          $ref: '_core.search.yaml#/components/schemas/FieldCollapse'
+        explain:
+          description: If true, returns detailed information about score computation as part of a hit.
+          type: boolean
+        ext:
+          description: Configuration of search extensions defined by OpenSearch plugins.
+          type: object
+          additionalProperties:
+            type: object
+        from:
+          description: |-
+            Starting document offset.
+            Needs to be non-negative.
+            By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
+            To page through more hits, use the `search_after` parameter.
+          type: number
+        highlight:
+          $ref: '_core.search.yaml#/components/schemas/Highlight'
+        track_total_hits:
+          $ref: '_core.search.yaml#/components/schemas/TrackHits'
+        indices_boost:
+          description: Boosts the _score of documents from specified indices.
+          type: array
+          items:
+            type: object
+            additionalProperties:
+              type: number
+        docvalue_fields:
+          description: |-
+            Array of wildcard (`*`) patterns.
+            The request returns doc values for field names matching these patterns in the `hits.fields` property of the response.
+          type: array
+          items:
+            $ref: '_common.query_dsl.yaml#/components/schemas/FieldAndFormat'
+        rank:
+          $ref: '_common.yaml#/components/schemas/RankContainer'
+        min_score:
+          description: |-
+            Minimum `_score` for matching documents.
+            Documents with a lower `_score` are not included in the search results.
+          type: number
+        post_filter:
+          $ref: '_common.query_dsl.yaml#/components/schemas/QueryContainer'
+        profile:
+          description: |-
+            Set to `true` to return detailed timing information about the execution of individual components in a search request.
+            NOTE: This is a debugging tool and adds significant overhead to search execution.
+          type: boolean
+        query:
+          $ref: '_common.query_dsl.yaml#/components/schemas/QueryContainer'
+        script_fields:
+          description: Retrieve a script evaluation (based on different fields) for each hit.
+          type: object
+          additionalProperties:
+            $ref: '_common.yaml#/components/schemas/ScriptField'
+        search_after:
+          $ref: '_common.yaml#/components/schemas/SortResults'
+        size:
+          description: |-
+            The number of hits to return.
+            By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
+            To page through more hits, use the `search_after` parameter.
+          type: number
+        slice:
+          $ref: '_common.yaml#/components/schemas/SlicedScroll'
+        sort:
+          $ref: '_common.yaml#/components/schemas/Sort'
+        _source:
+          $ref: '_core.search.yaml#/components/schemas/SourceConfig'
+        fields:
+          description: |-
+            Array of wildcard (`*`) patterns.
+            The request returns values for field names matching these patterns in the `hits.fields` property of the response.
+          type: array
+          items:
+            $ref: '_common.query_dsl.yaml#/components/schemas/FieldAndFormat'
+        suggest:
+          $ref: '_core.search.yaml#/components/schemas/Suggester'
+        terminate_after:
+          description: |-
+            Maximum number of documents to collect for each shard.
+            If a query reaches this limit, OpenSearch terminates the query early.
+            OpenSearch collects documents before sorting.
+            Use with caution.
+            OpenSearch applies this parameter to each shard handling the request.
+            When possible, let OpenSearch perform early termination automatically.
+            Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
+            If set to `0` (default), the query does not terminate early.
+          type: number
+        timeout:
+          description: |-
+            Specifies the period of time to wait for a response from each shard.
+            If no response is received before the timeout expires, the request fails and returns an error.
+            Defaults to no timeout.
+          type: string
+        track_scores:
+          description: If true, calculate and return document scores, even if the scores are not used for sorting.
+          type: boolean
+        version:
+          description: If true, returns document version as part of a hit.
+          type: boolean
+        seq_no_primary_term:
+          description: If `true`, returns sequence number and primary term of the last modification of each hit.
+          type: boolean
+        stored_fields:
+          $ref: '_common.yaml#/components/schemas/Fields'
+        pit:
+          $ref: '_core.search.yaml#/components/schemas/PointInTimeReference'
+        runtime_mappings:
+          $ref: '_common.mapping.yaml#/components/schemas/RuntimeFields'
+        stats:
+          description: |-
+            Stats groups to associate with the search.
+            Each group maintains a statistics aggregation for its associated searches.
+            You can retrieve these stats using the indices stats API.
+          type: array
+          items:
+            type: string
+      description: The search definition using the Query DSL.
+    AsynchronousSearchStats:
+      type: object
+      properties:
+        submitted:
+          type: integer
+        initialized:
+          type: integer
+        search_failed:
+          type: integer
+        search_completed:
+          type: integer
+        rejected:
+          type: integer
+        persist_failed:
+          type: integer
+        cancelled:
+          type: integer
+        running_current:
+          type: integer
+        persisted:
+          type: integer