From e776574d2f67a21a1b17ca162cde43737a9e21db Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 14 Jan 2025 00:21:05 -0800 Subject: [PATCH] Add clear scroll, close point in time, and count examples --- output/openapi/elasticsearch-openapi.json | 52 +++++++----- .../elasticsearch-serverless-openapi.json | 52 +++++++----- output/schema/schema.json | 79 ++++++++++++------- .../clear_scroll/ClearScrollRequest.ts | 8 +- .../clear_scroll/ClearScrollResponse.ts | 7 ++ .../request/ClearScrollRequestExample1.yaml | 8 ++ .../ClosePointInTimeRequest.ts | 1 - .../ClosePointInTimeResponse.ts | 6 ++ .../ClosePointInTimeResponseExample1.yaml | 9 +++ .../ClosePointInTimeRequestExample1.yaml | 8 ++ specification/_global/count/CountRequest.ts | 55 +++++++++---- .../200_response/CountResponseExample1.yaml | 14 ++++ .../request/CountRequestExample1.yaml | 13 +++ 13 files changed, 220 insertions(+), 92 deletions(-) create mode 100644 specification/_global/clear_scroll/examples/request/ClearScrollRequestExample1.yaml create mode 100644 specification/_global/close_point_in_time/examples/200_response/ClosePointInTimeResponseExample1.yaml create mode 100644 specification/_global/close_point_in_time/examples/request/ClosePointInTimeRequestExample1.yaml create mode 100644 specification/_global/count/examples/200_response/CountResponseExample1.yaml create mode 100644 specification/_global/count/examples/request/CountRequestExample1.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 5c66d87036..453cadb413 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -3370,6 +3370,9 @@ ], "summary": "Clear a scrolling search", "description": "Clear the search context and results for a scrolling search.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results" + }, "operationId": "clear-scroll", "requestBody": { "$ref": "#/components/requestBodies/clear_scroll" @@ -3454,6 +3457,9 @@ ], "summary": "Clear a scrolling search", "description": "Clear the search context and results for a scrolling search.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results" + }, "operationId": "clear-scroll-1", "parameters": [ { @@ -3504,9 +3510,11 @@ "type": "object", "properties": { "succeeded": { + "description": "If `true`, all search contexts associated with the point-in-time ID were successfully closed.", "type": "boolean" }, "num_freed": { + "description": "The number of search contexts that were successfully closed.", "type": "number" } }, @@ -6430,7 +6438,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count-1", "parameters": [ { @@ -6490,7 +6498,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count", "parameters": [ { @@ -6552,7 +6560,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count-3", "parameters": [ { @@ -6615,7 +6623,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count-2", "parameters": [ { @@ -93719,9 +93727,11 @@ "type": "object", "properties": { "succeeded": { + "description": "If `true`, the request succeeded.\nThis does not indicate whether any scrolling search requests were cleared.", "type": "boolean" }, "num_freed": { + "description": "The number of scrolling search requests cleared.", "type": "number" } }, @@ -98578,9 +98588,9 @@ "clear_scroll#scroll_id": { "in": "path", "name": "scroll_id", - "description": "Comma-separated list of scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.", + "description": "A comma-separated list of scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.\nIMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter.", "required": true, - "deprecated": false, + "deprecated": true, "schema": { "$ref": "#/components/schemas/_types:ScrollIds" }, @@ -98973,7 +98983,7 @@ "count#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases to search.\nSupports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*` or `_all`.", + "description": "A comma-separated list of data streams, indices, and aliases to search.\nIt supports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*` or `_all`.", "required": true, "deprecated": false, "schema": { @@ -98984,7 +98994,7 @@ "count#allow_no_indices": { "in": "query", "name": "allow_no_indices", - "description": "If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.\nThis behavior applies even if the request targets other open indices.", + "description": "If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.\nThis behavior applies even if the request targets other open indices.\nFor example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.", "deprecated": false, "schema": { "type": "boolean" @@ -98994,7 +99004,7 @@ "count#analyzer": { "in": "query", "name": "analyzer", - "description": "Analyzer to use for the query string.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The analyzer to use for the query string.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "string" @@ -99004,7 +99014,7 @@ "count#analyze_wildcard": { "in": "query", "name": "analyze_wildcard", - "description": "If `true`, wildcard and prefix queries are analyzed.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "If `true`, wildcard and prefix queries are analyzed.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "boolean" @@ -99014,7 +99024,7 @@ "count#default_operator": { "in": "query", "name": "default_operator", - "description": "The default operator for query string query: `AND` or `OR`.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The default operator for query string query: `AND` or `OR`.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types.query_dsl:Operator" @@ -99024,7 +99034,7 @@ "count#df": { "in": "query", "name": "df", - "description": "Field to use as default where no field prefix is given in the query string.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The field to use as a default when no field prefix is given in the query string.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "string" @@ -99034,7 +99044,7 @@ "count#expand_wildcards": { "in": "query", "name": "expand_wildcards", - "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.", + "description": "The type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nIt supports comma-separated values, such as `open,hidden`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:ExpandWildcards" @@ -99044,8 +99054,8 @@ "count#ignore_throttled": { "in": "query", "name": "ignore_throttled", - "description": "If `true`, concrete, expanded or aliased indices are ignored when frozen.", - "deprecated": false, + "description": "If `true`, concrete, expanded, or aliased indices are ignored when frozen.", + "deprecated": true, "schema": { "type": "boolean" }, @@ -99064,7 +99074,7 @@ "count#lenient": { "in": "query", "name": "lenient", - "description": "If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.", + "description": "If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "boolean" @@ -99074,7 +99084,7 @@ "count#min_score": { "in": "query", "name": "min_score", - "description": "Sets the minimum `_score` value that documents must have to be included in the result.", + "description": "The minimum `_score` value that documents must have to be included in the result.", "deprecated": false, "schema": { "type": "number" @@ -99084,7 +99094,7 @@ "count#preference": { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, it is random.", "deprecated": false, "schema": { "type": "string" @@ -99094,7 +99104,7 @@ "count#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -99104,7 +99114,7 @@ "count#terminate_after": { "in": "query", "name": "terminate_after", - "description": "Maximum number of documents to collect for each shard.\nIf a query reaches this limit, Elasticsearch terminates the query early.\nElasticsearch collects documents before sorting.", + "description": "The maximum number of documents to collect for each shard.\nIf a query reaches this limit, Elasticsearch terminates the query early.\nElasticsearch collects documents before sorting.\n\nIMPORTANT: Use with caution.\nElasticsearch applies this parameter to each shard handling the request.\nWhen possible, let Elasticsearch perform early termination automatically.\nAvoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.", "deprecated": false, "schema": { "type": "number" @@ -99114,7 +99124,7 @@ "count#q": { "in": "query", "name": "q", - "description": "Query in the Lucene query string syntax.", + "description": "The query in Lucene query string syntax.", "deprecated": false, "schema": { "type": "string" diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index ebd82fbff5..f2becfe1f1 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -1326,6 +1326,9 @@ ], "summary": "Clear a scrolling search", "description": "Clear the search context and results for a scrolling search.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results" + }, "operationId": "clear-scroll", "requestBody": { "$ref": "#/components/requestBodies/clear_scroll" @@ -1410,6 +1413,9 @@ ], "summary": "Clear a scrolling search", "description": "Clear the search context and results for a scrolling search.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#scroll-search-results" + }, "operationId": "clear-scroll-1", "parameters": [ { @@ -1460,9 +1466,11 @@ "type": "object", "properties": { "succeeded": { + "description": "If `true`, all search contexts associated with the point-in-time ID were successfully closed.", "type": "boolean" }, "num_freed": { + "description": "The number of search contexts that were successfully closed.", "type": "number" } }, @@ -3164,7 +3172,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count-1", "parameters": [ { @@ -3224,7 +3232,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count", "parameters": [ { @@ -3286,7 +3294,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count-3", "parameters": [ { @@ -3349,7 +3357,7 @@ "search" ], "summary": "Count search results", - "description": "Get the number of documents matching a query.", + "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.", "operationId": "count-2", "parameters": [ { @@ -56141,9 +56149,11 @@ "type": "object", "properties": { "succeeded": { + "description": "If `true`, the request succeeded.\nThis does not indicate whether any scrolling search requests were cleared.", "type": "boolean" }, "num_freed": { + "description": "The number of scrolling search requests cleared.", "type": "number" } }, @@ -58794,9 +58804,9 @@ "clear_scroll#scroll_id": { "in": "path", "name": "scroll_id", - "description": "Comma-separated list of scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.", + "description": "A comma-separated list of scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.\nIMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter.", "required": true, - "deprecated": false, + "deprecated": true, "schema": { "$ref": "#/components/schemas/_types:ScrollIds" }, @@ -58898,7 +58908,7 @@ "count#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases to search.\nSupports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*` or `_all`.", + "description": "A comma-separated list of data streams, indices, and aliases to search.\nIt supports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*` or `_all`.", "required": true, "deprecated": false, "schema": { @@ -58909,7 +58919,7 @@ "count#allow_no_indices": { "in": "query", "name": "allow_no_indices", - "description": "If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.\nThis behavior applies even if the request targets other open indices.", + "description": "If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.\nThis behavior applies even if the request targets other open indices.\nFor example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.", "deprecated": false, "schema": { "type": "boolean" @@ -58919,7 +58929,7 @@ "count#analyzer": { "in": "query", "name": "analyzer", - "description": "Analyzer to use for the query string.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The analyzer to use for the query string.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "string" @@ -58929,7 +58939,7 @@ "count#analyze_wildcard": { "in": "query", "name": "analyze_wildcard", - "description": "If `true`, wildcard and prefix queries are analyzed.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "If `true`, wildcard and prefix queries are analyzed.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "boolean" @@ -58939,7 +58949,7 @@ "count#default_operator": { "in": "query", "name": "default_operator", - "description": "The default operator for query string query: `AND` or `OR`.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The default operator for query string query: `AND` or `OR`.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types.query_dsl:Operator" @@ -58949,7 +58959,7 @@ "count#df": { "in": "query", "name": "df", - "description": "Field to use as default where no field prefix is given in the query string.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The field to use as a default when no field prefix is given in the query string.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "string" @@ -58959,7 +58969,7 @@ "count#expand_wildcards": { "in": "query", "name": "expand_wildcards", - "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.", + "description": "The type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nIt supports comma-separated values, such as `open,hidden`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:ExpandWildcards" @@ -58969,8 +58979,8 @@ "count#ignore_throttled": { "in": "query", "name": "ignore_throttled", - "description": "If `true`, concrete, expanded or aliased indices are ignored when frozen.", - "deprecated": false, + "description": "If `true`, concrete, expanded, or aliased indices are ignored when frozen.", + "deprecated": true, "schema": { "type": "boolean" }, @@ -58989,7 +58999,7 @@ "count#lenient": { "in": "query", "name": "lenient", - "description": "If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.", + "description": "If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.\nThis parameter can be used only when the `q` query string parameter is specified.", "deprecated": false, "schema": { "type": "boolean" @@ -58999,7 +59009,7 @@ "count#min_score": { "in": "query", "name": "min_score", - "description": "Sets the minimum `_score` value that documents must have to be included in the result.", + "description": "The minimum `_score` value that documents must have to be included in the result.", "deprecated": false, "schema": { "type": "number" @@ -59009,7 +59019,7 @@ "count#preference": { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, it is random.", "deprecated": false, "schema": { "type": "string" @@ -59019,7 +59029,7 @@ "count#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -59029,7 +59039,7 @@ "count#terminate_after": { "in": "query", "name": "terminate_after", - "description": "Maximum number of documents to collect for each shard.\nIf a query reaches this limit, Elasticsearch terminates the query early.\nElasticsearch collects documents before sorting.", + "description": "The maximum number of documents to collect for each shard.\nIf a query reaches this limit, Elasticsearch terminates the query early.\nElasticsearch collects documents before sorting.\n\nIMPORTANT: Use with caution.\nElasticsearch applies this parameter to each shard handling the request.\nWhen possible, let Elasticsearch perform early termination automatically.\nAvoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.", "deprecated": false, "schema": { "type": "number" @@ -59039,7 +59049,7 @@ "count#q": { "in": "query", "name": "q", - "description": "Query in the Lucene query string syntax.", + "description": "The query in Lucene query string syntax.", "deprecated": false, "schema": { "type": "string" diff --git a/output/schema/schema.json b/output/schema/schema.json index bc3fbe6688..112c3aacfd 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2175,10 +2175,12 @@ "stability": "stable" } }, - "description": "Clear a scrolling search.\n\nClear the search context and results for a scrolling search.", + "description": "Clear a scrolling search.\nClear the search context and results for a scrolling search.", "docId": "clear-scroll-api", "docTag": "search", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html", + "extDocId": "scroll-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", "name": "clear_scroll", "request": { "name": "Request", @@ -2226,7 +2228,7 @@ "stability": "stable" } }, - "description": "Close a point in time.\n\nA point in time must be opened explicitly before being used in search requests.\nThe `keep_alive` parameter tells Elasticsearch how long it should persist.\nA point in time is automatically closed when the `keep_alive` period has elapsed.\nHowever, keeping points in time has a cost; close them as soon as they are no longer required for search requests.", + "description": "Close a point in time.\nA point in time must be opened explicitly before being used in search requests.\nThe `keep_alive` parameter tells Elasticsearch how long it should persist.\nA point in time is automatically closed when the `keep_alive` period has elapsed.\nHowever, keeping points in time has a cost; close them as soon as they are no longer required for search requests.", "docId": "point-in-time-api", "docTag": "search", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/point-in-time-api.html", @@ -4151,10 +4153,16 @@ "stability": "stable" } }, - "description": "Count search results.\nGet the number of documents matching a query.", + "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.", + "docId": "search-count", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-count.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-count.html", "name": "count", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "_global.count" @@ -22776,7 +22784,7 @@ "kind": "properties", "properties": [ { - "description": "Scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.", + "description": "The scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.", "name": "scroll_id", "required": false, "type": { @@ -22789,7 +22797,7 @@ } ] }, - "description": "Clear a scrolling search.\n\nClear the search context and results for a scrolling search.", + "description": "Clear a scrolling search.\nClear the search context and results for a scrolling search.", "inherits": { "type": { "name": "RequestBase", @@ -22802,7 +22810,11 @@ }, "path": [ { - "description": "Comma-separated list of scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.", + "deprecation": { + "description": "", + "version": "7.0.0" + }, + "description": "A comma-separated list of scroll IDs to clear.\nTo clear all scroll IDs, use `_all`.\nIMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter.", "name": "scroll_id", "required": false, "type": { @@ -22815,7 +22827,7 @@ } ], "query": [], - "specLocation": "_global/clear_scroll/ClearScrollRequest.ts#L23-L59" + "specLocation": "_global/clear_scroll/ClearScrollRequest.ts#L23-L61" }, { "kind": "response", @@ -22823,6 +22835,7 @@ "kind": "properties", "properties": [ { + "description": "If `true`, the request succeeded.\nThis does not indicate whether any scrolling search requests were cleared.", "name": "succeeded", "required": true, "type": { @@ -22834,6 +22847,7 @@ } }, { + "description": "The number of scrolling search requests cleared.", "name": "num_freed", "required": true, "type": { @@ -22884,7 +22898,7 @@ "name": "Response", "namespace": "_global.clear_scroll" }, - "specLocation": "_global/clear_scroll/ClearScrollResponse.ts#L22-L36" + "specLocation": "_global/clear_scroll/ClearScrollResponse.ts#L22-L43" }, { "kind": "request", @@ -22908,7 +22922,7 @@ } ] }, - "description": "Close a point in time.\n\nA point in time must be opened explicitly before being used in search requests.\nThe `keep_alive` parameter tells Elasticsearch how long it should persist.\nA point in time is automatically closed when the `keep_alive` period has elapsed.\nHowever, keeping points in time has a cost; close them as soon as they are no longer required for search requests.", + "description": "Close a point in time.\nA point in time must be opened explicitly before being used in search requests.\nThe `keep_alive` parameter tells Elasticsearch how long it should persist.\nA point in time is automatically closed when the `keep_alive` period has elapsed.\nHowever, keeping points in time has a cost; close them as soon as they are no longer required for search requests.", "inherits": { "type": { "name": "RequestBase", @@ -22921,7 +22935,7 @@ }, "path": [], "query": [], - "specLocation": "_global/close_point_in_time/ClosePointInTimeRequest.ts#L23-L49" + "specLocation": "_global/close_point_in_time/ClosePointInTimeRequest.ts#L23-L48" }, { "kind": "response", @@ -22929,6 +22943,7 @@ "kind": "properties", "properties": [ { + "description": "If `true`, all search contexts associated with the point-in-time ID were successfully closed.", "name": "succeeded", "required": true, "type": { @@ -22940,6 +22955,7 @@ } }, { + "description": "The number of search contexts that were successfully closed.", "name": "num_freed", "required": true, "type": { @@ -22990,7 +23006,7 @@ "name": "Response", "namespace": "_global.close_point_in_time" }, - "specLocation": "_global/close_point_in_time/ClosePointInTimeResponse.ts#L22-L36" + "specLocation": "_global/close_point_in_time/ClosePointInTimeResponse.ts#L22-L42" }, { "kind": "request", @@ -23001,7 +23017,7 @@ "kind": "properties", "properties": [ { - "description": "Defines the search definition using the Query DSL.", + "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.", "name": "query", "required": false, "type": { @@ -23014,7 +23030,7 @@ } ] }, - "description": "Count search results.\nGet the number of documents matching a query.", + "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.", "inherits": { "type": { "name": "RequestBase", @@ -23027,7 +23043,7 @@ }, "path": [ { - "description": "Comma-separated list of data streams, indices, and aliases to search.\nSupports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*` or `_all`.", + "description": "A comma-separated list of data streams, indices, and aliases to search.\nIt supports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*` or `_all`.", "name": "index", "required": false, "type": { @@ -23041,7 +23057,7 @@ ], "query": [ { - "description": "If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.\nThis behavior applies even if the request targets other open indices.", + "description": "If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.\nThis behavior applies even if the request targets other open indices.\nFor example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.", "name": "allow_no_indices", "required": false, "serverDefault": true, @@ -23054,7 +23070,7 @@ } }, { - "description": "Analyzer to use for the query string.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The analyzer to use for the query string.\nThis parameter can be used only when the `q` query string parameter is specified.", "name": "analyzer", "required": false, "type": { @@ -23066,7 +23082,7 @@ } }, { - "description": "If `true`, wildcard and prefix queries are analyzed.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "If `true`, wildcard and prefix queries are analyzed.\nThis parameter can be used only when the `q` query string parameter is specified.", "name": "analyze_wildcard", "required": false, "serverDefault": false, @@ -23079,9 +23095,10 @@ } }, { - "description": "The default operator for query string query: `AND` or `OR`.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The default operator for query string query: `AND` or `OR`.\nThis parameter can be used only when the `q` query string parameter is specified.", "name": "default_operator", "required": false, + "serverDefault": "OR", "type": { "kind": "instance_of", "type": { @@ -23091,7 +23108,7 @@ } }, { - "description": "Field to use as default where no field prefix is given in the query string.\nThis parameter can only be used when the `q` query string parameter is specified.", + "description": "The field to use as a default when no field prefix is given in the query string.\nThis parameter can be used only when the `q` query string parameter is specified.", "name": "df", "required": false, "type": { @@ -23103,7 +23120,7 @@ } }, { - "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.", + "description": "The type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nIt supports comma-separated values, such as `open,hidden`.", "name": "expand_wildcards", "required": false, "serverDefault": "open", @@ -23116,7 +23133,11 @@ } }, { - "description": "If `true`, concrete, expanded or aliased indices are ignored when frozen.", + "deprecation": { + "description": "", + "version": "7.16.0" + }, + "description": "If `true`, concrete, expanded, or aliased indices are ignored when frozen.", "name": "ignore_throttled", "required": false, "serverDefault": true, @@ -23142,7 +23163,7 @@ } }, { - "description": "If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.", + "description": "If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.\nThis parameter can be used only when the `q` query string parameter is specified.", "name": "lenient", "required": false, "serverDefault": false, @@ -23155,7 +23176,7 @@ } }, { - "description": "Sets the minimum `_score` value that documents must have to be included in the result.", + "description": "The minimum `_score` value that documents must have to be included in the result.", "name": "min_score", "required": false, "type": { @@ -23167,7 +23188,7 @@ } }, { - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, it is random.", "name": "preference", "required": false, "type": { @@ -23179,7 +23200,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -23191,7 +23212,7 @@ } }, { - "description": "Maximum number of documents to collect for each shard.\nIf a query reaches this limit, Elasticsearch terminates the query early.\nElasticsearch collects documents before sorting.", + "description": "The maximum number of documents to collect for each shard.\nIf a query reaches this limit, Elasticsearch terminates the query early.\nElasticsearch collects documents before sorting.\n\nIMPORTANT: Use with caution.\nElasticsearch applies this parameter to each shard handling the request.\nWhen possible, let Elasticsearch perform early termination automatically.\nAvoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.", "name": "terminate_after", "required": false, "type": { @@ -23203,7 +23224,7 @@ } }, { - "description": "Query in the Lucene query string syntax.", + "description": "The query in Lucene query string syntax.", "name": "q", "required": false, "type": { @@ -23215,7 +23236,7 @@ } } ], - "specLocation": "_global/count/CountRequest.ts#L26-L133" + "specLocation": "_global/count/CountRequest.ts#L26-L154" }, { "kind": "response", diff --git a/specification/_global/clear_scroll/ClearScrollRequest.ts b/specification/_global/clear_scroll/ClearScrollRequest.ts index 291b5d3941..ff2e53cdfd 100644 --- a/specification/_global/clear_scroll/ClearScrollRequest.ts +++ b/specification/_global/clear_scroll/ClearScrollRequest.ts @@ -22,13 +22,13 @@ import { ScrollIds } from '@_types/common' /** * Clear a scrolling search. - * * Clear the search context and results for a scrolling search. * @rest_spec_name clear_scroll * @availability stack stability=stable * @availability serverless stability=stable visibility=public * @doc_id clear-scroll-api * @doc_tag search + * @ext_doc_id scroll-search-results */ export interface Request extends RequestBase { urls: [ @@ -44,14 +44,16 @@ export interface Request extends RequestBase { ] path_parts: { /** - * Comma-separated list of scroll IDs to clear. + * A comma-separated list of scroll IDs to clear. * To clear all scroll IDs, use `_all`. + * IMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter. + * @deprecated 7.0.0 */ scroll_id?: ScrollIds } body: { /** - * Scroll IDs to clear. + * The scroll IDs to clear. * To clear all scroll IDs, use `_all`. */ scroll_id?: ScrollIds diff --git a/specification/_global/clear_scroll/ClearScrollResponse.ts b/specification/_global/clear_scroll/ClearScrollResponse.ts index 77bbe83daf..51355a00e1 100644 --- a/specification/_global/clear_scroll/ClearScrollResponse.ts +++ b/specification/_global/clear_scroll/ClearScrollResponse.ts @@ -21,7 +21,14 @@ import { integer } from '@_types/Numeric' export class Response { body: { + /** + * If `true`, the request succeeded. + * This does not indicate whether any scrolling search requests were cleared. + */ succeeded: boolean + /** + * The number of scrolling search requests cleared. + */ num_freed: integer } exceptions: [ diff --git a/specification/_global/clear_scroll/examples/request/ClearScrollRequestExample1.yaml b/specification/_global/clear_scroll/examples/request/ClearScrollRequestExample1.yaml new file mode 100644 index 0000000000..cf38b01512 --- /dev/null +++ b/specification/_global/clear_scroll/examples/request/ClearScrollRequestExample1.yaml @@ -0,0 +1,8 @@ +# summary: +# method_request: DELETE /_search/scroll +description: Run `DELETE /_search/scroll` to clear the search context and results for a scrolling search. +# type: request +value: |- + { + "scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==" + } diff --git a/specification/_global/close_point_in_time/ClosePointInTimeRequest.ts b/specification/_global/close_point_in_time/ClosePointInTimeRequest.ts index 0156c29866..922650cead 100644 --- a/specification/_global/close_point_in_time/ClosePointInTimeRequest.ts +++ b/specification/_global/close_point_in_time/ClosePointInTimeRequest.ts @@ -22,7 +22,6 @@ import { Id } from '@_types/common' /** * Close a point in time. - * * A point in time must be opened explicitly before being used in search requests. * The `keep_alive` parameter tells Elasticsearch how long it should persist. * A point in time is automatically closed when the `keep_alive` period has elapsed. diff --git a/specification/_global/close_point_in_time/ClosePointInTimeResponse.ts b/specification/_global/close_point_in_time/ClosePointInTimeResponse.ts index 77bbe83daf..0ec2fc39fa 100644 --- a/specification/_global/close_point_in_time/ClosePointInTimeResponse.ts +++ b/specification/_global/close_point_in_time/ClosePointInTimeResponse.ts @@ -21,7 +21,13 @@ import { integer } from '@_types/Numeric' export class Response { body: { + /** + * If `true`, all search contexts associated with the point-in-time ID were successfully closed. + */ succeeded: boolean + /** + * The number of search contexts that were successfully closed. + */ num_freed: integer } exceptions: [ diff --git a/specification/_global/close_point_in_time/examples/200_response/ClosePointInTimeResponseExample1.yaml b/specification/_global/close_point_in_time/examples/200_response/ClosePointInTimeResponseExample1.yaml new file mode 100644 index 0000000000..934f1fe814 --- /dev/null +++ b/specification/_global/close_point_in_time/examples/200_response/ClosePointInTimeResponseExample1.yaml @@ -0,0 +1,9 @@ +# summary: +description: A successful response from `DELETE /_pit`. +# type: response +# response_code: 200 +value: |- + { + "succeeded": true, + "num_freed": 3 + } diff --git a/specification/_global/close_point_in_time/examples/request/ClosePointInTimeRequestExample1.yaml b/specification/_global/close_point_in_time/examples/request/ClosePointInTimeRequestExample1.yaml new file mode 100644 index 0000000000..8173163203 --- /dev/null +++ b/specification/_global/close_point_in_time/examples/request/ClosePointInTimeRequestExample1.yaml @@ -0,0 +1,8 @@ +# summary: +# method_request: DELETE /_pit +description: Run `DELETE /_pit` to close a point-in-time. +# type: request +value: |- + { + "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==" + } diff --git a/specification/_global/count/CountRequest.ts b/specification/_global/count/CountRequest.ts index 6eb7370ff8..2921adbfcc 100644 --- a/specification/_global/count/CountRequest.ts +++ b/specification/_global/count/CountRequest.ts @@ -26,10 +26,21 @@ 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 count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices. + * + * The operation is broadcast across all shards. + * For each shard ID group, a replica is chosen and the search is run against it. + * This means that replicas increase the scalability of the count. * @rest_spec_name count * @availability stack stability=stable * @availability serverless stability=stable visibility=public * @doc_tag search + * @doc_id search-count + * @index_privileges read */ export interface Request extends RequestBase { urls: [ @@ -44,8 +55,8 @@ export interface Request extends RequestBase { ] path_parts: { /** - * Comma-separated list of data streams, indices, and aliases to search. - * Supports wildcards (`*`). + * A comma-separated list of data streams, indices, and aliases to search. + * It supports wildcards (`*`). * To search all data streams and indices, omit this parameter or use `*` or `_all`. */ index?: Indices @@ -54,40 +65,43 @@ export interface Request extends RequestBase { /** * If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. * This behavior applies even if the request targets other open indices. + * For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. * @server_default true */ allow_no_indices?: boolean /** - * Analyzer to use for the query string. - * This parameter can only be used when the `q` query string parameter is specified. + * The analyzer to use for the query string. + * This parameter can be used only when the `q` query string parameter is specified. */ analyzer?: string /** * If `true`, wildcard and prefix queries are analyzed. - * This parameter can only be used when the `q` query string parameter is specified. + * This parameter can be used only when the `q` query string parameter is specified. * @server_default false */ analyze_wildcard?: boolean /** * The default operator for query string query: `AND` or `OR`. - * This parameter can only be used when the `q` query string parameter is specified. + * This parameter can be used only when the `q` query string parameter is specified. + * @server_default OR */ default_operator?: Operator /** - * Field to use as default where no field prefix is given in the query string. - * This parameter can only be used when the `q` query string parameter is specified. + * The field to use as a default when no field prefix is given in the query string. + * This parameter can be used only when the `q` query string parameter is specified. */ df?: string /** - * Type of index that wildcard patterns can match. + * The type of index that wildcard patterns can match. * If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. - * Supports comma-separated values, such as `open,hidden`. + * It supports comma-separated values, such as `open,hidden`. * @server_default open */ expand_wildcards?: ExpandWildcards /** - * If `true`, concrete, expanded or aliased indices are ignored when frozen. + * If `true`, concrete, expanded, or aliased indices are ignored when frozen. * @server_default true + * @deprecated 7.16.0 */ ignore_throttled?: boolean /** @@ -97,36 +111,43 @@ export interface Request extends RequestBase { ignore_unavailable?: boolean /** * If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. + * This parameter can be used only when the `q` query string parameter is specified. * @server_default false */ lenient?: boolean /** - * Sets the minimum `_score` value that documents must have to be included in the result. + * The minimum `_score` value that documents must have to be included in the result. */ min_score?: double /** - * Specifies the node or shard the operation should be performed on. - * Random by default. + * The node or shard the operation should be performed on. + * By default, it is random. */ preference?: string /** - * Custom value used to route operations to a specific shard. + * A custom value used to route operations to a specific shard. */ routing?: Routing /** - * Maximum number of documents to collect for each shard. + * The maximum number of documents to collect for each shard. * If a query reaches this limit, Elasticsearch terminates the query early. * Elasticsearch collects documents before sorting. + * + * IMPORTANT: Use with caution. + * Elasticsearch applies this parameter to each shard handling the request. + * When possible, let Elasticsearch perform early termination automatically. + * Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. */ terminate_after?: long /** - * Query in the Lucene query string syntax. + * The query in Lucene query string syntax. */ 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. */ query?: QueryContainer } diff --git a/specification/_global/count/examples/200_response/CountResponseExample1.yaml b/specification/_global/count/examples/200_response/CountResponseExample1.yaml new file mode 100644 index 0000000000..05f9999dbf --- /dev/null +++ b/specification/_global/count/examples/200_response/CountResponseExample1.yaml @@ -0,0 +1,14 @@ +# summary: +description: A successful response from `GET /my-index-000001/_count?q=user:kimchy`. +# type: response +# response_code: 200 +value: |- + { + "count": 1, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + } + } diff --git a/specification/_global/count/examples/request/CountRequestExample1.yaml b/specification/_global/count/examples/request/CountRequestExample1.yaml new file mode 100644 index 0000000000..2c84775812 --- /dev/null +++ b/specification/_global/count/examples/request/CountRequestExample1.yaml @@ -0,0 +1,13 @@ +# summary: +# method_request: GET /my-index-000001/_count +description: > + Run `GET /my-index-000001/_count?q=user:kimchy`. + Alternatively, run `GET /my-index-000001/_count` with the same query in the request body. + Both requests count the number of documents in `my-index-000001` with a `user.id` of `kimchy`. +# type: request +value: |- + { + "query" : { + "term" : { "user.id" : "kimchy" } + } + }