From 71d04d6301eb5c38d7e99a070d2b85edbe59a1d9 Mon Sep 17 00:00:00 2001
From: Marci W <333176+marciw@users.noreply.github.com>
Date: Fri, 24 Jan 2025 16:12:00 -0500
Subject: [PATCH] Clarify query options

---
 output/openapi/elasticsearch-openapi.json            | 10 +++++-----
 output/openapi/elasticsearch-serverless-openapi.json | 10 +++++-----
 output/schema/schema.json                            |  8 ++++----
 specification/_global/count/CountRequest.ts          | 10 +++++-----
 4 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index ef3e197338..57664456d8 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -6474,7 +6474,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count-1",
         "parameters": [
           {
@@ -6534,7 +6534,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count",
         "parameters": [
           {
@@ -6596,7 +6596,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count-3",
         "parameters": [
           {
@@ -6659,7 +6659,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count-2",
         "parameters": [
           {
@@ -99904,7 +99904,7 @@
       "count#q": {
         "in": "query",
         "name": "q",
-        "description": "The query in Lucene query string syntax.",
+        "description": "The query in Lucene query string syntax. This parameter cannot be used with a request body.",
         "deprecated": false,
         "schema": {
           "type": "string"
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index e2bd454200..8a22a943ff 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -3208,7 +3208,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count-1",
         "parameters": [
           {
@@ -3268,7 +3268,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count",
         "parameters": [
           {
@@ -3330,7 +3330,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count-3",
         "parameters": [
           {
@@ -3393,7 +3393,7 @@
           "search"
         ],
         "summary": "Count search results",
-        "description": "Get the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+        "description": "Get the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
         "operationId": "count-2",
         "parameters": [
           {
@@ -59302,7 +59302,7 @@
       "count#q": {
         "in": "query",
         "name": "q",
-        "description": "The query in Lucene query string syntax.",
+        "description": "The query in Lucene query string syntax. This parameter cannot be used with a request body.",
         "deprecated": false,
         "schema": {
           "type": "string"
diff --git a/output/schema/schema.json b/output/schema/schema.json
index 86c0be906e..93c62c9e50 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -4154,7 +4154,7 @@
           "stability": "stable"
         }
       },
-      "description": "Count search results.\nGet the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+      "description": "Count search results.\nGet the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
       "docId": "search-count",
       "docTag": "search",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-count.html",
@@ -23291,7 +23291,7 @@
         "kind": "properties",
         "properties": [
           {
-            "description": "Defines the search definition using the Query DSL.\nThe query is optional, and when not provided, it will use `match_all` to count all the docs.",
+            "description": "Defines the search query using Query DSL. A request body query cannot be used\nwith the `q` query string parameter.",
             "name": "query",
             "required": false,
             "type": {
@@ -23304,7 +23304,7 @@
           }
         ]
       },
-      "description": "Count search results.\nGet the number of documents matching a query.\n\nThe query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.\nThe latter must be nested in a `query` key, which is the same as the search API.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
+      "description": "Count search results.\nGet the number of documents matching a query.\n\nThe query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.\nThe query is optional. When no query is provided, the API uses `match_all` to count all the documents.\n\nThe count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.\n\nThe operation is broadcast across all shards.\nFor each shard ID group, a replica is chosen and the search is run against it.\nThis means that replicas increase the scalability of the count.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -23498,7 +23498,7 @@
           }
         },
         {
-          "description": "The query in Lucene query string syntax.",
+          "description": "The query in Lucene query string syntax. This parameter cannot be used with a request body.",
           "name": "q",
           "required": false,
           "type": {
diff --git a/specification/_global/count/CountRequest.ts b/specification/_global/count/CountRequest.ts
index 2921adbfcc..af4202f271 100644
--- a/specification/_global/count/CountRequest.ts
+++ b/specification/_global/count/CountRequest.ts
@@ -27,8 +27,8 @@ import { Operator } from '@_types/query_dsl/Operator'
  * Count search results.
  * Get the number of documents matching a query.
  *
- * The query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body.
- * The latter must be nested in a `query` key, which is the same as the search API.
+ * The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.
+ * The query is optional. When no query is provided, the API uses `match_all` to count all the documents.
  *
  * The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.
  *
@@ -140,14 +140,14 @@ export interface Request extends RequestBase {
      */
     terminate_after?: long
     /**
-     * The query in Lucene query string syntax.
+     * The query in Lucene query string syntax. This parameter cannot be used with a request body.
      */
     q?: string
   }
   body: {
     /**
-     * Defines the search definition using the Query DSL.
-     * The query is optional, and when not provided, it will use `match_all` to count all the docs.
+     * Defines the search query using Query DSL. A request body query cannot be used
+     * with the `q` query string parameter.
      */
     query?: QueryContainer
   }