add adjust_pure_negative api spec

Signed-off-by: Chenyang Ji <[email protected]>

CHANGELOG.md

@@ -104,7 +104,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `config_id` and `config_id_list` to `/_plugins/_notifications/configs` query parameters ([#594](https://github.com/opensearch-project/opensearch-api-specification/pull/594))
 - Added a release workflow triggered on a tag ([#635](https://github.com/opensearch-project/opensearch-api-specification/pull/635))
 - Added API spec for query insights plugin ([#625](https://github.com/opensearch-project/opensearch-api-specification/pull/625))
-
+- Added API spec for `adjust_pure_negative` for bool queries ([#641](https://github.com/opensearch-project/opensearch-api-specification/pull/641))
+- 
 ### Changed
 
 - Replaced Smithy with a native OpenAPI spec ([#189](https://github.com/opensearch-project/opensearch-api-specification/issues/189))

spec/schemas/_common.query_dsl.yaml

@@ -270,6 +270,13 @@ components:
                 - type: array
                   items:
                     $ref: '#/components/schemas/QueryContainer'
+            adjust_pure_negative:
+              description: |-
+                Ensures correct behavior when a query contains only must_not clauses.
+                By default set to true, OpenSearch adds a match-all clause to ensure results are returned from Lucene, with the must_not conditions applied as filters.
+                If set to false, the query may return no results, as Lucene typically requires at least one positive condition.
+              type: boolean
+              default: true
     QueryBase:
       type: object
       properties:

spec/schemas/insights._common.yaml

@@ -137,8 +137,7 @@ components:
             NOTE: This is a debugging tool and adds significant overhead to search execution.
           type: boolean
         query:
-          description: The query definition using the Query DSL.
-          type: object
+          $ref: '_common.query_dsl.yaml#/components/schemas/QueryContainer'
         script_fields:
           description: Retrieve a script evaluation (based on different fields) for each hit.
           type: object
@@ -206,7 +205,6 @@ components:
           type: array
           items:
             type: string
-      additionalProperties: true
     Measurement:
       type: object
       properties:

tests/plugins/query_insights/insights/top_queries.yaml

@@ -41,6 +41,19 @@ prologues:
             terms:
               field: director.raw
 
+  - path: /{index}/_search
+    parameters:
+      index: movies
+    method: GET
+    request:
+      payload:
+        query:
+          bool:
+            adjust_pure_negative: true
+            must:
+              match:
+                title: Drive
+
 chapters:
   - synopsis: Retrieve default top queries.
     path: /_insights/top_queries