diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 372004d304..fb600584bf 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -25801,7 +25801,7 @@ "search" ], "summary": "Open a point in time", - "description": "A search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent 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.", + "description": "A search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent point in time.\n\nA point in time must be opened explicitly before being used in search requests.\n\nA subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time.\n\nJust like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits.\nIf you want to retrieve more hits, use PIT with `search_after`.\n\nIMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.\n\nWhen a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception.\nTo get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.\n\n**Keeping point in time alive**\n\nThe `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.\nThe value does not need to be long enough to process all data — it just needs to be long enough for the next request.\n\nNormally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments.\nOnce the smaller segments are no longer needed they are deleted.\nHowever, open point-in-times prevent the old segments from being deleted since they are still in use.\n\nTIP: Keeping older segments alive means that more disk space and file handles are needed.\nEnsure that you have configured your nodes to have ample free file handles.\n\nAdditionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request.\nEnsure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.\nNote that a point-in-time doesn't prevent its associated indices from being deleted.\nYou can check how many point-in-times (that is, search contexts) are open with the nodes stats API.", "operationId": "open-point-in-time", "parameters": [ { @@ -25818,7 +25818,7 @@ { "in": "query", "name": "keep_alive", - "description": "Extends the time to live of the corresponding point in time.", + "description": "Extend the length of time that the point in time persists.", "required": true, "deprecated": false, "schema": { @@ -25839,7 +25839,7 @@ { "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" @@ -25849,7 +25849,7 @@ { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -25859,7 +25859,7 @@ { "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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.", + "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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:ExpandWildcards" @@ -25869,7 +25869,7 @@ { "in": "query", "name": "allow_partial_search_results", - "description": "If `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.\nIf `true`, the point in time will contain all the shards that are available at the time of the request.", + "description": "Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT.\nIf `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.\nIf `true`, the point in time will contain all the shards that are available at the time of the request.", "deprecated": false, "schema": { "type": "boolean" @@ -27380,7 +27380,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search", "parameters": [ { @@ -27533,7 +27536,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search-1", "parameters": [ { @@ -27688,7 +27694,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search-2", "parameters": [ { @@ -27844,7 +27853,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search-3", "parameters": [ { @@ -46803,7 +46815,7 @@ "$ref": "#/components/schemas/_types:Field" }, "format": { - "description": "Format in which the values are returned.", + "description": "The format in which the values are returned.", "type": "string" }, "include_unmapped": { @@ -69477,9 +69489,11 @@ "type": "object", "properties": { "took": { + "description": "The number of milliseconds it took Elasticsearch to run the request.\nThis value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response.\nIt includes:\n\n* Communication time between the coordinating node and data nodes\n* Time the request spends in the search thread pool, queued for execution\n* Actual run time\n\nIt does not include:\n\n* Time needed to send the request to Elasticsearch\n* Time needed to serialize the JSON response\n* Time needed to send the response to a client", "type": "number" }, "timed_out": { + "description": "If `true`, the request timed out before completion; returned results may be partial or empty.", "type": "boolean" }, "_shards": { @@ -105222,7 +105236,7 @@ "search#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": { @@ -105243,7 +105257,7 @@ "search#allow_partial_search_results": { "in": "query", "name": "allow_partial_search_results", - "description": "If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results.", + "description": "If `true` and there are shard request timeouts or shard failures, the request returns partial results.\nIf `false`, it returns an error with no partial results.\n\nTo override the default behavior, you can set the `search.default_allow_partial_results` cluster setting to `false`.", "deprecated": false, "schema": { "type": "boolean" @@ -105253,7 +105267,7 @@ "search#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" @@ -105263,7 +105277,7 @@ "search#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" @@ -105273,7 +105287,7 @@ "search#batched_reduce_size": { "in": "query", "name": "batched_reduce_size", - "description": "The number of shard results that should be reduced at once on the coordinating node.\nThis value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "description": "The number of shard results that should be reduced at once on the coordinating node.\nIf the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.", "deprecated": false, "schema": { "type": "number" @@ -105283,7 +105297,7 @@ "search#ccs_minimize_roundtrips": { "in": "query", "name": "ccs_minimize_roundtrips", - "description": "If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests.", + "description": "If `true`, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.", "deprecated": false, "schema": { "type": "boolean" @@ -105293,7 +105307,7 @@ "search#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 the 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" @@ -105303,7 +105317,7 @@ "search#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" @@ -105313,7 +105327,7 @@ "search#docvalue_fields": { "in": "query", "name": "docvalue_fields", - "description": "A comma-separated list of fields to return as the docvalue representation for each hit.", + "description": "A comma-separated list of fields to return as the docvalue representation of a field for each hit.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -105323,7 +105337,7 @@ "search#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" @@ -105333,7 +105347,7 @@ "search#explain": { "in": "query", "name": "explain", - "description": "If `true`, returns detailed information about score computation as part of a hit.", + "description": "If `true`, the request returns detailed information about score computation as part of a hit.", "deprecated": false, "schema": { "type": "boolean" @@ -105344,7 +105358,7 @@ "in": "query", "name": "ignore_throttled", "description": "If `true`, concrete, expanded or aliased indices will be ignored when frozen.", - "deprecated": false, + "deprecated": true, "schema": { "type": "boolean" }, @@ -105363,7 +105377,7 @@ "search#include_named_queries_score": { "in": "query", "name": "include_named_queries_score", - "description": "Indicates whether hit.matched_queries should be rendered as a map that includes\nthe name of the matched query associated with its score (true)\nor as an array containing the name of the matched queries (false)\nThis functionality reruns each named query on every hit in a search response.\nTypically, this adds a small overhead to a request.\nHowever, using computationally expensive named queries on a large number of hits may add significant overhead.", + "description": "If `true`, the response includes the score contribution from any named queries.\n\nThis functionality reruns each named query on every hit in a search response.\nTypically, this adds a small overhead to a request.\nHowever, using computationally expensive named queries on a large number of hits may add significant overhead.", "deprecated": false, "schema": { "type": "boolean" @@ -105373,7 +105387,7 @@ "search#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.\nThis parameter can only be used when the `q` query string parameter is specified.", + "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" @@ -105383,7 +105397,7 @@ "search#max_concurrent_shard_requests": { "in": "query", "name": "max_concurrent_shard_requests", - "description": "Defines the number of concurrent shard requests per node this search executes concurrently.\nThis value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "description": "The number of concurrent shard requests per node that the search runs concurrently.\nThis value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", "deprecated": false, "schema": { "type": "number" @@ -105403,7 +105417,7 @@ "search#preference": { "in": "query", "name": "preference", - "description": "Nodes and shards used for the search.\nBy default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:\n`_only_local` to run the search only on shards on the local node;\n`_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method;\n`_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;\n`_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;\n`_shards:,` to run the search only on the specified shards;\n`` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order.", + "description": "The nodes and shards used for the search.\nBy default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness.\nValid values are:\n\n* `_only_local` to run the search only on shards on the local node;\n* `_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method;\n* `_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;\n* `_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;\n* `_shards:,` to run the search only on the specified shards;\n* `` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order.", "deprecated": false, "schema": { "type": "string" @@ -105413,7 +105427,7 @@ "search#pre_filter_shard_size": { "in": "query", "name": "pre_filter_shard_size", - "description": "Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold.\nThis filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint).\nWhen unspecified, the pre-filter phase is executed if any of these conditions is met:\nthe request targets more than 128 shards;\nthe request targets one or more read-only index;\nthe primary sort of the query targets an indexed field.", + "description": "A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold.\nThis filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint).\nWhen unspecified, the pre-filter phase is executed if any of these conditions is met:\n\n* The request targets more than 128 shards.\n* The request targets one or more read-only index.\n* The primary sort of the query targets an indexed field.", "deprecated": false, "schema": { "type": "number" @@ -105423,7 +105437,7 @@ "search#request_cache": { "in": "query", "name": "request_cache", - "description": "If `true`, the caching of search results is enabled for requests where `size` is `0`.\nDefaults to index level settings.", + "description": "If `true`, the caching of search results is enabled for requests where `size` is `0`.\nIt defaults to index level settings.", "deprecated": false, "schema": { "type": "boolean" @@ -105433,7 +105447,7 @@ "search#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -105443,7 +105457,7 @@ "search#scroll": { "in": "query", "name": "scroll", - "description": "Period to retain the search context for scrolling. See Scroll search results.\nBy default, this value cannot exceed `1d` (24 hours).\nYou can change this limit using the `search.max_keep_alive` cluster-level setting.", + "description": "The period to retain the search context for scrolling.\nBy default, this value cannot exceed `1d` (24 hours).\nYou can change this limit by using the `search.max_keep_alive` cluster-level setting.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -105453,7 +105467,7 @@ "search#search_type": { "in": "query", "name": "search_type", - "description": "How distributed term frequencies are calculated for relevance scoring.", + "description": "Indicates how distributed term frequencies are calculated for relevance scoring.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:SearchType" @@ -105486,7 +105500,7 @@ "search#suggest_field": { "in": "query", "name": "suggest_field", - "description": "Specifies which field to use for suggestions.", + "description": "The field to use for suggestions.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Field" @@ -105496,7 +105510,7 @@ "search#suggest_mode": { "in": "query", "name": "suggest_mode", - "description": "Specifies the suggest mode.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The suggest mode.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:SuggestMode" @@ -105506,7 +105520,7 @@ "search#suggest_size": { "in": "query", "name": "suggest_size", - "description": "Number of suggestions to return.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The number of suggestions to return.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "deprecated": false, "schema": { "type": "number" @@ -105516,7 +105530,7 @@ "search#suggest_text": { "in": "query", "name": "suggest_text", - "description": "The source text for which the suggestions should be returned.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The source text for which the suggestions should be returned.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "deprecated": false, "schema": { "type": "string" @@ -105526,7 +105540,7 @@ "search#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.\nUse 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.\nIf set to `0` (default), the query does not terminate early.", + "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.\nIf set to `0` (default), the query does not terminate early.", "deprecated": false, "schema": { "type": "number" @@ -105536,7 +105550,7 @@ "search#timeout": { "in": "query", "name": "timeout", - "description": "Specifies the period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt defaults to no timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -105546,7 +105560,7 @@ "search#track_total_hits": { "in": "query", "name": "track_total_hits", - "description": "Number of hits matching the query to count accurately.\nIf `true`, the exact number of hits is returned at the cost of some performance.\nIf `false`, the response does not include the total number of hits matching the query.", + "description": "The number of hits matching the query to count accurately.\nIf `true`, the exact number of hits is returned at the cost of some performance.\nIf `false`, the response does not include the total number of hits matching the query.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:TrackHits" @@ -105556,7 +105570,7 @@ "search#track_scores": { "in": "query", "name": "track_scores", - "description": "If `true`, calculate and return document scores, even if the scores are not used for sorting.", + "description": "If `true`, the request calculates and returns document scores, even if the scores are not used for sorting.", "deprecated": false, "schema": { "type": "boolean" @@ -105586,7 +105600,7 @@ "search#version": { "in": "query", "name": "version", - "description": "If `true`, returns document version as part of a hit.", + "description": "If `true`, the request returns the document version as part of a hit.", "deprecated": false, "schema": { "type": "boolean" @@ -105596,7 +105610,7 @@ "search#_source": { "in": "query", "name": "_source", - "description": "Indicates which source fields are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nValid values are:\n`true` to return the entire document source;\n`false` to not return the document source;\n`` to return the source fields that are specified as a comma-separated list (supports wildcard (`*`) patterns).", + "description": "The source fields that are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nValid values are:\n\n* `true` to return the entire document source.\n* `false` to not return the document source.\n* `` to return the source fields that are specified as a comma-separated list that supports wildcard (`*`) patterns.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -105626,7 +105640,7 @@ "search#seq_no_primary_term": { "in": "query", "name": "seq_no_primary_term", - "description": "If `true`, returns sequence number and primary term of the last modification of each hit.", + "description": "If `true`, the request returns the sequence number and primary term of the last modification of each hit.", "deprecated": false, "schema": { "type": "boolean" @@ -105636,7 +105650,7 @@ "search#q": { "in": "query", "name": "q", - "description": "Query in the Lucene query string syntax using query parameter search.\nQuery parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.", + "description": "A query in the Lucene query string syntax.\nQuery parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.\n\nIMPORTANT: This parameter overrides the query parameter in the request body.\nIf both parameters are specified, documents matching the query request body parameter are not returned.", "deprecated": false, "schema": { "type": "string" @@ -105646,7 +105660,7 @@ "search#size": { "in": "query", "name": "size", - "description": "Defines the number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "deprecated": false, "schema": { "type": "number" @@ -105656,7 +105670,7 @@ "search#from": { "in": "query", "name": "from", - "description": "Starting document offset.\nNeeds to be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset, which must be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "deprecated": false, "schema": { "type": "number" @@ -105666,7 +105680,7 @@ "search#sort": { "in": "query", "name": "sort", - "description": "A comma-separated list of : pairs.", + "description": "A comma-separated list of `:` pairs.", "deprecated": false, "schema": { "oneOf": [ @@ -109282,7 +109296,7 @@ "$ref": "#/components/schemas/_global.search._types:FieldCollapse" }, "explain": { - "description": "If true, returns detailed information about score computation as part of a hit.", + "description": "If `true`, the request returns detailed information about score computation as part of a hit.", "type": "boolean" }, "ext": { @@ -109293,7 +109307,7 @@ } }, "from": { - "description": "Starting document offset.\nNeeds to be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset, which must be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "highlight": { @@ -109303,7 +109317,10 @@ "$ref": "#/components/schemas/_global.search._types:TrackHits" }, "indices_boost": { - "description": "Boosts the _score of documents from specified indices.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-filter-context.html#relevance-scores" + }, + "description": "Boost the `_score` of documents from specified indices.\nThe boost value is the factor by which scores are multiplied.\nA boost value greater than `1.0` increases the score.\nA boost value between `0` and `1.0` decreases the score.", "type": "array", "items": { "type": "object", @@ -109313,14 +109330,20 @@ } }, "docvalue_fields": { - "description": "Array of wildcard (`*`) patterns.\nThe request returns doc values for field names matching these patterns in the `hits.fields` property of the response.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-fields.html#docvalue-fields" + }, + "description": "An array of wildcard (`*`) field patterns.\nThe request returns doc values for field names matching these patterns in the `hits.fields` property of the response.", "type": "array", "items": { "$ref": "#/components/schemas/_types.query_dsl:FieldAndFormat" } }, "knn": { - "description": "Defines the approximate kNN search to run.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html#approximate-knn" + }, + "description": "The approximate kNN search to run.", "oneOf": [ { "$ref": "#/components/schemas/_types:KnnSearch" @@ -109337,7 +109360,7 @@ "$ref": "#/components/schemas/_types:RankContainer" }, "min_score": { - "description": "Minimum `_score` for matching documents.\nDocuments with a lower `_score` are not included in the search results.", + "description": "The minimum `_score` for matching documents.\nDocuments with a lower `_score` are not included in the search results.", "type": "number" }, "post_filter": { @@ -109378,7 +109401,7 @@ "$ref": "#/components/schemas/_types:SortResults" }, "size": { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return, which must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` property.", "type": "number" }, "slice": { @@ -109391,7 +109414,7 @@ "$ref": "#/components/schemas/_global.search._types:SourceConfig" }, "fields": { - "description": "Array of wildcard (`*`) patterns.\nThe request returns values for field names matching these patterns in the `hits.fields` property of the response.", + "description": "An array of wildcard (`*`) field patterns.\nThe request returns values for field names matching these patterns in the `hits.fields` property of the response.", "type": "array", "items": { "$ref": "#/components/schemas/_types.query_dsl:FieldAndFormat" @@ -109401,23 +109424,26 @@ "$ref": "#/components/schemas/_global.search._types:Suggester" }, "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.\nUse 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.\nIf set to `0` (default), the query does not terminate early.", + "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 property to each shard handling the request.\nWhen possible, let Elasticsearch perform early termination automatically.\nAvoid specifying this property for requests that target data streams with backing indices across multiple data tiers.\n\nIf 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.\nIf no response is received before the timeout expires, the request fails and returns an error.\nDefaults to no timeout.", + "description": "The period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nDefaults to no timeout.", "type": "string" }, "track_scores": { - "description": "If true, calculate and return document scores, even if the scores are not used for sorting.", + "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.", + "description": "If `true`, the request returns the 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.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html" + }, + "description": "If `true`, the request returns sequence number and primary term of the last modification of each hit.", "type": "boolean" }, "stored_fields": { @@ -109430,7 +109456,7 @@ "$ref": "#/components/schemas/_types.mapping:RuntimeFields" }, "stats": { - "description": "Stats groups to associate with the search.\nEach group maintains a statistics aggregation for its associated searches.\nYou can retrieve these stats using the indices stats API.", + "description": "The stats groups to associate with the search.\nEach group maintains a statistics aggregation for its associated searches.\nYou can retrieve these stats using the indices stats API.", "type": "array", "items": { "type": "string" diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 44b69a4c6d..078a11c34b 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -14874,7 +14874,7 @@ "search" ], "summary": "Open a point in time", - "description": "A search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent 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.", + "description": "A search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent point in time.\n\nA point in time must be opened explicitly before being used in search requests.\n\nA subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time.\n\nJust like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits.\nIf you want to retrieve more hits, use PIT with `search_after`.\n\nIMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.\n\nWhen a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception.\nTo get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.\n\n**Keeping point in time alive**\n\nThe `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.\nThe value does not need to be long enough to process all data — it just needs to be long enough for the next request.\n\nNormally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments.\nOnce the smaller segments are no longer needed they are deleted.\nHowever, open point-in-times prevent the old segments from being deleted since they are still in use.\n\nTIP: Keeping older segments alive means that more disk space and file handles are needed.\nEnsure that you have configured your nodes to have ample free file handles.\n\nAdditionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request.\nEnsure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.\nNote that a point-in-time doesn't prevent its associated indices from being deleted.\nYou can check how many point-in-times (that is, search contexts) are open with the nodes stats API.", "operationId": "open-point-in-time", "parameters": [ { @@ -14891,7 +14891,7 @@ { "in": "query", "name": "keep_alive", - "description": "Extends the time to live of the corresponding point in time.", + "description": "Extend the length of time that the point in time persists.", "required": true, "deprecated": false, "schema": { @@ -14912,7 +14912,7 @@ { "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" @@ -14922,7 +14922,7 @@ { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -14932,7 +14932,7 @@ { "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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.", + "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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:ExpandWildcards" @@ -14942,7 +14942,7 @@ { "in": "query", "name": "allow_partial_search_results", - "description": "If `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.\nIf `true`, the point in time will contain all the shards that are available at the time of the request.", + "description": "Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT.\nIf `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.\nIf `true`, the point in time will contain all the shards that are available at the time of the request.", "deprecated": false, "schema": { "type": "boolean" @@ -15974,7 +15974,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search", "parameters": [ { @@ -16124,7 +16127,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search-1", "parameters": [ { @@ -16276,7 +16282,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search-2", "parameters": [ { @@ -16429,7 +16438,10 @@ "search" ], "summary": "Run a search", - "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Get search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/remote-clusters-cert.html#remote-clusters-privileges-ccs" + }, "operationId": "search-3", "parameters": [ { @@ -27234,7 +27246,7 @@ "$ref": "#/components/schemas/_types:Field" }, "format": { - "description": "Format in which the values are returned.", + "description": "The format in which the values are returned.", "type": "string" }, "include_unmapped": { @@ -53461,9 +53473,11 @@ "type": "object", "properties": { "took": { + "description": "The number of milliseconds it took Elasticsearch to run the request.\nThis value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response.\nIt includes:\n\n* Communication time between the coordinating node and data nodes\n* Time the request spends in the search thread pool, queued for execution\n* Actual run time\n\nIt does not include:\n\n* Time needed to send the request to Elasticsearch\n* Time needed to serialize the JSON response\n* Time needed to send the response to a client", "type": "number" }, "timed_out": { + "description": "If `true`, the request timed out before completion; returned results may be partial or empty.", "type": "boolean" }, "_shards": { @@ -62053,7 +62067,7 @@ "search#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": { @@ -62074,7 +62088,7 @@ "search#allow_partial_search_results": { "in": "query", "name": "allow_partial_search_results", - "description": "If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results.", + "description": "If `true` and there are shard request timeouts or shard failures, the request returns partial results.\nIf `false`, it returns an error with no partial results.\n\nTo override the default behavior, you can set the `search.default_allow_partial_results` cluster setting to `false`.", "deprecated": false, "schema": { "type": "boolean" @@ -62084,7 +62098,7 @@ "search#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" @@ -62094,7 +62108,7 @@ "search#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" @@ -62104,7 +62118,7 @@ "search#batched_reduce_size": { "in": "query", "name": "batched_reduce_size", - "description": "The number of shard results that should be reduced at once on the coordinating node.\nThis value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "description": "The number of shard results that should be reduced at once on the coordinating node.\nIf the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.", "deprecated": false, "schema": { "type": "number" @@ -62114,7 +62128,7 @@ "search#ccs_minimize_roundtrips": { "in": "query", "name": "ccs_minimize_roundtrips", - "description": "If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests.", + "description": "If `true`, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.", "deprecated": false, "schema": { "type": "boolean" @@ -62124,7 +62138,7 @@ "search#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 the 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" @@ -62134,7 +62148,7 @@ "search#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" @@ -62144,7 +62158,7 @@ "search#docvalue_fields": { "in": "query", "name": "docvalue_fields", - "description": "A comma-separated list of fields to return as the docvalue representation for each hit.", + "description": "A comma-separated list of fields to return as the docvalue representation of a field for each hit.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -62154,7 +62168,7 @@ "search#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" @@ -62164,7 +62178,7 @@ "search#explain": { "in": "query", "name": "explain", - "description": "If `true`, returns detailed information about score computation as part of a hit.", + "description": "If `true`, the request returns detailed information about score computation as part of a hit.", "deprecated": false, "schema": { "type": "boolean" @@ -62175,7 +62189,7 @@ "in": "query", "name": "ignore_throttled", "description": "If `true`, concrete, expanded or aliased indices will be ignored when frozen.", - "deprecated": false, + "deprecated": true, "schema": { "type": "boolean" }, @@ -62194,7 +62208,7 @@ "search#include_named_queries_score": { "in": "query", "name": "include_named_queries_score", - "description": "Indicates whether hit.matched_queries should be rendered as a map that includes\nthe name of the matched query associated with its score (true)\nor as an array containing the name of the matched queries (false)\nThis functionality reruns each named query on every hit in a search response.\nTypically, this adds a small overhead to a request.\nHowever, using computationally expensive named queries on a large number of hits may add significant overhead.", + "description": "If `true`, the response includes the score contribution from any named queries.\n\nThis functionality reruns each named query on every hit in a search response.\nTypically, this adds a small overhead to a request.\nHowever, using computationally expensive named queries on a large number of hits may add significant overhead.", "deprecated": false, "schema": { "type": "boolean" @@ -62204,7 +62218,7 @@ "search#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.\nThis parameter can only be used when the `q` query string parameter is specified.", + "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" @@ -62214,7 +62228,7 @@ "search#max_concurrent_shard_requests": { "in": "query", "name": "max_concurrent_shard_requests", - "description": "Defines the number of concurrent shard requests per node this search executes concurrently.\nThis value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "description": "The number of concurrent shard requests per node that the search runs concurrently.\nThis value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", "deprecated": false, "schema": { "type": "number" @@ -62234,7 +62248,7 @@ "search#preference": { "in": "query", "name": "preference", - "description": "Nodes and shards used for the search.\nBy default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:\n`_only_local` to run the search only on shards on the local node;\n`_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method;\n`_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;\n`_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;\n`_shards:,` to run the search only on the specified shards;\n`` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order.", + "description": "The nodes and shards used for the search.\nBy default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness.\nValid values are:\n\n* `_only_local` to run the search only on shards on the local node;\n* `_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method;\n* `_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;\n* `_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;\n* `_shards:,` to run the search only on the specified shards;\n* `` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order.", "deprecated": false, "schema": { "type": "string" @@ -62244,7 +62258,7 @@ "search#pre_filter_shard_size": { "in": "query", "name": "pre_filter_shard_size", - "description": "Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold.\nThis filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint).\nWhen unspecified, the pre-filter phase is executed if any of these conditions is met:\nthe request targets more than 128 shards;\nthe request targets one or more read-only index;\nthe primary sort of the query targets an indexed field.", + "description": "A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold.\nThis filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint).\nWhen unspecified, the pre-filter phase is executed if any of these conditions is met:\n\n* The request targets more than 128 shards.\n* The request targets one or more read-only index.\n* The primary sort of the query targets an indexed field.", "deprecated": false, "schema": { "type": "number" @@ -62254,7 +62268,7 @@ "search#request_cache": { "in": "query", "name": "request_cache", - "description": "If `true`, the caching of search results is enabled for requests where `size` is `0`.\nDefaults to index level settings.", + "description": "If `true`, the caching of search results is enabled for requests where `size` is `0`.\nIt defaults to index level settings.", "deprecated": false, "schema": { "type": "boolean" @@ -62264,7 +62278,7 @@ "search#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -62274,7 +62288,7 @@ "search#scroll": { "in": "query", "name": "scroll", - "description": "Period to retain the search context for scrolling. See Scroll search results.\nBy default, this value cannot exceed `1d` (24 hours).\nYou can change this limit using the `search.max_keep_alive` cluster-level setting.", + "description": "The period to retain the search context for scrolling.\nBy default, this value cannot exceed `1d` (24 hours).\nYou can change this limit by using the `search.max_keep_alive` cluster-level setting.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -62284,7 +62298,7 @@ "search#search_type": { "in": "query", "name": "search_type", - "description": "How distributed term frequencies are calculated for relevance scoring.", + "description": "Indicates how distributed term frequencies are calculated for relevance scoring.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:SearchType" @@ -62317,7 +62331,7 @@ "search#suggest_field": { "in": "query", "name": "suggest_field", - "description": "Specifies which field to use for suggestions.", + "description": "The field to use for suggestions.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Field" @@ -62327,7 +62341,7 @@ "search#suggest_mode": { "in": "query", "name": "suggest_mode", - "description": "Specifies the suggest mode.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The suggest mode.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:SuggestMode" @@ -62337,7 +62351,7 @@ "search#suggest_size": { "in": "query", "name": "suggest_size", - "description": "Number of suggestions to return.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The number of suggestions to return.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "deprecated": false, "schema": { "type": "number" @@ -62347,7 +62361,7 @@ "search#suggest_text": { "in": "query", "name": "suggest_text", - "description": "The source text for which the suggestions should be returned.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The source text for which the suggestions should be returned.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "deprecated": false, "schema": { "type": "string" @@ -62357,7 +62371,7 @@ "search#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.\nUse 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.\nIf set to `0` (default), the query does not terminate early.", + "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.\nIf set to `0` (default), the query does not terminate early.", "deprecated": false, "schema": { "type": "number" @@ -62367,7 +62381,7 @@ "search#timeout": { "in": "query", "name": "timeout", - "description": "Specifies the period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt defaults to no timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -62377,7 +62391,7 @@ "search#track_total_hits": { "in": "query", "name": "track_total_hits", - "description": "Number of hits matching the query to count accurately.\nIf `true`, the exact number of hits is returned at the cost of some performance.\nIf `false`, the response does not include the total number of hits matching the query.", + "description": "The number of hits matching the query to count accurately.\nIf `true`, the exact number of hits is returned at the cost of some performance.\nIf `false`, the response does not include the total number of hits matching the query.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:TrackHits" @@ -62387,7 +62401,7 @@ "search#track_scores": { "in": "query", "name": "track_scores", - "description": "If `true`, calculate and return document scores, even if the scores are not used for sorting.", + "description": "If `true`, the request calculates and returns document scores, even if the scores are not used for sorting.", "deprecated": false, "schema": { "type": "boolean" @@ -62417,7 +62431,7 @@ "search#version": { "in": "query", "name": "version", - "description": "If `true`, returns document version as part of a hit.", + "description": "If `true`, the request returns the document version as part of a hit.", "deprecated": false, "schema": { "type": "boolean" @@ -62427,7 +62441,7 @@ "search#_source": { "in": "query", "name": "_source", - "description": "Indicates which source fields are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nValid values are:\n`true` to return the entire document source;\n`false` to not return the document source;\n`` to return the source fields that are specified as a comma-separated list (supports wildcard (`*`) patterns).", + "description": "The source fields that are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nValid values are:\n\n* `true` to return the entire document source.\n* `false` to not return the document source.\n* `` to return the source fields that are specified as a comma-separated list that supports wildcard (`*`) patterns.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -62457,7 +62471,7 @@ "search#seq_no_primary_term": { "in": "query", "name": "seq_no_primary_term", - "description": "If `true`, returns sequence number and primary term of the last modification of each hit.", + "description": "If `true`, the request returns the sequence number and primary term of the last modification of each hit.", "deprecated": false, "schema": { "type": "boolean" @@ -62467,7 +62481,7 @@ "search#q": { "in": "query", "name": "q", - "description": "Query in the Lucene query string syntax using query parameter search.\nQuery parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.", + "description": "A query in the Lucene query string syntax.\nQuery parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.\n\nIMPORTANT: This parameter overrides the query parameter in the request body.\nIf both parameters are specified, documents matching the query request body parameter are not returned.", "deprecated": false, "schema": { "type": "string" @@ -62477,7 +62491,7 @@ "search#size": { "in": "query", "name": "size", - "description": "Defines the number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "deprecated": false, "schema": { "type": "number" @@ -62487,7 +62501,7 @@ "search#from": { "in": "query", "name": "from", - "description": "Starting document offset.\nNeeds to be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset, which must be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "deprecated": false, "schema": { "type": "number" @@ -62497,7 +62511,7 @@ "search#sort": { "in": "query", "name": "sort", - "description": "A comma-separated list of : pairs.", + "description": "A comma-separated list of `:` pairs.", "deprecated": false, "schema": { "oneOf": [ @@ -64336,7 +64350,7 @@ "$ref": "#/components/schemas/_global.search._types:FieldCollapse" }, "explain": { - "description": "If true, returns detailed information about score computation as part of a hit.", + "description": "If `true`, the request returns detailed information about score computation as part of a hit.", "type": "boolean" }, "ext": { @@ -64347,7 +64361,7 @@ } }, "from": { - "description": "Starting document offset.\nNeeds to be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset, which must be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "highlight": { @@ -64357,7 +64371,10 @@ "$ref": "#/components/schemas/_global.search._types:TrackHits" }, "indices_boost": { - "description": "Boosts the _score of documents from specified indices.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-filter-context.html#relevance-scores" + }, + "description": "Boost the `_score` of documents from specified indices.\nThe boost value is the factor by which scores are multiplied.\nA boost value greater than `1.0` increases the score.\nA boost value between `0` and `1.0` decreases the score.", "type": "array", "items": { "type": "object", @@ -64367,14 +64384,20 @@ } }, "docvalue_fields": { - "description": "Array of wildcard (`*`) patterns.\nThe request returns doc values for field names matching these patterns in the `hits.fields` property of the response.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-fields.html#docvalue-fields" + }, + "description": "An array of wildcard (`*`) field patterns.\nThe request returns doc values for field names matching these patterns in the `hits.fields` property of the response.", "type": "array", "items": { "$ref": "#/components/schemas/_types.query_dsl:FieldAndFormat" } }, "knn": { - "description": "Defines the approximate kNN search to run.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html#approximate-knn" + }, + "description": "The approximate kNN search to run.", "oneOf": [ { "$ref": "#/components/schemas/_types:KnnSearch" @@ -64388,7 +64411,7 @@ ] }, "min_score": { - "description": "Minimum `_score` for matching documents.\nDocuments with a lower `_score` are not included in the search results.", + "description": "The minimum `_score` for matching documents.\nDocuments with a lower `_score` are not included in the search results.", "type": "number" }, "post_filter": { @@ -64429,7 +64452,7 @@ "$ref": "#/components/schemas/_types:SortResults" }, "size": { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return, which must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` property.", "type": "number" }, "slice": { @@ -64442,7 +64465,7 @@ "$ref": "#/components/schemas/_global.search._types:SourceConfig" }, "fields": { - "description": "Array of wildcard (`*`) patterns.\nThe request returns values for field names matching these patterns in the `hits.fields` property of the response.", + "description": "An array of wildcard (`*`) field patterns.\nThe request returns values for field names matching these patterns in the `hits.fields` property of the response.", "type": "array", "items": { "$ref": "#/components/schemas/_types.query_dsl:FieldAndFormat" @@ -64452,23 +64475,26 @@ "$ref": "#/components/schemas/_global.search._types:Suggester" }, "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.\nUse 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.\nIf set to `0` (default), the query does not terminate early.", + "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 property to each shard handling the request.\nWhen possible, let Elasticsearch perform early termination automatically.\nAvoid specifying this property for requests that target data streams with backing indices across multiple data tiers.\n\nIf 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.\nIf no response is received before the timeout expires, the request fails and returns an error.\nDefaults to no timeout.", + "description": "The period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nDefaults to no timeout.", "type": "string" }, "track_scores": { - "description": "If true, calculate and return document scores, even if the scores are not used for sorting.", + "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.", + "description": "If `true`, the request returns the 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.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html" + }, + "description": "If `true`, the request returns sequence number and primary term of the last modification of each hit.", "type": "boolean" }, "stored_fields": { @@ -64481,7 +64507,7 @@ "$ref": "#/components/schemas/_types.mapping:RuntimeFields" }, "stats": { - "description": "Stats groups to associate with the search.\nEach group maintains a statistics aggregation for its associated searches.\nYou can retrieve these stats using the indices stats API.", + "description": "The stats groups to associate with the search.\nEach group maintains a statistics aggregation for its associated searches.\nYou can retrieve these stats using the indices stats API.", "type": "array", "items": { "type": "string" diff --git a/output/schema/schema.json b/output/schema/schema.json index 51e5d03479..9a72791aba 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -14218,7 +14218,7 @@ "stability": "stable" } }, - "description": "Open a point in time.\n\nA search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent 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.", + "description": "Open a point in time.\n\nA search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent point in time.\n\nA point in time must be opened explicitly before being used in search requests.\n\nA subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time.\n\nJust like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits.\nIf you want to retrieve more hits, use PIT with `search_after`.\n\nIMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.\n\nWhen a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception.\nTo get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.\n\n**Keeping point in time alive**\n\nThe `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.\nThe value does not need to be long enough to process all data — it just needs to be long enough for the next request.\n\nNormally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments.\nOnce the smaller segments are no longer needed they are deleted.\nHowever, open point-in-times prevent the old segments from being deleted since they are still in use.\n\nTIP: Keeping older segments alive means that more disk space and file handles are needed.\nEnsure that you have configured your nodes to have ample free file handles.\n\nAdditionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request.\nEnsure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.\nNote that a point-in-time doesn't prevent its associated indices from being deleted.\nYou can check how many point-in-times (that is, search contexts) are open with the nodes stats API.", "docId": "point-in-time-api", "docTag": "search", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/point-in-time-api.html", @@ -15409,8 +15409,10 @@ "stability": "stable" } }, - "description": "Run a search.\n\nGet search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Run a search.\n\nGet search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html", + "extDocId": "ccs-privileges", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-cert.html#remote-clusters-privileges-ccs", "name": "search", "privileges": { "index": [ @@ -31240,7 +31242,7 @@ "kind": "properties", "properties": [ { - "description": "Allows to filter indices if the provided query rewrites to `match_none` on every shard.", + "description": "Filter indices if the provided query rewrites to `match_none` on every shard.", "name": "index_filter", "required": false, "type": { @@ -31253,7 +31255,7 @@ } ] }, - "description": "Open a point in time.\n\nA search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent 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.", + "description": "Open a point in time.\n\nA search request by default runs against the most recent visible data of the target indices,\nwhich is called point in time. Elasticsearch pit (point in time) is a lightweight view into the\nstate of the data as it existed when initiated. In some cases, it’s preferred to perform multiple\nsearch requests using the same point in time. For example, if refreshes happen between\n`search_after` requests, then the results of those requests might not be consistent as changes happening\nbetween searches are only visible to the more recent point in time.\n\nA point in time must be opened explicitly before being used in search requests.\n\nA subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time.\n\nJust like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits.\nIf you want to retrieve more hits, use PIT with `search_after`.\n\nIMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.\n\nWhen a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception.\nTo get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.\n\n**Keeping point in time alive**\n\nThe `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.\nThe value does not need to be long enough to process all data — it just needs to be long enough for the next request.\n\nNormally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments.\nOnce the smaller segments are no longer needed they are deleted.\nHowever, open point-in-times prevent the old segments from being deleted since they are still in use.\n\nTIP: Keeping older segments alive means that more disk space and file handles are needed.\nEnsure that you have configured your nodes to have ample free file handles.\n\nAdditionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request.\nEnsure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.\nNote that a point-in-time doesn't prevent its associated indices from being deleted.\nYou can check how many point-in-times (that is, search contexts) are open with the nodes stats API.", "inherits": { "type": { "name": "RequestBase", @@ -31280,7 +31282,7 @@ ], "query": [ { - "description": "Extends the time to live of the corresponding point in time.", + "description": "Extend the length of time that the point in time persists.", "name": "keep_alive", "required": true, "type": { @@ -31305,7 +31307,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": { @@ -31317,7 +31319,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -31329,7 +31331,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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.", + "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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.", "name": "expand_wildcards", "required": false, "serverDefault": "open", @@ -31342,7 +31344,7 @@ } }, { - "description": "If `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.\nIf `true`, the point in time will contain all the shards that are available at the time of the request.", + "description": "Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT.\nIf `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.\nIf `true`, the point in time will contain all the shards that are available at the time of the request.", "name": "allow_partial_search_results", "required": false, "serverDefault": false, @@ -31355,7 +31357,7 @@ } } ], - "specLocation": "_global/open_point_in_time/OpenPointInTimeRequest.ts#L25-L93" + "specLocation": "_global/open_point_in_time/OpenPointInTimeRequest.ts#L25-L121" }, { "kind": "response", @@ -33921,7 +33923,7 @@ } }, { - "description": "If true, returns detailed information about score computation as part of a hit.", + "description": "If `true`, the request returns detailed information about score computation as part of a hit.", "name": "explain", "required": false, "serverDefault": false, @@ -33953,7 +33955,7 @@ } }, { - "description": "Starting document offset.\nNeeds to be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset, which must be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "from", "required": false, "serverDefault": 0, @@ -33991,7 +33993,9 @@ } }, { - "description": "Boosts the _score of documents from specified indices.", + "description": "Boost the `_score` of documents from specified indices.\nThe boost value is the factor by which scores are multiplied.\nA boost value greater than `1.0` increases the score.\nA boost value between `0` and `1.0` decreases the score.", + "extDocId": "relevance-scores", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-filter-context.html#relevance-scores", "name": "indices_boost", "required": false, "type": { @@ -34017,7 +34021,9 @@ } }, { - "description": "Array of wildcard (`*`) patterns.\nThe request returns doc values for field names matching these patterns in the `hits.fields` property of the response.", + "description": "An array of wildcard (`*`) field patterns.\nThe request returns doc values for field names matching these patterns in the `hits.fields` property of the response.", + "extDocId": "docvalue-fields", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#docvalue-fields", "name": "docvalue_fields", "required": false, "type": { @@ -34038,7 +34044,9 @@ "since": "8.4.0" } }, - "description": "Defines the approximate kNN search to run.", + "description": "The approximate kNN search to run.", + "extDocId": "knn-approximate", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search.html#approximate-knn", "name": "knn", "required": false, "type": { @@ -34070,7 +34078,7 @@ "since": "8.8.0" } }, - "description": "Defines the Reciprocal Rank Fusion (RRF) to use.", + "description": "The Reciprocal Rank Fusion (RRF) to use.", "name": "rank", "required": false, "type": { @@ -34082,7 +34090,7 @@ } }, { - "description": "Minimum `_score` for matching documents.\nDocuments with a lower `_score` are not included in the search results.", + "description": "The minimum `_score` for matching documents.\nDocuments with a lower `_score` are not included in the search results.", "name": "min_score", "required": false, "type": { @@ -34119,7 +34127,9 @@ } }, { - "description": "Defines the search definition using the Query DSL.", + "description": "The search definition using the Query DSL.", + "extDocId": "query-dsl", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl.html", "name": "query", "required": false, "type": { @@ -34167,7 +34177,7 @@ "stability": "stable" } }, - "description": "A retriever is a specification to describe top documents returned from a search. A retriever replaces other elements of the search API that also return top documents such as query and knn.", + "description": "A retriever is a specification to describe top documents returned from a search.\nA retriever replaces other elements of the search API that also return top documents such as `query` and `knn`.", "name": "retriever", "required": false, "type": { @@ -34214,7 +34224,7 @@ } }, { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return, which must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` property.", "name": "size", "required": false, "serverDefault": 10, @@ -34227,7 +34237,7 @@ } }, { - "description": "Can be used to split a scrolled search into multiple slices that can be consumed independently.", + "description": "Split a scrolled search into multiple slices that can be consumed independently.", "name": "slice", "required": false, "type": { @@ -34240,8 +34250,8 @@ }, { "description": "A comma-separated list of : pairs.", - "docId": "sort-search-results", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", + "extDocId": "sort-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", "name": "sort", "required": false, "type": { @@ -34253,7 +34263,9 @@ } }, { - "description": "Indicates which source fields are returned for matching documents.\nThese fields are returned in the hits._source property of the search response.", + "description": "The source fields that are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nIf the `stored_fields` property is specified, the `_source` property defaults to `false`.\nOtherwise, it defaults to `true`.", + "extDocId": "source-filtering", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#source-filtering", "name": "_source", "required": false, "type": { @@ -34265,7 +34277,7 @@ } }, { - "description": "Array of wildcard (`*`) patterns.\nThe request returns values for field names matching these patterns in the `hits.fields` property of the response.", + "description": "An array of wildcard (`*`) field patterns.\nThe request returns values for field names matching these patterns in the `hits.fields` property of the response.", "name": "fields", "required": false, "type": { @@ -34292,7 +34304,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.\nUse 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.\nIf set to `0` (default), the query does not terminate early.", + "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 property to each shard handling the request.\nWhen possible, let Elasticsearch perform early termination automatically.\nAvoid specifying this property for requests that target data streams with backing indices across multiple data tiers.\n\nIf set to `0` (default), the query does not terminate early.", "name": "terminate_after", "required": false, "serverDefault": 0, @@ -34305,7 +34317,7 @@ } }, { - "description": "Specifies the period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nDefaults to no timeout.", + "description": "The period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nDefaults to no timeout.", "name": "timeout", "required": false, "type": { @@ -34317,7 +34329,7 @@ } }, { - "description": "If true, calculate and return document scores, even if the scores are not used for sorting.", + "description": "If `true`, calculate and return document scores, even if the scores are not used for sorting.", "name": "track_scores", "required": false, "serverDefault": false, @@ -34330,7 +34342,7 @@ } }, { - "description": "If true, returns document version as part of a hit.", + "description": "If `true`, the request returns the document version as part of a hit.", "name": "version", "required": false, "serverDefault": false, @@ -34343,7 +34355,9 @@ } }, { - "description": "If `true`, returns sequence number and primary term of the last modification of each hit.", + "description": "If `true`, the request returns sequence number and primary term of the last modification of each hit.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "seq_no_primary_term", "required": false, "type": { @@ -34355,7 +34369,9 @@ } }, { - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.\nYou can pass `_source: true` to return both source fields and stored fields in the search response.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` property defaults to `false`.\nYou can pass `_source: true` to return both source fields and stored fields in the search response.", + "extDocId": "stored-fields", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#stored-fields", "name": "stored_fields", "required": false, "type": { @@ -34367,7 +34383,7 @@ } }, { - "description": "Limits the search to a point in time (PIT).\nIf you provide a PIT, you cannot specify an `` in the request path.", + "description": "Limit the search to a point in time (PIT).\nIf you provide a PIT, you cannot specify an `` in the request path.", "name": "pit", "required": false, "type": { @@ -34379,7 +34395,9 @@ } }, { - "description": "Defines one or more runtime fields in the search request.\nThese fields take precedence over mapped fields with the same name.", + "description": "One or more runtime fields in the search request.\nThese fields take precedence over mapped fields with the same name.", + "extDocId": "runtime-search-request", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html", "name": "runtime_mappings", "required": false, "type": { @@ -34391,7 +34409,7 @@ } }, { - "description": "Stats groups to associate with the search.\nEach group maintains a statistics aggregation for its associated searches.\nYou can retrieve these stats using the indices stats API.", + "description": "The stats groups to associate with the search.\nEach group maintains a statistics aggregation for its associated searches.\nYou can retrieve these stats using the indices stats API.", "name": "stats", "required": false, "type": { @@ -34407,7 +34425,7 @@ } ] }, - "description": "Run a search.\n\nGet search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.", + "description": "Run a search.\n\nGet search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", "inherits": { "type": { "name": "RequestBase", @@ -34420,7 +34438,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": { @@ -34447,7 +34465,7 @@ } }, { - "description": "If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results.", + "description": "If `true` and there are shard request timeouts or shard failures, the request returns partial results.\nIf `false`, it returns an error with no partial results.\n\nTo override the default behavior, you can set the `search.default_allow_partial_results` cluster setting to `false`.", "name": "allow_partial_search_results", "required": false, "serverDefault": true, @@ -34460,7 +34478,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": { @@ -34472,7 +34490,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, @@ -34485,7 +34503,7 @@ } }, { - "description": "The number of shard results that should be reduced at once on the coordinating node.\nThis value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "description": "The number of shard results that should be reduced at once on the coordinating node.\nIf the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.", "name": "batched_reduce_size", "required": false, "serverDefault": 512, @@ -34498,9 +34516,9 @@ } }, { - "description": "If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests.", - "docId": "ccs-network-delays", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#ccs-network-delays", + "description": "If `true`, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.", + "extDocId": "ccs-network-delays", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#ccs-network-delays", "name": "ccs_minimize_roundtrips", "required": false, "serverDefault": true, @@ -34513,7 +34531,7 @@ } }, { - "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 the 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", @@ -34526,7 +34544,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": { @@ -34538,7 +34556,9 @@ } }, { - "description": "A comma-separated list of fields to return as the docvalue representation for each hit.", + "description": "A comma-separated list of fields to return as the docvalue representation of a field for each hit.", + "extDocId": "docvalue-fields", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#docvalue-fields", "name": "docvalue_fields", "required": false, "type": { @@ -34550,9 +34570,10 @@ } }, { - "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", "type": { "kind": "instance_of", "type": { @@ -34562,7 +34583,7 @@ } }, { - "description": "If `true`, returns detailed information about score computation as part of a hit.", + "description": "If `true`, the request returns detailed information about score computation as part of a hit.", "name": "explain", "required": false, "serverDefault": false, @@ -34575,6 +34596,10 @@ } }, { + "deprecation": { + "description": "", + "version": "7.16.0" + }, "description": "If `true`, concrete, expanded or aliased indices will be ignored when frozen.", "name": "ignore_throttled", "required": false, @@ -34601,7 +34626,7 @@ } }, { - "description": "Indicates whether hit.matched_queries should be rendered as a map that includes\nthe name of the matched query associated with its score (true)\nor as an array containing the name of the matched queries (false)\nThis functionality reruns each named query on every hit in a search response.\nTypically, this adds a small overhead to a request.\nHowever, using computationally expensive named queries on a large number of hits may add significant overhead.", + "description": "If `true`, the response includes the score contribution from any named queries.\n\nThis functionality reruns each named query on every hit in a search response.\nTypically, this adds a small overhead to a request.\nHowever, using computationally expensive named queries on a large number of hits may add significant overhead.", "name": "include_named_queries_score", "required": false, "serverDefault": false, @@ -34614,7 +34639,7 @@ } }, { - "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 only be used when the `q` query string parameter is specified.", + "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, @@ -34627,7 +34652,7 @@ } }, { - "description": "Defines the number of concurrent shard requests per node this search executes concurrently.\nThis value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "description": "The number of concurrent shard requests per node that the search runs concurrently.\nThis value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", "name": "max_concurrent_shard_requests", "required": false, "serverDefault": 5, @@ -34652,7 +34677,7 @@ } }, { - "description": "Nodes and shards used for the search.\nBy default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:\n`_only_local` to run the search only on shards on the local node;\n`_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method;\n`_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;\n`_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;\n`_shards:,` to run the search only on the specified shards;\n`` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order.", + "description": "The nodes and shards used for the search.\nBy default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness.\nValid values are:\n\n* `_only_local` to run the search only on shards on the local node;\n* `_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method;\n* `_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method;\n* `_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method;\n* `_shards:,` to run the search only on the specified shards;\n* `` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order.", "name": "preference", "required": false, "type": { @@ -34664,7 +34689,7 @@ } }, { - "description": "Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold.\nThis filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint).\nWhen unspecified, the pre-filter phase is executed if any of these conditions is met:\nthe request targets more than 128 shards;\nthe request targets one or more read-only index;\nthe primary sort of the query targets an indexed field.", + "description": "A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold.\nThis filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint).\nWhen unspecified, the pre-filter phase is executed if any of these conditions is met:\n\n* The request targets more than 128 shards.\n* The request targets one or more read-only index.\n* The primary sort of the query targets an indexed field.", "name": "pre_filter_shard_size", "required": false, "type": { @@ -34676,7 +34701,9 @@ } }, { - "description": "If `true`, the caching of search results is enabled for requests where `size` is `0`.\nDefaults to index level settings.", + "description": "If `true`, the caching of search results is enabled for requests where `size` is `0`.\nIt defaults to index level settings.", + "extDocId": "shard-request-cache", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shard-request-cache.html", "name": "request_cache", "required": false, "type": { @@ -34688,7 +34715,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -34700,9 +34727,9 @@ } }, { - "description": "Period to retain the search context for scrolling. See Scroll search results.\nBy default, this value cannot exceed `1d` (24 hours).\nYou can change this limit using the `search.max_keep_alive` cluster-level setting.", - "docId": "scroll-search-results", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", + "description": "The period to retain the search context for scrolling.\nBy default, this value cannot exceed `1d` (24 hours).\nYou can change this limit by using the `search.max_keep_alive` cluster-level setting.", + "extDocId": "scroll-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", "name": "scroll", "required": false, "type": { @@ -34714,7 +34741,9 @@ } }, { - "description": "How distributed term frequencies are calculated for relevance scoring.", + "description": "Indicates how distributed term frequencies are calculated for relevance scoring.", + "extDocId": "relevance-scores", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-filter-context.html#relevance-scores", "name": "search_type", "required": false, "type": { @@ -34742,6 +34771,8 @@ }, { "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.\nYou can pass `_source: true` to return both source fields and stored fields in the search response.", + "extDocId": "stored-fields", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#stored-fields", "name": "stored_fields", "required": false, "type": { @@ -34753,7 +34784,7 @@ } }, { - "description": "Specifies which field to use for suggestions.", + "description": "The field to use for suggestions.", "name": "suggest_field", "required": false, "type": { @@ -34765,7 +34796,7 @@ } }, { - "description": "Specifies the suggest mode.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The suggest mode.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "name": "suggest_mode", "required": false, "serverDefault": "missing", @@ -34778,7 +34809,7 @@ } }, { - "description": "Number of suggestions to return.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The number of suggestions to return.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "name": "suggest_size", "required": false, "type": { @@ -34790,7 +34821,7 @@ } }, { - "description": "The source text for which the suggestions should be returned.\nThis parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified.", + "description": "The source text for which the suggestions should be returned.\nThis parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified.", "name": "suggest_text", "required": false, "type": { @@ -34802,7 +34833,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.\nUse 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.\nIf set to `0` (default), the query does not terminate early.", + "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.\nIf set to `0` (default), the query does not terminate early.", "name": "terminate_after", "required": false, "serverDefault": 0, @@ -34815,7 +34846,7 @@ } }, { - "description": "Specifies the period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period of time to wait for a response from each shard.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt defaults to no timeout.", "name": "timeout", "required": false, "type": { @@ -34827,7 +34858,7 @@ } }, { - "description": "Number of hits matching the query to count accurately.\nIf `true`, the exact number of hits is returned at the cost of some performance.\nIf `false`, the response does not include the total number of hits matching the query.", + "description": "The number of hits matching the query to count accurately.\nIf `true`, the exact number of hits is returned at the cost of some performance.\nIf `false`, the response does not include the total number of hits matching the query.", "name": "track_total_hits", "required": false, "serverDefault": "10000", @@ -34840,7 +34871,7 @@ } }, { - "description": "If `true`, calculate and return document scores, even if the scores are not used for sorting.", + "description": "If `true`, the request calculates and returns document scores, even if the scores are not used for sorting.", "name": "track_scores", "required": false, "serverDefault": false, @@ -34856,7 +34887,7 @@ "description": "If `true`, aggregation and suggester names are be prefixed by their respective types in the response.", "name": "typed_keys", "required": false, - "serverDefault": true, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -34879,7 +34910,7 @@ } }, { - "description": "If `true`, returns document version as part of a hit.", + "description": "If `true`, the request returns the document version as part of a hit.", "name": "version", "required": false, "serverDefault": false, @@ -34892,7 +34923,7 @@ } }, { - "description": "Indicates which source fields are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nValid values are:\n`true` to return the entire document source;\n`false` to not return the document source;\n`` to return the source fields that are specified as a comma-separated list (supports wildcard (`*`) patterns).", + "description": "The source fields that are returned for matching documents.\nThese fields are returned in the `hits._source` property of the search response.\nValid values are:\n\n* `true` to return the entire document source.\n* `false` to not return the document source.\n* `` to return the source fields that are specified as a comma-separated list that supports wildcard (`*`) patterns.", "name": "_source", "required": false, "serverDefault": "true", @@ -34929,7 +34960,9 @@ } }, { - "description": "If `true`, returns sequence number and primary term of the last modification of each hit.", + "description": "If `true`, the request returns the sequence number and primary term of the last modification of each hit.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "seq_no_primary_term", "required": false, "type": { @@ -34941,7 +34974,7 @@ } }, { - "description": "Query in the Lucene query string syntax using query parameter search.\nQuery parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.", + "description": "A query in the Lucene query string syntax.\nQuery parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.\n\nIMPORTANT: This parameter overrides the query parameter in the request body.\nIf both parameters are specified, documents matching the query request body parameter are not returned.", "name": "q", "required": false, "type": { @@ -34953,7 +34986,7 @@ } }, { - "description": "Defines the number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "size", "required": false, "serverDefault": 10, @@ -34966,7 +34999,7 @@ } }, { - "description": "Starting document offset.\nNeeds to be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset, which must be non-negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "from", "required": false, "serverDefault": 0, @@ -34979,9 +35012,9 @@ } }, { - "description": "A comma-separated list of : pairs.", - "docId": "sort-search-results", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", + "description": "A comma-separated list of `:` pairs.", + "extDocId": "sort-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", "name": "sort", "required": false, "type": { @@ -35027,7 +35060,7 @@ } } ], - "specLocation": "_global/search/SearchRequest.ts#L54-L541" + "specLocation": "_global/search/SearchRequest.ts#L54-L589" }, { "kind": "response", @@ -35076,6 +35109,7 @@ }, "properties": [ { + "description": "The number of milliseconds it took Elasticsearch to run the request.\nThis value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response.\nIt includes:\n\n* Communication time between the coordinating node and data nodes\n* Time the request spends in the search thread pool, queued for execution\n* Actual run time\n\nIt does not include:\n\n* Time needed to send the request to Elasticsearch\n* Time needed to serialize the JSON response\n* Time needed to send the response to a client", "name": "took", "required": true, "type": { @@ -35087,6 +35121,7 @@ } }, { + "description": "If `true`, the request timed out before completion; returned results may be partial or empty.", "name": "timed_out", "required": true, "type": { @@ -35098,6 +35133,7 @@ } }, { + "description": "A count of shards used for the request.", "name": "_shards", "required": true, "type": { @@ -35109,6 +35145,7 @@ } }, { + "description": "The returned documents and metadata.", "name": "hits", "required": true, "type": { @@ -35224,6 +35261,9 @@ } }, { + "description": "The identifier for the search and its search context.\nYou can use this scroll ID with the scroll API to retrieve the next batch of search results for the request.\nThis property is returned only if the `scroll` query parameter is specified in the request.", + "extDocId": "scroll-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", "name": "_scroll_id", "required": false, "type": { @@ -35280,7 +35320,7 @@ } } ], - "specLocation": "_global/search/SearchResponse.ts#L38-L54" + "specLocation": "_global/search/SearchResponse.ts#L38-L84" }, { "kind": "interface", @@ -81251,7 +81291,7 @@ }, "properties": [ { - "description": "Wildcard pattern. The request returns values for field names matching this pattern.", + "description": "A wildcard pattern. The request returns values for field names matching this pattern.", "name": "field", "required": true, "type": { @@ -81263,7 +81303,7 @@ } }, { - "description": "Format in which the values are returned.", + "description": "The format in which the values are returned.", "name": "format", "required": false, "type": { diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 0d28cb6a1b..5908b76d80 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -66,6 +66,7 @@ ccr-put-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/refere ccr-put-follow,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-put-follow.html ccr-resume-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-resume-auto-follow-pattern.html ccs-network-delays,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#ccs-network-delays +ccs-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-cert.html#remote-clusters-privileges-ccs clean-up-snapshot-repo,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup clear-repositories-metering-archive-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-repositories-metering-archive-api.html clear-scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html @@ -151,6 +152,7 @@ docs-termvectors,https://www.elastic.co/guide/en/elasticsearch/reference/{branch docs-update-by-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update-by-query.html docs-update,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update.html document-input-parameters,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-mlt-query.html#_document_input_parameters +docvalue-fields,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#docvalue-fields dot-expand-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/dot-expand-processor.html drop-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/drop-processor.html enrich-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/enrich-processor.html @@ -286,6 +288,7 @@ json-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ k-precision,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#k-precision k-recall,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#k-recall kv-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/kv-processor.html +knn-approximate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search.html#approximate-knn knn-inner-hits,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search.html#nested-knn-search-inner-hits license-management,https://www.elastic.co/guide/en/kibana/{branch}/managing-licenses.html logstash-api-delete-pipeline,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/logstash-api-delete-pipeline.html @@ -450,6 +453,7 @@ query-dsl-span-not-query,https://www.elastic.co/guide/en/elasticsearch/reference query-dsl-span-or-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-or-query.html query-dsl-span-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-term-query.html query-dsl-span-within-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-within-query.html +query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-sparse-vector-query.html query-dsl-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-term-query.html query-dsl-terms-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-terms-query.html query-dsl-terms-set-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-terms-set-query.html @@ -472,6 +476,7 @@ redact-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch regexp-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/regexp-syntax.html register-repository,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html registered-domain-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/registered-domain-processor.html +relevance-scores,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-filter-context.html#relevance-scores remove-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remove-processor.html remote-clusters-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-api-key.html rename-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rename-processor.html @@ -675,6 +680,7 @@ security-user-cache,https://www.elastic.co/guide/en/elasticsearch/reference/{bra service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html +shard-request-cache,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shard-request-cache.html simulate-ingest-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-ingest-api.html simulate-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-pipeline-api.html slice-scroll,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#slice-scroll @@ -702,7 +708,7 @@ snapshot-repo-verify-integrity,https://www.elastic.co/guide/en/elasticsearch/ref sort-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-processor.html sort-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html sort-tiebreaker,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html#eql-search-specify-a-sort-tiebreaker -query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-sparse-vector-query.html +source-filtering,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#source-filtering split-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/split-processor.html sql-async-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html sql-async-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html @@ -722,6 +728,7 @@ start-trial,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sta stop-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-dfanalytics.html stop-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-trained-model-deployment.html stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-transform.html +stored-fields,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#stored-fields synonym-rule-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-synonym-rule.html synonym-rule-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-synonym-rule.html synonym-rule-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonym-rule.html diff --git a/specification/_global/open_point_in_time/OpenPointInTimeRequest.ts b/specification/_global/open_point_in_time/OpenPointInTimeRequest.ts index 9f3a67d893..0384ab2ab9 100644 --- a/specification/_global/open_point_in_time/OpenPointInTimeRequest.ts +++ b/specification/_global/open_point_in_time/OpenPointInTimeRequest.ts @@ -33,13 +33,40 @@ import { Duration } from '@_types/Time' * between searches are only visible to the more recent 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 subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time. + * + * Just like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits. + * If you want to retrieve more hits, use PIT with `search_after`. + * + * IMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request. + * + * When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception. + * To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime. + * + * **Keeping point in time alive** + * + * The `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time. + * The value does not need to be long enough to process all data — it just needs to be long enough for the next request. + * + * Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments. + * Once the smaller segments are no longer needed they are deleted. + * However, open point-in-times prevent the old segments from being deleted since they are still in use. + * + * TIP: Keeping older segments alive means that more disk space and file handles are needed. + * Ensure that you have configured your nodes to have ample free file handles. + * + * Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request. + * Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates. + * Note that a point-in-time doesn't prevent its associated indices from being deleted. + * You can check how many point-in-times (that is, search contexts) are open with the nodes stats API. * @rest_spec_name open_point_in_time * @availability stack since=7.10.0 stability=stable * @availability serverless stability=stable visibility=public * @doc_id point-in-time-api * @index_privileges read * @doc_tag search + * @doc_id point-in-time-api */ export interface Request extends RequestBase { urls: [ @@ -53,7 +80,7 @@ export interface Request extends RequestBase { } query_parameters: { /** - * Extends the time to live of the corresponding point in time. + * Extend the length of time that the point in time persists. */ keep_alive: Duration /** @@ -62,22 +89,23 @@ export interface Request extends RequestBase { */ ignore_unavailable?: boolean /** - * 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 that is used to route operations to a specific shard. */ routing?: Routing /** - * 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`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + * It supports comma-separated values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. * @server_default open */ expand_wildcards?: ExpandWildcards /** + * Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT. * If `false`, creating a point in time request when a shard is missing or unavailable will throw an exception. * If `true`, the point in time will contain all the shards that are available at the time of the request. * @server_default false @@ -86,7 +114,7 @@ export interface Request extends RequestBase { } body: { /** - * Allows to filter indices if the provided query rewrites to `match_none` on every shard. + * Filter indices if the provided query rewrites to `match_none` on every shard. */ index_filter?: QueryContainer } diff --git a/specification/_global/open_point_in_time/examples/response/OpenPointInTimeResponseExample1.yaml b/specification/_global/open_point_in_time/examples/response/OpenPointInTimeResponseExample1.yaml new file mode 100644 index 0000000000..2baad1e813 --- /dev/null +++ b/specification/_global/open_point_in_time/examples/response/OpenPointInTimeResponseExample1.yaml @@ -0,0 +1,16 @@ +# summary: +description: > + A successful response from `POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true`. + It includes a summary of the total number of shards, as well as the number of successful shards when creating the PIT. +# type: response +# response_code: '' +value: |- + { + "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=", + "_shards": { + "total": 10, + "successful": 10, + "skipped": 0, + "failed": 0 + } + } diff --git a/specification/_global/search/SearchRequest.ts b/specification/_global/search/SearchRequest.ts index ebabdc59a8..a301e869a6 100644 --- a/specification/_global/search/SearchRequest.ts +++ b/specification/_global/search/SearchRequest.ts @@ -57,10 +57,26 @@ import { Suggester } from './_types/suggester' * Get search hits that match the query defined in the request. * You can provide search queries using the `q` query string parameter or the request body. * If both are specified, only the query parameter is used. + * + * If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. + * To search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices. + * + * **Search slicing** + * + * When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties. + * By default the splitting is done first on the shards, then locally on each shard. + * The local splitting partitions the shard into contiguous ranges based on Lucene document IDs. + * + * For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard. + * + * IMPORTANT: The same point-in-time ID should be used for all slices. + * If different PIT IDs are used, slices can overlap and miss documents. + * This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index. * @rest_spec_name search * @availability stack stability=stable * @availability serverless stability=stable visibility=public * @index_privileges read + * @ext_doc_id ccs-privileges */ export interface Request extends RequestBase { urls: [ @@ -75,8 +91,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 @@ -90,62 +106,68 @@ export interface Request extends RequestBase { */ allow_no_indices?: boolean /** - * If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. + * If `true` and there are shard request timeouts or shard failures, the request returns partial results. + * If `false`, it returns an error with no partial results. + * + * To override the default behavior, you can set the `search.default_allow_partial_results` cluster setting to `false`. * @server_default true */ allow_partial_search_results?: 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. + * If `true`, wildcard and prefix queries are analyzed. + * This parameter can be used only when the `q` query string parameter is specified. * @server_default false */ analyze_wildcard?: boolean /** * The number of shard results that should be reduced at once on the coordinating node. - * This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large. + * If the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request. * @server_default 512 */ batched_reduce_size?: long /** - * If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests. - * @doc_id ccs-network-delays + * If `true`, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests. + * @ext_doc_id ccs-network-delays * @server_default true */ ccs_minimize_roundtrips?: 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. + * The default operator for the query string query: `AND` or `OR`. + * 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 /** - * A comma-separated list of fields to return as the docvalue representation for each hit. + * A comma-separated list of fields to return as the docvalue representation of a field for each hit. + * @ext_doc_id docvalue-fields */ docvalue_fields?: Fields /** - * 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`, returns detailed information about score computation as part of a hit. + * If `true`, the request returns detailed information about score computation as part of a hit. * @server_default false */ explain?: boolean /** * If `true`, concrete, expanded or aliased indices will be ignored when frozen. * @server_default true + * @deprecated 7.16.0 */ ignore_throttled?: boolean /** @@ -154,9 +176,8 @@ export interface Request extends RequestBase { */ ignore_unavailable?: boolean /** - * Indicates whether hit.matched_queries should be rendered as a map that includes - * the name of the matched query associated with its score (true) - * or as an array containing the name of the matched queries (false) + * If `true`, the response includes the score contribution from any named queries. + * * This functionality reruns each named query on every hit in a search response. * Typically, this adds a small overhead to a request. * However, using computationally expensive named queries on a large number of hits may add significant overhead. @@ -165,12 +186,12 @@ export interface Request extends RequestBase { include_named_queries_score?: 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 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 */ lenient?: boolean /** - * Defines the number of concurrent shard requests per node this search executes concurrently. + * The number of concurrent shard requests per node that the search runs concurrently. * This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests. * @server_default 5 */ @@ -181,43 +202,48 @@ export interface Request extends RequestBase { */ min_compatible_shard_node?: VersionString /** - * Nodes and shards used for the search. - * By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are: - * `_only_local` to run the search only on shards on the local node; - * `_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method; - * `_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method; - * `_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method; - * `_shards:,` to run the search only on the specified shards; - * `` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order. + * The nodes and shards used for the search. + * By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. + * Valid values are: + * + * * `_only_local` to run the search only on shards on the local node; + * * `_local` to, if possible, run the search on shards on the local node, or if not, select shards using the default method; + * * `_only_nodes:,` to run the search on only the specified nodes IDs, where, if suitable shards exist on more than one selected node, use shards on those nodes using the default method, or if none of the specified nodes are available, select shards from any available node using the default method; + * * `_prefer_nodes:,` to if possible, run the search on the specified nodes IDs, or if not, select shards using the default method; + * * `_shards:,` to run the search only on the specified shards; + * * `` (any string that does not start with `_`) to route searches with the same `` to the same shards in the same order. */ preference?: string /** - * Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. + * A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. * This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint). * When unspecified, the pre-filter phase is executed if any of these conditions is met: - * the request targets more than 128 shards; - * the request targets one or more read-only index; - * the primary sort of the query targets an indexed field. + * + * * The request targets more than 128 shards. + * * The request targets one or more read-only index. + * * The primary sort of the query targets an indexed field. */ pre_filter_shard_size?: long /** * If `true`, the caching of search results is enabled for requests where `size` is `0`. - * Defaults to index level settings. + * It defaults to index level settings. + * @ext_doc_id shard-request-cache */ request_cache?: boolean /** - * Custom value used to route operations to a specific shard. + * A custom value that is used to route operations to a specific shard. */ routing?: Routing /** - * Period to retain the search context for scrolling. See Scroll search results. + * The period to retain the search context for scrolling. * By default, this value cannot exceed `1d` (24 hours). - * You can change this limit using the `search.max_keep_alive` cluster-level setting. - * @doc_id scroll-search-results + * You can change this limit by using the `search.max_keep_alive` cluster-level setting. + * @ext_doc_id scroll-search-results */ scroll?: Duration /** - * How distributed term frequencies are calculated for relevance scoring. + * Indicates how distributed term frequencies are calculated for relevance scoring. + * @ext_doc_id relevance-scores */ search_type?: SearchType /** @@ -229,33 +255,35 @@ export interface Request extends RequestBase { * If no fields are specified, no stored fields are included in the response. * If this field is specified, the `_source` parameter defaults to `false`. * You can pass `_source: true` to return both source fields and stored fields in the search response. + * @ext_doc_id stored-fields */ stored_fields?: Fields /** - * Specifies which field to use for suggestions. + * The field to use for suggestions. */ suggest_field?: Field /** - * Specifies the suggest mode. - * This parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified. + * The suggest mode. + * This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. * @server_default missing */ suggest_mode?: SuggestMode /** - * Number of suggestions to return. - * This parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified. + * The number of suggestions to return. + * This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. */ suggest_size?: long /** * The source text for which the suggestions should be returned. - * This parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified. + * This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. */ suggest_text?: string /** - * 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. - * Use with caution. + * + * 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. @@ -264,25 +292,26 @@ export interface Request extends RequestBase { */ terminate_after?: long /** - * Specifies the period of time to wait for a response from each shard. + * 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. + * It defaults to no timeout. */ timeout?: Duration /** - * Number of hits matching the query to count accurately. + * The number of hits matching the query to count accurately. * If `true`, the exact number of hits is returned at the cost of some performance. * If `false`, the response does not include the total number of hits matching the query. * @server_default 10000 */ track_total_hits?: TrackHits /** - * If `true`, calculate and return document scores, even if the scores are not used for sorting. + * If `true`, the request calculates and returns document scores, even if the scores are not used for sorting. * @server_default false */ track_scores?: boolean /** * If `true`, aggregation and suggester names are be prefixed by their respective types in the response. - * @server_default true + * @server_default false */ typed_keys?: boolean /** @@ -291,17 +320,18 @@ export interface Request extends RequestBase { */ rest_total_hits_as_int?: boolean /** - * If `true`, returns document version as part of a hit. + * If `true`, the request returns the document version as part of a hit. * @server_default false */ version?: boolean /** - * Indicates which source fields are returned for matching documents. + * The source fields that are returned for matching documents. * These fields are returned in the `hits._source` property of the search response. * Valid values are: - * `true` to return the entire document source; - * `false` to not return the document source; - * `` to return the source fields that are specified as a comma-separated list (supports wildcard (`*`) patterns). + * + * * `true` to return the entire document source. + * * `false` to not return the document source. + * * `` to return the source fields that are specified as a comma-separated list that supports wildcard (`*`) patterns. * @server_default true */ _source?: SourceConfigParam @@ -319,32 +349,35 @@ export interface Request extends RequestBase { */ _source_includes?: Fields /** - * If `true`, returns sequence number and primary term of the last modification of each hit. + * If `true`, the request returns the sequence number and primary term of the last modification of each hit. + * @ext_doc_id optimistic-concurrency */ seq_no_primary_term?: boolean /** - * Query in the Lucene query string syntax using query parameter search. + * A query in the Lucene query string syntax. * Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing. + * + * IMPORTANT: This parameter overrides the query parameter in the request body. + * If both parameters are specified, documents matching the query request body parameter are not returned. */ q?: string /** - * Defines the number of hits to return. + * 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. * @server_default 10 */ size?: integer /** - * Starting document offset. - * Needs to be non-negative. + * The starting document offset, which must 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. * @server_default 0 */ from?: integer /** - * A comma-separated list of : pairs. - * @doc_id sort-search-results + * A comma-separated list of `:` pairs. + * @ext_doc_id sort-search-results */ sort?: string | string[] /** @@ -366,7 +399,7 @@ export interface Request extends RequestBase { */ collapse?: FieldCollapse /** - * If true, returns detailed information about score computation as part of a hit. + * If `true`, the request returns detailed information about score computation as part of a hit. * @server_default false */ explain?: boolean @@ -375,8 +408,7 @@ export interface Request extends RequestBase { */ ext?: Dictionary /** - * Starting document offset. - * Needs to be non-negative. + * The starting document offset, which must 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. * @server_default 0 @@ -394,27 +426,33 @@ export interface Request extends RequestBase { */ track_total_hits?: TrackHits /** - * Boosts the _score of documents from specified indices. + * Boost the `_score` of documents from specified indices. + * The boost value is the factor by which scores are multiplied. + * A boost value greater than `1.0` increases the score. + * A boost value between `0` and `1.0` decreases the score. + * @ext_doc_id relevance-scores */ indices_boost?: Array> /** - * Array of wildcard (`*`) patterns. + * An array of wildcard (`*`) field patterns. * The request returns doc values for field names matching these patterns in the `hits.fields` property of the response. + * @ext_doc_id docvalue-fields */ docvalue_fields?: FieldAndFormat[] /** - * Defines the approximate kNN search to run. + * The approximate kNN search to run. * @availability stack since=8.4.0 * @availability serverless + * @ext_doc_id knn-approximate */ knn?: KnnSearch | KnnSearch[] /** - * Defines the Reciprocal Rank Fusion (RRF) to use. + * The Reciprocal Rank Fusion (RRF) to use. * @availability stack since=8.8.0 */ rank?: RankContainer /** - * Minimum `_score` for matching documents. + * The minimum `_score` for matching documents. * Documents with a lower `_score` are not included in the search results. */ min_score?: double @@ -431,7 +469,8 @@ export interface Request extends RequestBase { */ profile?: boolean /** - * Defines the search definition using the Query DSL. + * The search definition using the Query DSL. + * @ext_doc_id query-dsl */ query?: QueryContainer /** @@ -439,7 +478,8 @@ export interface Request extends RequestBase { */ rescore?: Rescore | Rescore[] /** - * A retriever is a specification to describe top documents returned from a search. A retriever replaces other elements of the search API that also return top documents such as query and knn. + * A retriever is a specification to describe top documents returned from a search. + * A retriever replaces other elements of the search API that also return top documents such as `query` and `knn`. * @availability stack since=8.14.0 stability=stable * @availability serverless stability=stable */ @@ -453,28 +493,31 @@ export interface Request extends RequestBase { */ search_after?: SortResults /** - * The number of hits to return. + * The number of hits to return, which must not be 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. + * To page through more hits, use the `search_after` property. * @server_default 10 */ size?: integer /** - * Can be used to split a scrolled search into multiple slices that can be consumed independently. + * Split a scrolled search into multiple slices that can be consumed independently. */ slice?: SlicedScroll /** * A comma-separated list of : pairs. - * @doc_id sort-search-results + * @ext_doc_id sort-search-results */ sort?: Sort /** - * Indicates which source fields are returned for matching documents. - * These fields are returned in the hits._source property of the search response. + * The source fields that are returned for matching documents. + * These fields are returned in the `hits._source` property of the search response. + * If the `stored_fields` property is specified, the `_source` property defaults to `false`. + * Otherwise, it defaults to `true`. + * @ext_doc_id source-filtering */ _source?: SourceConfig /** - * Array of wildcard (`*`) patterns. + * An array of wildcard (`*`) field patterns. * The request returns values for field names matching these patterns in the `hits.fields` property of the response. */ fields?: Array @@ -483,56 +526,61 @@ export interface Request extends RequestBase { */ suggest?: Suggester /** - * 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. - * Use with caution. - * Elasticsearch applies this parameter to each shard handling the request. + * + * IMPORTANT: Use with caution. + * Elasticsearch applies this property 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. + * Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers. + * * If set to `0` (default), the query does not terminate early. * @server_default 0 */ terminate_after?: long /** - * Specifies the period of time to wait for a response from each shard. + * 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. */ timeout?: string /** - * If true, calculate and return document scores, even if the scores are not used for sorting. + * If `true`, calculate and return document scores, even if the scores are not used for sorting. * @server_default false */ track_scores?: boolean /** - * If true, returns document version as part of a hit. + * If `true`, the request returns the document version as part of a hit. * @server_default false */ version?: boolean /** - * If `true`, returns sequence number and primary term of the last modification of each hit. + * If `true`, the request returns sequence number and primary term of the last modification of each hit. + * @ext_doc_id optimistic-concurrency */ seq_no_primary_term?: boolean /** - * List of stored fields to return as part of a hit. + * A comma-separated list of stored fields to return as part of a hit. * If no fields are specified, no stored fields are included in the response. - * If this field is specified, the `_source` parameter defaults to `false`. + * If this field is specified, the `_source` property defaults to `false`. * You can pass `_source: true` to return both source fields and stored fields in the search response. + * @ext_doc_id stored-fields */ stored_fields?: Fields /** - * Limits the search to a point in time (PIT). + * Limit the search to a point in time (PIT). * If you provide a PIT, you cannot specify an `` in the request path. */ pit?: PointInTimeReference /** - * Defines one or more runtime fields in the search request. + * One or more runtime fields in the search request. * These fields take precedence over mapped fields with the same name. + * @ext_doc_id runtime-search-request */ runtime_mappings?: RuntimeFields /** - * Stats groups to associate with the search. + * The 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. */ diff --git a/specification/_global/search/SearchResponse.ts b/specification/_global/search/SearchResponse.ts index c0fa8cd20f..33fdeb3042 100644 --- a/specification/_global/search/SearchResponse.ts +++ b/specification/_global/search/SearchResponse.ts @@ -37,9 +37,33 @@ export class Response { export class ResponseBody { // Has to be kept in sync with SearchTemplateResponse + /** + * The number of milliseconds it took Elasticsearch to run the request. + * This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. + * It includes: + * + * * Communication time between the coordinating node and data nodes + * * Time the request spends in the search thread pool, queued for execution + * * Actual run time + * + * It does not include: + * + * * Time needed to send the request to Elasticsearch + * * Time needed to serialize the JSON response + * * Time needed to send the response to a client + */ took: long + /** + * If `true`, the request timed out before completion; returned results may be partial or empty. + */ timed_out: boolean + /** + * A count of shards used for the request. + */ _shards: ShardStatistics + /** + * The returned documents and metadata. + */ hits: HitsMetadata aggregations?: Dictionary _clusters?: ClusterStatistics @@ -48,6 +72,12 @@ export class ResponseBody { num_reduce_phases?: long profile?: Profile pit_id?: Id + /** + * The identifier for the search and its search context. + * You can use this scroll ID with the scroll API to retrieve the next batch of search results for the request. + * This property is returned only if the `scroll` query parameter is specified in the request. + * @ext_doc_id scroll-search-results + */ _scroll_id?: ScrollId suggest?: Dictionary[]> terminated_early?: boolean diff --git a/specification/_global/search/examples/200_response/SearchResponseExample1.yaml b/specification/_global/search/examples/200_response/SearchResponseExample1.yaml new file mode 100644 index 0000000000..f4d14616ce --- /dev/null +++ b/specification/_global/search/examples/200_response/SearchResponseExample1.yaml @@ -0,0 +1,50 @@ +# summary: +description: > + An abbreviated response from `GET /my-index-000001/_search?from=40&size=20` with a simple term query. +# type: response +# response_code: '' +value: |- + { + "took": 5, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 20, + "relation": "eq" + }, + "max_score": 1.3862942, + "hits": [ + { + "_index": "my-index-000001", + "_id": "0", + "_score": 1.3862942, + "_source": { + "@timestamp": "2099-11-15T14:12:12", + "http": { + "request": { + "method": "get" + }, + "response": { + "status_code": 200, + "bytes": 1070000 + }, + "version": "1.1" + }, + "source": { + "ip": "127.0.0.1" + }, + "message": "GET /search HTTP/1.1 200 1070000", + "user": { + "id": "kimchy" + } + } + } + ] + } + } diff --git a/specification/_global/search/examples/request/SearchRequestExample1.yaml b/specification/_global/search/examples/request/SearchRequestExample1.yaml new file mode 100644 index 0000000000..18224878e6 --- /dev/null +++ b/specification/_global/search/examples/request/SearchRequestExample1.yaml @@ -0,0 +1,13 @@ +summary: A simple term search +# method_request: GET /my-index-000001/_search?from=40&size=20 +description: > + Run `GET /my-index-000001/_search?from=40&size=20` to run a search. +# type: request +value: |- + { + "query": { + "term": { + "user.id": "kimchy" + } + } + } diff --git a/specification/_global/search/examples/request/SearchRequestExample2.yaml b/specification/_global/search/examples/request/SearchRequestExample2.yaml new file mode 100644 index 0000000000..cec7a7cad6 --- /dev/null +++ b/specification/_global/search/examples/request/SearchRequestExample2.yaml @@ -0,0 +1,20 @@ +summary: A point in time search +# method_request: POST /_search +description: > + Run `POST /_search` to run a point in time search. + The `id` parameter tells Elasticsearch to run the request using contexts from this open point in time. + The `keep_alive` parameter tells Elasticsearch how long it should extend the time to live of the point in time. +# type: request +value: |- + { + "size": 100, + "query": { + "match" : { + "title" : "elasticsearch" + } + }, + "pit": { + "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", + "keep_alive": "1m" + } + } diff --git a/specification/_global/search/examples/request/SearchRequestExample3.yaml b/specification/_global/search/examples/request/SearchRequestExample3.yaml new file mode 100644 index 0000000000..bc2da206b0 --- /dev/null +++ b/specification/_global/search/examples/request/SearchRequestExample3.yaml @@ -0,0 +1,23 @@ +summary: Search slicing +# method_request: GET /_search +description: > + When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently. + The result from running the first `GET /_search` request returns documents belonging to the first slice (`id: 0`). + If you run a second request with `id` set to `1', it returns documents in the second slice. + Since the maximum number of slices is set to `2`, the union of the results is equivalent to the results of a point-in-time search without slicing. +# type: request +value: |- + { + "slice": { + "id": 0, + "max": 2 + }, + "query": { + "match": { + "message": "foo" + } + }, + "pit": { + "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==" + } + } diff --git a/specification/_types/query_dsl/abstractions.ts b/specification/_types/query_dsl/abstractions.ts index 6ecdb11e9c..9c7c3767dc 100644 --- a/specification/_types/query_dsl/abstractions.ts +++ b/specification/_types/query_dsl/abstractions.ts @@ -532,11 +532,11 @@ export enum CombinedFieldsZeroTerms { */ export class FieldAndFormat { /** - * Wildcard pattern. The request returns values for field names matching this pattern. + * A wildcard pattern. The request returns values for field names matching this pattern. */ field: Field /** - * Format in which the values are returned. + * The format in which the values are returned. */ format?: string include_unmapped?: boolean