diff --git a/docs/doc_examples/120fcf9f55128d6a81d5e87a9c235bbd.asciidoc b/docs/doc_examples/120fcf9f55128d6a81d5e87a9c235bbd.asciidoc new file mode 100644 index 000000000..f6c1cb881 --- /dev/null +++ b/docs/doc_examples/120fcf9f55128d6a81d5e87a9c235bbd.asciidoc @@ -0,0 +1,20 @@ +// This file is autogenerated, DO NOT EDIT +// Use `node scripts/generate-docs-examples.js` to generate the docs examples + +[source, js] +---- +const response = await client.transport.request({ + method: "POST", + path: "/_inference/chat_completion/openai-completion/_stream", + body: { + model: "gpt-4o", + messages: [ + { + role: "user", + content: "What is Elastic?", + }, + ], + }, +}); +console.log(response); +---- diff --git a/docs/doc_examples/ddaadd91b7743a1c7e946ce1b593cd1b.asciidoc b/docs/doc_examples/141ef0ebaa3b0772892b79b9bb85efb0.asciidoc similarity index 65% rename from docs/doc_examples/ddaadd91b7743a1c7e946ce1b593cd1b.asciidoc rename to docs/doc_examples/141ef0ebaa3b0772892b79b9bb85efb0.asciidoc index bd9c35360..7d7aeab98 100644 --- a/docs/doc_examples/ddaadd91b7743a1c7e946ce1b593cd1b.asciidoc +++ b/docs/doc_examples/141ef0ebaa3b0772892b79b9bb85efb0.asciidoc @@ -3,11 +3,13 @@ [source, js] ---- -const response = await client.inference.inference({ +const response = await client.inference.put({ task_type: "my-inference-endpoint", inference_id: "_update", - service_settings: { - api_key: "", + inference_config: { + service_settings: { + api_key: "", + }, }, }); console.log(response); diff --git a/docs/doc_examples/2f72a63c73dd672ac2dc3997ad15dd41.asciidoc b/docs/doc_examples/2f72a63c73dd672ac2dc3997ad15dd41.asciidoc new file mode 100644 index 000000000..e1edb8658 --- /dev/null +++ b/docs/doc_examples/2f72a63c73dd672ac2dc3997ad15dd41.asciidoc @@ -0,0 +1,23 @@ +// This file is autogenerated, DO NOT EDIT +// Use `node scripts/generate-docs-examples.js` to generate the docs examples + +[source, js] +---- +const response = await client.indices.create({ + index: "test-index", + mappings: { + properties: { + source_field: { + type: "text", + fields: { + infer_field: { + type: "semantic_text", + inference_id: ".elser-2-elasticsearch", + }, + }, + }, + }, + }, +}); +console.log(response); +---- diff --git a/docs/doc_examples/31bc93e429ad0de11dd2dd231e8f2c5e.asciidoc b/docs/doc_examples/31bc93e429ad0de11dd2dd231e8f2c5e.asciidoc deleted file mode 100644 index 36c1c5a79..000000000 --- a/docs/doc_examples/31bc93e429ad0de11dd2dd231e8f2c5e.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -// This file is autogenerated, DO NOT EDIT -// Use `node scripts/generate-docs-examples.js` to generate the docs examples - -[source, js] ----- -const response = await client.indices.unfreeze({ - index: "my-index-000001", -}); -console.log(response); ----- diff --git a/docs/doc_examples/38ba93890494bfa7beece58dffa44f98.asciidoc b/docs/doc_examples/38ba93890494bfa7beece58dffa44f98.asciidoc deleted file mode 100644 index f9dca64fb..000000000 --- a/docs/doc_examples/38ba93890494bfa7beece58dffa44f98.asciidoc +++ /dev/null @@ -1,23 +0,0 @@ -// This file is autogenerated, DO NOT EDIT -// Use `node scripts/generate-docs-examples.js` to generate the docs examples - -[source, js] ----- -const response = await client.bulk({ - index: "test-index", - operations: [ - { - update: { - _id: "1", - }, - }, - { - doc: { - infer_field: "updated inference field", - source_field: "updated source field", - }, - }, - ], -}); -console.log(response); ----- diff --git a/docs/doc_examples/45954b8aaedfed57012be8b6538b0a24.asciidoc b/docs/doc_examples/45954b8aaedfed57012be8b6538b0a24.asciidoc new file mode 100644 index 000000000..a2ff623e6 --- /dev/null +++ b/docs/doc_examples/45954b8aaedfed57012be8b6538b0a24.asciidoc @@ -0,0 +1,47 @@ +// This file is autogenerated, DO NOT EDIT +// Use `node scripts/generate-docs-examples.js` to generate the docs examples + +[source, js] +---- +const response = await client.transport.request({ + method: "POST", + path: "/_inference/chat_completion/openai-completion/_stream", + body: { + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: "What's the price of a scarf?", + }, + ], + }, + ], + tools: [ + { + type: "function", + function: { + name: "get_current_price", + description: "Get the current price of a item", + parameters: { + type: "object", + properties: { + item: { + id: "123", + }, + }, + }, + }, + }, + ], + tool_choice: { + type: "function", + function: { + name: "get_current_price", + }, + }, + }, +}); +console.log(response); +---- diff --git a/docs/doc_examples/519e46350316a33162740e5d7968aa2c.asciidoc b/docs/doc_examples/519e46350316a33162740e5d7968aa2c.asciidoc new file mode 100644 index 000000000..3c92986f6 --- /dev/null +++ b/docs/doc_examples/519e46350316a33162740e5d7968aa2c.asciidoc @@ -0,0 +1,20 @@ +// This file is autogenerated, DO NOT EDIT +// Use `node scripts/generate-docs-examples.js` to generate the docs examples + +[source, js] +---- +const response = await client.search({ + index: "image-index", + knn: { + field: "image-vector", + query_vector: [-5, 9, -12], + k: 10, + num_candidates: 100, + rescore_vector: { + oversample: 2, + }, + }, + fields: ["title", "file-type"], +}); +console.log(response); +---- diff --git a/docs/doc_examples/ee05714a83d75fb6858e3b9fcbeb8f8b.asciidoc b/docs/doc_examples/681d24c2633f598fc43d6afff8996dbb.asciidoc similarity index 96% rename from docs/doc_examples/ee05714a83d75fb6858e3b9fcbeb8f8b.asciidoc rename to docs/doc_examples/681d24c2633f598fc43d6afff8996dbb.asciidoc index abb8e0b60..bfb21cf32 100644 --- a/docs/doc_examples/ee05714a83d75fb6858e3b9fcbeb8f8b.asciidoc +++ b/docs/doc_examples/681d24c2633f598fc43d6afff8996dbb.asciidoc @@ -5,6 +5,9 @@ ---- const response = await client.indices.create({ index: "retrievers_example", + settings: { + number_of_shards: 1, + }, mappings: { properties: { vector: { @@ -12,6 +15,9 @@ const response = await client.indices.create({ dims: 3, similarity: "l2_norm", index: true, + index_options: { + type: "flat", + }, }, text: { type: "text", diff --git a/docs/doc_examples/9d47f02a063444da9f098858a1830d28.asciidoc b/docs/doc_examples/77cebba946fe648873a1e7375c13df41.asciidoc similarity index 66% rename from docs/doc_examples/9d47f02a063444da9f098858a1830d28.asciidoc rename to docs/doc_examples/77cebba946fe648873a1e7375c13df41.asciidoc index b10da9a05..a09e089bb 100644 --- a/docs/doc_examples/9d47f02a063444da9f098858a1830d28.asciidoc +++ b/docs/doc_examples/77cebba946fe648873a1e7375c13df41.asciidoc @@ -5,7 +5,8 @@ ---- const response = await client.cluster.putSettings({ persistent: { - "cluster.routing.allocation.disk.watermark.low": "30gb", + "cluster.routing.allocation.disk.watermark.low": "90%", + "cluster.routing.allocation.disk.watermark.high": "95%", }, }); console.log(response); diff --git a/docs/doc_examples/93c77c65f1e11382f8043d0300e87b89.asciidoc b/docs/doc_examples/7bdc283b96c7a965fae23013647b8578.asciidoc similarity index 100% rename from docs/doc_examples/93c77c65f1e11382f8043d0300e87b89.asciidoc rename to docs/doc_examples/7bdc283b96c7a965fae23013647b8578.asciidoc index 7a9809243..7f416d2de 100644 --- a/docs/doc_examples/93c77c65f1e11382f8043d0300e87b89.asciidoc +++ b/docs/doc_examples/7bdc283b96c7a965fae23013647b8578.asciidoc @@ -7,14 +7,14 @@ const response = await client.indices.create({ index: "test-index", mappings: { properties: { - infer_field: { - type: "semantic_text", - inference_id: ".elser-2-elasticsearch", - }, source_field: { type: "text", copy_to: "infer_field", }, + infer_field: { + type: "semantic_text", + inference_id: ".elser-2-elasticsearch", + }, }, }, }); diff --git a/docs/doc_examples/82bb6c61dab959f4446dc5ecab7ecbdf.asciidoc b/docs/doc_examples/82bb6c61dab959f4446dc5ecab7ecbdf.asciidoc new file mode 100644 index 000000000..7c7a7cba1 --- /dev/null +++ b/docs/doc_examples/82bb6c61dab959f4446dc5ecab7ecbdf.asciidoc @@ -0,0 +1,34 @@ +// This file is autogenerated, DO NOT EDIT +// Use `node scripts/generate-docs-examples.js` to generate the docs examples + +[source, js] +---- +const response = await client.transport.request({ + method: "POST", + path: "/_inference/chat_completion/openai-completion/_stream", + body: { + messages: [ + { + role: "assistant", + content: "Let's find out what the weather is", + tool_calls: [ + { + id: "call_KcAjWtAww20AihPHphUh46Gd", + type: "function", + function: { + name: "get_current_weather", + arguments: '{"location":"Boston, MA"}', + }, + }, + ], + }, + { + role: "tool", + content: "The weather is cold", + tool_call_id: "call_KcAjWtAww20AihPHphUh46Gd", + }, + ], + }, +}); +console.log(response); +---- diff --git a/docs/doc_examples/bee3fda7bb07086243424b62e5b16ca7.asciidoc b/docs/doc_examples/948418e0ef1b7e7cfee2f11be715d7d2.asciidoc similarity index 93% rename from docs/doc_examples/bee3fda7bb07086243424b62e5b16ca7.asciidoc rename to docs/doc_examples/948418e0ef1b7e7cfee2f11be715d7d2.asciidoc index 9ab13275d..5a4bb2510 100644 --- a/docs/doc_examples/bee3fda7bb07086243424b62e5b16ca7.asciidoc +++ b/docs/doc_examples/948418e0ef1b7e7cfee2f11be715d7d2.asciidoc @@ -5,6 +5,9 @@ ---- const response = await client.indices.create({ index: "retrievers_example_nested", + settings: { + number_of_shards: 1, + }, mappings: { properties: { nested_field: { @@ -18,6 +21,9 @@ const response = await client.indices.create({ dims: 3, similarity: "l2_norm", index: true, + index_options: { + type: "flat", + }, }, }, }, diff --git a/docs/reference.asciidoc b/docs/reference.asciidoc index b8c69b9b4..a027e3341 100644 --- a/docs/reference.asciidoc +++ b/docs/reference.asciidoc @@ -28,9 +28,116 @@ [discrete] === bulk Bulk index or delete documents. -Performs multiple indexing or delete operations in a single API call. +Perform multiple `index`, `create`, `delete`, and `update` actions in a single request. This reduces overhead and can greatly increase indexing speed. +If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: + +* To use the `create` action, you must have the `create_doc`, `create`, `index`, or `write` index privilege. Data streams support only the `create` action. +* To use the `index` action, you must have the `create`, `index`, or `write` index privilege. +* To use the `delete` action, you must have the `delete` or `write` index privilege. +* To use the `update` action, you must have the `index` or `write` index privilege. +* To automatically create a data stream or index with a bulk API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. +* To make the result of a bulk operation visible to search using the `refresh` parameter, you must have the `maintenance` or `manage` index privilege. + +Automatic data stream creation requires a matching index template with data stream enabled. + +The actions are specified in the request body using a newline delimited JSON (NDJSON) structure: + +---- +action_and_meta_data\n +optional_source\n +action_and_meta_data\n +optional_source\n +.... +action_and_meta_data\n +optional_source\n +---- + +The `index` and `create` actions expect a source on the next line and have the same semantics as the `op_type` parameter in the standard index API. +A `create` action fails if a document with the same ID already exists in the target +An `index` action adds or replaces a document as necessary. + +NOTE: Data streams support only the `create` action. +To update or delete a document in a data stream, you must target the backing index containing the document. + +An `update` action expects that the partial doc, upsert, and script and its options are specified on the next line. + +A `delete` action does not expect a source on the next line and has the same semantics as the standard delete API. + +NOTE: The final line of data must end with a newline character (`\n`). +Each newline character may be preceded by a carriage return (`\r`). +When sending NDJSON data to the `_bulk` endpoint, use a `Content-Type` header of `application/json` or `application/x-ndjson`. +Because this format uses literal newline characters (`\n`) as delimiters, make sure that the JSON actions and sources are not pretty printed. + +If you provide a target in the request path, it is used for any actions that don't explicitly specify an `_index` argument. + +A note on the format: the idea here is to make processing as fast as possible. +As some of the actions are redirected to other shards on other nodes, only `action_meta_data` is parsed on the receiving node side. + +Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible. + +There is no "correct" number of actions to perform in a single bulk request. +Experiment with different settings to find the optimal size for your particular workload. +Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. +It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. +For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch. + +**Client suppport for bulk requests** + +Some of the officially supported clients provide helpers to assist with bulk requests and reindexing: + +* Go: Check out `esutil.BulkIndexer` +* Perl: Check out `Search::Elasticsearch::Client::5_0::Bulk` and `Search::Elasticsearch::Client::5_0::Scroll` +* Python: Check out `elasticsearch.helpers.*` +* JavaScript: Check out `client.helpers.*` +* .NET: Check out `BulkAllObservable` +* PHP: Check out bulk indexing. + +**Submitting bulk requests with cURL** + +If you're providing text file input to `curl`, you must use the `--data-binary` flag instead of plain `-d`. +The latter doesn't preserve newlines. For example: + +---- +$ cat requests +{ "index" : { "_index" : "test", "_id" : "1" } } +{ "field1" : "value1" } +$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo +{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]} +---- + +**Optimistic concurrency control** + +Each `index` and `delete` action within a bulk API call may include the `if_seq_no` and `if_primary_term` parameters in their respective action and meta data lines. +The `if_seq_no` and `if_primary_term` parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details. + +**Versioning** + +Each bulk item can include the version value using the `version` field. +It automatically follows the behavior of the index or delete operation based on the `_version` mapping. +It also support the `version_type`. + +**Routing** + +Each bulk item can include the routing value using the `routing` field. +It automatically follows the behavior of the index or delete operation based on the `_routing` mapping. + +NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. + +**Wait for active shards** + +When making bulk calls, you can set the `wait_for_active_shards` parameter to require a minimum number of shard copies to be active before starting to process the bulk request. + +**Refresh** + +Control when the changes made by this request are visible to search. + +NOTE: Only the shards that receive the bulk request will be affected by refresh. +Imagine a `_bulk?refresh=wait_for` request with three documents in it that happen to be routed to different shards in an index with five shards. +The request will only wait for those three shards to refresh. +The other two shards that make up the index do not participate in the `_bulk` request at all. + {ref}/docs-bulk.html[Endpoint documentation] [source,ts] ---- @@ -40,28 +147,23 @@ client.bulk({ ... }) ==== Arguments * *Request (object):* -** *`index` (Optional, string)*: Name of the data stream, index, or index alias to perform bulk actions on. +** *`index` (Optional, string)*: The name of the data stream, index, or index alias to perform bulk actions on. ** *`operations` (Optional, { index, create, update, delete } | { detect_noop, doc, doc_as_upsert, script, scripted_upsert, _source, upsert } | object[])* -** *`list_executed_pipelines` (Optional, boolean)*: If `true`, the response will include the ingest pipelines that were executed for each index or create. -** *`pipeline` (Optional, string)*: ID of the pipeline to use to preprocess incoming documents. -If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. -If a final pipeline is configured it will always run, regardless of the value of this parameter. -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. -Valid values: `true`, `false`, `wait_for`. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`_source` (Optional, boolean | string | string[])*: `true` or `false` to return the `_source` field or not, or a list of fields to return. -** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. -** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -** *`timeout` (Optional, string | -1 | 0)*: Period each action waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). -** *`require_alias` (Optional, boolean)*: If `true`, the request’s actions must target an index alias. -** *`require_data_stream` (Optional, boolean)*: If `true`, the request's actions must target a data stream (existing or to-be-created). +** *`list_executed_pipelines` (Optional, boolean)*: If `true`, the response will include the ingest pipelines that were run for each index or create. +** *`pipeline` (Optional, string)*: The pipeline identifier to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter. +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. If `wait_for`, wait for a refresh to make this operation visible to search. If `false`, do nothing with refreshes. Valid values: `true`, `false`, `wait_for`. +** *`routing` (Optional, string)*: A custom value that is used to route operations to a specific shard. +** *`_source` (Optional, boolean | string | string[])*: Indicates whether to return the `_source` field (`true` or `false`) or contains a list of fields to return. +** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`timeout` (Optional, string | -1 | 0)*: The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards. The default is `1m` (one minute), which guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). The default is `1`, which waits for each primary shard to be active. +** *`require_alias` (Optional, boolean)*: If `true`, the request's actions must target an index alias. +** *`require_data_stream` (Optional, boolean)*: If `true`, the request's actions must target a data stream (existing or to be created). [discrete] === clear_scroll Clear a scrolling search. - Clear the search context and results for a scrolling search. {ref}/clear-scroll-api.html[Endpoint documentation] @@ -73,13 +175,11 @@ client.clearScroll({ ... }) ==== Arguments * *Request (object):* -** *`scroll_id` (Optional, string | string[])*: List of scroll IDs to clear. -To clear all scroll IDs, use `_all`. +** *`scroll_id` (Optional, string | string[])*: A list of scroll IDs to clear. To clear all scroll IDs, use `_all`. IMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter. [discrete] === close_point_in_time Close a point in time. - A point in time must be opened explicitly before being used in search requests. The `keep_alive` parameter tells Elasticsearch how long it should persist. A point in time is automatically closed when the `keep_alive` period has elapsed. @@ -101,6 +201,15 @@ client.closePointInTime({ id }) Count search results. Get the number of documents matching a query. +The query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body. +The latter must be nested in a `query` key, which is the same as the search API. + +The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices. + +The operation is broadcast across all shards. +For each shard ID group, a replica is chosen and the search is run against it. +This means that replicas increase the scalability of the count. + {ref}/search-count.html[Endpoint documentation] [source,ts] ---- @@ -110,40 +219,97 @@ client.count({ ... }) ==== Arguments * *Request (object):* -** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases to search. -Supports wildcards (`*`). -To search all data streams and indices, omit this parameter or use `*` or `_all`. -** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Defines the search definition using the Query DSL. -** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. -This behavior applies even if the request targets other open indices. -** *`analyzer` (Optional, string)*: Analyzer to use for the query string. -This parameter can only be used when the `q` query string parameter is specified. -** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. -This parameter can only be used when the `q` query string parameter is specified. -** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: `AND` or `OR`. -This parameter can only be used when the `q` query string parameter is specified. -** *`df` (Optional, string)*: 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. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. -** *`ignore_throttled` (Optional, boolean)*: If `true`, concrete, expanded or aliased indices are ignored when frozen. +** *`index` (Optional, string | string[])*: A 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`. +** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Defines the search definition using the Query DSL. The query is optional, and when not provided, it will use `match_all` to count all the docs. +** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. +** *`analyzer` (Optional, string)*: The analyzer to use for the query string. This parameter can be used only when the `q` query string parameter is specified. +** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. This parameter can be used only when the `q` query string parameter is specified. +** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: `AND` or `OR`. This parameter can be used only when the `q` query string parameter is specified. +** *`df` (Optional, string)*: 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. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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. It supports a list of values, such as `open,hidden`. +** *`ignore_throttled` (Optional, boolean)*: If `true`, concrete, expanded, or aliased indices are ignored when frozen. ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. -** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. -** *`min_score` (Optional, number)*: Sets the minimum `_score` value that documents must have to be included in the result. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`terminate_after` (Optional, number)*: 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. -** *`q` (Optional, string)*: Query in the Lucene query string syntax. +** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the `q` query string parameter is specified. +** *`min_score` (Optional, number)*: The minimum `_score` value that documents must have to be included in the result. +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. By default, it is random. +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`terminate_after` (Optional, number)*: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. +** *`q` (Optional, string)*: The query in Lucene query string syntax. [discrete] === create -Index a document. -Adds a JSON document to the specified data stream or index and makes it searchable. -If the target is an index and the document already exists, the request updates the document and increments its version. +Create a new document in the index. + +You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs +Using `_create` guarantees that the document is indexed only if it does not already exist. +It returns a 409 response when a document with a same ID already exists in the index. +To update an existing document, you must use the `//_doc/` API. + +If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: + +* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege. +* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. + +Automatic data stream creation requires a matching index template with data stream enabled. + +**Automatically create data streams and indices** + +If the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream. + +If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates. + +NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation. + +If no mapping exists, the index operation creates a dynamic mapping. +By default, new fields and objects are automatically added to the mapping if needed. + +Automatic index creation is controlled by the `action.auto_create_index` setting. +If it is `true`, any index can be created automatically. +You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely. +Specify a list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. +When a list is specified, the default behaviour is to disallow. + +NOTE: The `action.auto_create_index` setting affects the automatic creation of indices only. +It does not affect the creation of data streams. + +**Routing** + +By default, shard placement — or routing — is controlled by using a hash of the document's ID value. +For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter. + +When setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself. +This does come at the (very minimal) cost of an additional document parsing pass. +If the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted. + +NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. + +**Distributed** + +The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. +After the primary shard completes the operation, if needed, the update is distributed to applicable replicas. + +**Active shards** + +To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. +If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. +By default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`). +This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. +To alter this behavior per operation, use the `wait_for_active_shards request` parameter. + +Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1). +Specifying a negative value or a number greater than the number of shard copies will throw an error. + +For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). +If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. +This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. +If `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. +This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. +However, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. +The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard. + +It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. +After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. +The `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed. {ref}/docs-index_.html[Endpoint documentation] [source,ts] @@ -154,28 +320,58 @@ client.create({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Unique identifier for the document. -** *`index` (string)*: Name of the data stream or index to target. -If the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. -If the target doesn’t exist and doesn’t match a data stream template, this request creates the index. +** *`id` (string)*: A unique identifier for the document. To automatically generate a document ID, use the `POST //_doc/` request format. +** *`index` (string)*: The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. If the target doesn't exist and doesn’t match a data stream template, this request creates the index. ** *`document` (Optional, object)*: A document. -** *`pipeline` (Optional, string)*: ID of the pipeline to use to preprocess incoming documents. -If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. -If a final pipeline is configured it will always run, regardless of the value of this parameter. -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. -Valid values: `true`, `false`, `wait_for`. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`timeout` (Optional, string | -1 | 0)*: Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. -** *`version` (Optional, number)*: Explicit version number for concurrency control. -The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: `external`, `external_gte`. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). +** *`pipeline` (Optional, string)*: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter. +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. If `wait_for`, it waits for a refresh to make this operation visible to search. If `false`, it does nothing with refreshes. +** *`routing` (Optional, string)*: A custom value that is used to route operations to a specific shard. +** *`timeout` (Optional, string | -1 | 0)*: The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. Elasticsearch waits for at least the specified timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur. This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur. +** *`version` (Optional, number)*: The explicit version number for concurrency control. It must be a non-negative long number. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. You can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). The default value of `1` means it waits for each primary shard to be active. [discrete] === delete Delete a document. -Removes a JSON document from the specified index. + +Remove a JSON document from the specified index. + +NOTE: You cannot send deletion requests directly to a data stream. +To delete a document in a data stream, you must target the backing index containing the document. + +**Optimistic concurrency control** + +Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters. +If a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`. + +**Versioning** + +Each document indexed is versioned. +When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. +Every write operation run on a document, deletes included, causes its version to be incremented. +The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. +The length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting. + +**Routing** + +If routing is used during indexing, the routing value also needs to be specified to delete a document. + +If the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request. + +For example: + +---- +DELETE /my-index-000001/_doc/1?routing=shard-1 +---- + +This request deletes the document with ID 1, but it is routed based on the user. +The document is not deleted if the correct routing is not specified. + +**Distributed** + +The delete operation gets hashed into a specific shard ID. +It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group. {ref}/docs-delete.html[Endpoint documentation] [source,ts] @@ -186,25 +382,100 @@ client.delete({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Unique identifier for the document. -** *`index` (string)*: Name of the target index. +** *`id` (string)*: A unique identifier for the document. +** *`index` (string)*: The name of the target index. ** *`if_primary_term` (Optional, number)*: Only perform the operation if the document has this primary term. ** *`if_seq_no` (Optional, number)*: Only perform the operation if the document has this sequence number. -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. -Valid values: `true`, `false`, `wait_for`. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for active shards. -** *`version` (Optional, number)*: Explicit version number for concurrency control. -The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: `external`, `external_gte`. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. If `wait_for`, it waits for a refresh to make this operation visible to search. If `false`, it does nothing with refreshes. +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for active shards. This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. Some reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation. By default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error. +** *`version` (Optional, number)*: An explicit version number for concurrency control. It must match the current version of the document for the request to succeed. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The minimum number of shard copies that must be active before proceeding with the operation. You can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). The default value of `1` means it waits for each primary shard to be active. [discrete] === delete_by_query Delete documents. + Deletes documents that match the specified query. +If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias: + +* `read` +* `delete` or `write` + +You can specify the query criteria in the request URI or the request body using the same syntax as the search API. +When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. +If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails. + +NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number. + +While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. +A bulk delete request is performed for each batch of matching documents. +If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. +If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. +Any delete requests that completed successfully still stick, they are not rolled back. + +You can opt to count version conflicts instead of halting and returning by setting `conflicts` to `proceed`. +Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than `max_docs` until it has successfully deleted `max_docs documents`, or it has gone through every document in the source query. + +**Throttling delete requests** + +To control the rate at which delete by query issues batches of delete operations, you can set `requests_per_second` to any positive decimal number. +This pads each batch with a wait time to throttle the rate. +Set `requests_per_second` to `-1` to disable throttling. + +Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. +The padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing. +By default the batch size is `1000`, so if `requests_per_second` is set to `500`: + +---- +target_time = 1000 / 500 per second = 2 seconds +wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds +---- + +Since the batch is issued as a single `_bulk` request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. +This is "bursty" instead of "smooth". + +**Slicing** + +Delete by query supports sliced scroll to parallelize the delete process. +This can improve efficiency and provide a convenient way to break the request down into smaller parts. + +Setting `slices` to `auto` lets Elasticsearch choose the number of slices to use. +This setting will use one slice per shard, up to a certain limit. +If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. +Adding slices to the delete by query operation creates sub-requests which means it has some quirks: + +* You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices. +* Fetching the status of the task for the request with slices only contains the status of completed slices. +* These sub-requests are individually addressable for things like cancellation and rethrottling. +* Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally. +* Canceling the request with `slices` will cancel each sub-request. +* Due to the nature of `slices` each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution. +* Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being deleted. +* Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time. + +If you're slicing manually or otherwise tuning automatic slicing, keep in mind that: + +* Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many `slices` hurts performance. Setting `slices` higher than the number of shards generally does not improve efficiency and adds overhead. +* Delete performance scales linearly across available resources with the number of slices. + +Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources. + +**Cancel a delete by query operation** + +Any delete by query can be canceled using the task cancel API. For example: + +---- +POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel +---- + +The task ID can be found by using the get tasks API. + +Cancellation should happen quickly but might take a few seconds. +The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself. + {ref}/docs-delete-by-query.html[Endpoint documentation] [source,ts] ---- @@ -214,55 +485,38 @@ client.deleteByQuery({ index }) ==== Arguments * *Request (object):* -** *`index` (string | string[])*: List of data streams, indices, and aliases to search. -Supports wildcards (`*`). -To search all data streams or indices, omit this parameter or use `*` or `_all`. +** *`index` (string | string[])*: A list of data streams, indices, and aliases to search. It supports wildcards (`*`). To search all data streams or indices, omit this parameter or use `*` or `_all`. ** *`max_docs` (Optional, number)*: The maximum number of documents to delete. -** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Specifies the documents to delete using the Query DSL. +** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: The documents to delete specified with Query DSL. ** *`slice` (Optional, { field, id, max })*: Slice the request manually using the provided slice ID and total number of slices. -** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. -This behavior applies even if the request targets other open indices. -For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. -** *`analyzer` (Optional, string)*: Analyzer to use for the query string. -** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. +** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. +** *`analyzer` (Optional, string)*: Analyzer to use for the query string. This parameter can be used only when the `q` query string parameter is specified. +** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. This parameter can be used only when the `q` query string parameter is specified. ** *`conflicts` (Optional, Enum("abort" | "proceed"))*: What to do if delete by query hits version conflicts: `abort` or `proceed`. -** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: `AND` or `OR`. -** *`df` (Optional, string)*: Field to use as default where no field prefix is given in the query string. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. +** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: `AND` or `OR`. This parameter can be used only when the `q` query string parameter is specified. +** *`df` (Optional, string)*: The field to use as default where no field prefix is given in the query string. This parameter can be used only when the `q` query string parameter is specified. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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. It supports a list of values, such as `open,hidden`. ** *`from` (Optional, number)*: Starting offset (default: 0) ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. -** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. -** *`refresh` (Optional, boolean)*: If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes. -** *`request_cache` (Optional, boolean)*: If `true`, the request cache is used for this request. -Defaults to the index-level setting. +** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the `q` query string parameter is specified. +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. It is random by default. +** *`refresh` (Optional, boolean)*: If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes. This is different than the delete API's `refresh` parameter, which causes just the shard that received the delete request to be refreshed. Unlike the delete API, it does not support `wait_for`. +** *`request_cache` (Optional, boolean)*: If `true`, the request cache is used for this request. Defaults to the index-level setting. ** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`q` (Optional, string)*: Query in the Lucene query string syntax. -** *`scroll` (Optional, string | -1 | 0)*: Period to retain the search context for scrolling. -** *`scroll_size` (Optional, number)*: Size of the scroll request that powers the operation. -** *`search_timeout` (Optional, string | -1 | 0)*: Explicit timeout for each search request. -Defaults to no timeout. -** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: The type of the search operation. -Available options: `query_then_fetch`, `dfs_query_then_fetch`. +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`q` (Optional, string)*: A query in the Lucene query string syntax. +** *`scroll` (Optional, string | -1 | 0)*: The period to retain the search context for scrolling. +** *`scroll_size` (Optional, number)*: The size of the scroll request that powers the operation. +** *`search_timeout` (Optional, string | -1 | 0)*: The explicit timeout for each search request. It defaults to no timeout. +** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: The type of the search operation. Available options include `query_then_fetch` and `dfs_query_then_fetch`. ** *`slices` (Optional, number | Enum("auto"))*: The number of slices this task should be divided into. -** *`sort` (Optional, string[])*: A list of : pairs. -** *`stats` (Optional, string[])*: Specific `tag` of the request for logging and statistical purposes. -** *`terminate_after` (Optional, number)*: 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. -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. -** *`timeout` (Optional, string | -1 | 0)*: Period each deletion request waits for active shards. +** *`sort` (Optional, string[])*: A list of `:` pairs. +** *`stats` (Optional, string[])*: The specific `tag` of the request for logging and statistical purposes. +** *`terminate_after` (Optional, number)*: 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. 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. +** *`timeout` (Optional, string | -1 | 0)*: The period each deletion request waits for active shards. ** *`version` (Optional, boolean)*: If `true`, returns the document version as part of a hit. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). -** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks until the operation is complete. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). The `timeout` value controls how long each write request waits for unavailable shards to become available. +** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks until the operation is complete. If `false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at `.tasks/task/${taskId}`. When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space. [discrete] === delete_by_query_rethrottle @@ -281,7 +535,7 @@ client.deleteByQueryRethrottle({ task_id }) * *Request (object):* ** *`task_id` (string | number)*: The ID for the task. -** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. +** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. To disable throttling, set it to `-1`. [discrete] === delete_script @@ -298,15 +552,30 @@ client.deleteScript({ id }) * *Request (object):* ** *`id` (string)*: Identifier for the stored script or search template. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. -If no response is received before the timeout expires, the request fails and returns an error. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. -If no response is received before the timeout expires, the request fails and returns an error. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] === exists Check a document. -Checks if a specified document exists. + +Verify that a document exists. +For example, check to see if a document with the `_id` 0 exists: + +---- +HEAD my-index-000001/_doc/0 +---- + +If the document exists, the API returns a status code of `200 - OK`. +If the document doesn’t exist, the API returns `404 - Not Found`. + +**Versioning support** + +You can use the `version` parameter to check the document only if its current version is equal to the specified one. + +Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. +The old version of the document doesn't disappear immediately, although you won't be able to access it. +Elasticsearch cleans up deleted documents in the background as you continue to index more data. {ref}/docs-get.html[Endpoint documentation] [source,ts] @@ -317,28 +586,31 @@ client.exists({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Identifier of the document. -** *`index` (string)*: List of data streams, indices, and aliases. -Supports wildcards (`*`). -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`id` (string)*: A unique document identifier. +** *`index` (string)*: A list of data streams, indices, and aliases. It supports wildcards (`*`). +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas. If it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible. If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value. This can help with "jumping values" when hitting different shards in different refresh states. A sample value can be something like the web session ID or the user name. ** *`realtime` (Optional, boolean)*: If `true`, the request is real-time as opposed to near-real-time. -** *`refresh` (Optional, boolean)*: If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes. -** *`routing` (Optional, string)*: Target the specified primary shard. -** *`_source` (Optional, boolean | string | string[])*: `true` or `false` to return the `_source` field or not, or a list of fields to return. -** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude in the response. -** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -** *`stored_fields` (Optional, string | string[])*: 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. -** *`version` (Optional, number)*: Explicit version number for concurrency control. -The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: `external`, `external_gte`. +** *`refresh` (Optional, boolean)*: If `true`, the request refreshes the relevant shards before retrieving the document. Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`_source` (Optional, boolean | string | string[])*: Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. +** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`stored_fields` (Optional, string | string[])*: A 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`. +** *`version` (Optional, number)*: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. [discrete] === exists_source Check for a document source. -Checks if a document's `_source` is stored. + +Check whether a document source exists in an index. +For example: + +---- +HEAD my-index-000001/_source/1 +---- + +A document's source is not available if it is disabled in the mapping. {ref}/docs-get.html[Endpoint documentation] [source,ts] @@ -349,20 +621,17 @@ client.existsSource({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Identifier of the document. -** *`index` (string)*: List of data streams, indices, and aliases. -Supports wildcards (`*`). -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. -** *`realtime` (Optional, boolean)*: If true, the request is real-time as opposed to near-real-time. -** *`refresh` (Optional, boolean)*: If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes. -** *`routing` (Optional, string)*: Target the specified primary shard. -** *`_source` (Optional, boolean | string | string[])*: `true` or `false` to return the `_source` field or not, or a list of fields to return. +** *`id` (string)*: A unique identifier for the document. +** *`index` (string)*: A list of data streams, indices, and aliases. It supports wildcards (`*`). +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas. +** *`realtime` (Optional, boolean)*: If `true`, the request is real-time as opposed to near-real-time. +** *`refresh` (Optional, boolean)*: If `true`, the request refreshes the relevant shards before retrieving the document. Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`_source` (Optional, boolean | string | string[])*: Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. ** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude in the response. ** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -** *`version` (Optional, number)*: Explicit version number for concurrency control. -The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: `external`, `external_gte`. +** *`version` (Optional, number)*: The version number for concurrency control. It must match the current version of the document for the request to succeed. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. [discrete] === explain @@ -379,17 +648,14 @@ client.explain({ id, index }) * *Request (object):* ** *`id` (string)*: Defines the document ID. -** *`index` (string)*: Index names used to limit the request. -Only a single index name can be provided to this parameter. +** *`index` (string)*: Index names used to limit the request. Only a single index name can be provided to this parameter. ** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Defines the search definition using the Query DSL. -** *`analyzer` (Optional, string)*: Analyzer to use for the query string. -This parameter can only be used when the `q` query string parameter is specified. +** *`analyzer` (Optional, string)*: Analyzer to use for the query string. This parameter can only be used when the `q` query string parameter is specified. ** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. ** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: `AND` or `OR`. ** *`df` (Optional, string)*: Field to use as default where no field prefix is given in the query string. ** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. ** *`_source` (Optional, boolean | string | string[])*: True or false to return the `_source` field or not, or a list of fields to return. ** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. @@ -419,11 +685,8 @@ client.fieldCaps({ ... }) ** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all. ** *`fields` (Optional, string | string[])*: List of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported. ** *`index_filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Allows to filter indices if the provided query rewrites to match_none on every shard. -** *`runtime_mappings` (Optional, Record)*: Defines ad-hoc runtime fields in the request similar to the way it is done in search requests. -These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings. -** *`allow_no_indices` (Optional, boolean)*: If false, the request returns an error if any wildcard expression, index alias, -or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request -targeting `foo*,bar*` returns an error if an index starts with foo but no index starts with bar. +** *`runtime_mappings` (Optional, Record)*: Defines ad-hoc runtime fields in the request similar to the way it is done in search requests. These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings. +** *`allow_no_indices` (Optional, boolean)*: If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with foo but no index starts with bar. ** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. ** *`ignore_unavailable` (Optional, boolean)*: If `true`, missing or closed indices are not included in the response. ** *`include_unmapped` (Optional, boolean)*: If true, unmapped fields are included in the response. @@ -434,7 +697,63 @@ targeting `foo*,bar*` returns an error if an index starts with foo but no index [discrete] === get Get a document by its ID. -Retrieves the document with the specified ID from an index. + +Get a document and its source or stored fields from an index. + +By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search). +In the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields. +To turn off realtime behavior, set the `realtime` parameter to false. + +**Source filtering** + +By default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off. +You can turn off `_source` retrieval by using the `_source` parameter: + +---- +GET my-index-000001/_doc/0?_source=false +---- + +If you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields. +This can be helpful with large documents where partial retrieval can save on network overhead +Both parameters take a comma separated list of fields or wildcard expressions. +For example: + +---- +GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities +---- + +If you only want to specify includes, you can use a shorter notation: + +---- +GET my-index-000001/_doc/0?_source=*.id +---- + +**Routing** + +If routing is used during indexing, the routing value also needs to be specified to retrieve a document. +For example: + +---- +GET my-index-000001/_doc/2?routing=user1 +---- + +This request gets the document with ID 2, but it is routed based on the user. +The document is not fetched if the correct routing is not specified. + +**Distributed** + +The GET operation is hashed into a specific shard ID. +It is then redirected to one of the replicas within that shard ID and returns the result. +The replicas are the primary shard and its replicas within that shard ID group. +This means that the more replicas you have, the better your GET scaling will be. + +**Versioning support** + +You can use the `version` parameter to retrieve the document only if its current version is equal to the specified one. + +Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. +The old version of the document doesn't disappear immediately, although you won't be able to access it. +Elasticsearch cleans up deleted documents in the background as you continue to index more data. {ref}/docs-get.html[Endpoint documentation] [source,ts] @@ -445,23 +764,19 @@ client.get({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Unique identifier of the document. -** *`index` (string)*: Name of the index that contains the document. -** *`force_synthetic_source` (Optional, boolean)*: Should this request force synthetic _source? -Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. -Fetches with this enabled will be slower the enabling synthetic source natively in the index. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. +** *`id` (string)*: A unique document identifier. +** *`index` (string)*: The name of the index that contains the document. +** *`force_synthetic_source` (Optional, boolean)*: Indicates whether the request forces synthetic `_source`. Use this paramater to test if the mapping supports synthetic `_source` and to get a sense of the worst case performance. Fetches with this parameter enabled will be slower than enabling synthetic source natively in the index. +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas. If it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible. If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value. This can help with "jumping values" when hitting different shards in different refresh states. A sample value can be something like the web session ID or the user name. ** *`realtime` (Optional, boolean)*: If `true`, the request is real-time as opposed to near-real-time. -** *`refresh` (Optional, boolean)*: If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes. -** *`routing` (Optional, string)*: Target the specified primary shard. -** *`_source` (Optional, boolean | string | string[])*: True or false to return the _source field or not, or a list of fields to return. -** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude in the response. -** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -** *`stored_fields` (Optional, string | string[])*: 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. -** *`version` (Optional, number)*: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: internal, external, external_gte. +** *`refresh` (Optional, boolean)*: If `true`, the request refreshes the relevant shards before retrieving the document. Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`_source` (Optional, boolean | string | string[])*: Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. +** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`stored_fields` (Optional, string | string[])*: A 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`. Only leaf fields can be retrieved with the `stored_field` option. Object fields can't be returned;if specified, the request fails. +** *`version` (Optional, number)*: The version number for concurrency control. It must match the current version of the document for the request to succeed. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. [discrete] === get_script @@ -507,7 +822,19 @@ client.getScriptLanguages() [discrete] === get_source Get a document's source. -Returns the source of a document. + +Get the source of a document. +For example: + +---- +GET my-index-000001/_source/1 +---- + +You can use the source filtering parameters to control which parts of the `_source` are returned: + +---- +GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities +---- {ref}/docs-get.html[Endpoint documentation] [source,ts] @@ -518,18 +845,18 @@ client.getSource({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Unique identifier of the document. -** *`index` (string)*: Name of the index that contains the document. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. -** *`realtime` (Optional, boolean)*: Boolean) If true, the request is real-time as opposed to near-real-time. -** *`refresh` (Optional, boolean)*: If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes. -** *`routing` (Optional, string)*: Target the specified primary shard. -** *`_source` (Optional, boolean | string | string[])*: True or false to return the _source field or not, or a list of fields to return. +** *`id` (string)*: A unique document identifier. +** *`index` (string)*: The name of the index that contains the document. +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas. +** *`realtime` (Optional, boolean)*: If `true`, the request is real-time as opposed to near-real-time. +** *`refresh` (Optional, boolean)*: If `true`, the request refreshes the relevant shards before retrieving the document. Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`_source` (Optional, boolean | string | string[])*: Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. ** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude in the response. ** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -** *`stored_fields` (Optional, string | string[])* -** *`version` (Optional, number)*: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: internal, external, external_gte. +** *`stored_fields` (Optional, string | string[])*: A list of stored fields to return as part of a hit. +** *`version` (Optional, number)*: The version number for concurrency control. It must match the current version of the document for the request to succeed. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. [discrete] === health_report @@ -568,10 +895,127 @@ client.healthReport({ ... }) [discrete] === index -Index a document. -Adds a JSON document to the specified data stream or index and makes it searchable. +Create or update a document in an index. + +Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version. +NOTE: You cannot use this API to send update requests for existing documents in a data stream. + +If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: + +* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege. +* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege. +* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. + +Automatic data stream creation requires a matching index template with data stream enabled. + +NOTE: Replica shards might not all be started when an indexing operation returns successfully. +By default, only the primary is required. Set `wait_for_active_shards` to change this default behavior. + +**Automatically create data streams and indices** + +If the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream. + +If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates. + +NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation. + +If no mapping exists, the index operation creates a dynamic mapping. +By default, new fields and objects are automatically added to the mapping if needed. + +Automatic index creation is controlled by the `action.auto_create_index` setting. +If it is `true`, any index can be created automatically. +You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely. +Specify a list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. +When a list is specified, the default behaviour is to disallow. + +NOTE: The `action.auto_create_index` setting affects the automatic creation of indices only. +It does not affect the creation of data streams. + +**Optimistic concurrency control** + +Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters. +If a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`. + +**Routing** + +By default, shard placement — or routing — is controlled by using a hash of the document's ID value. +For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter. + +When setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself. +This does come at the (very minimal) cost of an additional document parsing pass. +If the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted. + +NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. + +**Distributed** + +The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. +After the primary shard completes the operation, if needed, the update is distributed to applicable replicas. + +**Active shards** + +To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. +If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. +By default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`). +This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. +To alter this behavior per operation, use the `wait_for_active_shards request` parameter. + +Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1). +Specifying a negative value or a number greater than the number of shard copies will throw an error. + +For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). +If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. +This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. +If `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. +This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. +However, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. +The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard. + +It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. +After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. +The `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed. + +**No operation (noop) updates** + +When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. +If this isn't acceptable use the `_update` API with `detect_noop` set to `true`. +The `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source. + +There isn't a definitive rule for when noop updates aren't acceptable. +It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates. + +**Versioning** + +Each indexed document is given a version number. +By default, internal versioning is used that starts at 1 and increments with each update, deletes included. +Optionally, the version number can be set to an external value (for example, if maintained in a database). +To enable this functionality, `version_type` should be set to `external`. +The value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`. + +NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. +If no version is provided, the operation runs without any version checks. + +When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. +If true, the document will be indexed and the new version number used. +If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example: + +---- +PUT my-index-000001/_doc/1?version=2&version_type=external +{ + "user": { + "id": "elkbee" + } +} +---- + +In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. +If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). + +A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. +Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. + {ref}/docs-index_.html[Endpoint documentation] [source,ts] ---- @@ -581,29 +1025,19 @@ client.index({ index }) ==== Arguments * *Request (object):* -** *`index` (string)*: Name of the data stream or index to target. -** *`id` (Optional, string)*: Unique identifier for the document. +** *`index` (string)*: The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. If the target doesn't exist and doesn't match a data stream template, this request creates the index. You can check for existing targets with the resolve index API. +** *`id` (Optional, string)*: A unique identifier for the document. To automatically generate a document ID, use the `POST //_doc/` request format and omit this parameter. ** *`document` (Optional, object)*: A document. ** *`if_primary_term` (Optional, number)*: Only perform the operation if the document has this primary term. ** *`if_seq_no` (Optional, number)*: Only perform the operation if the document has this sequence number. -** *`op_type` (Optional, Enum("index" | "create"))*: Set to create to only index the document if it does not already exist (put if absent). -If a document with the specified `_id` already exists, the indexing operation will fail. -Same as using the `/_create` endpoint. -Valid values: `index`, `create`. -If document id is specified, it defaults to `index`. -Otherwise, it defaults to `create`. -** *`pipeline` (Optional, string)*: ID of the pipeline to use to preprocess incoming documents. -If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. -If a final pipeline is configured it will always run, regardless of the value of this parameter. -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. -Valid values: `true`, `false`, `wait_for`. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`timeout` (Optional, string | -1 | 0)*: Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. -** *`version` (Optional, number)*: Explicit version number for concurrency control. -The specified version must match the current version of the document for the request to succeed. -** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: Specific version type: `external`, `external_gte`. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). +** *`op_type` (Optional, Enum("index" | "create"))*: Set to `create` to only index the document if it does not already exist (put if absent). If a document with the specified `_id` already exists, the indexing operation will fail. The behavior is the same as using the `/_create` endpoint. If a document ID is specified, this paramater defaults to `index`. Otherwise, it defaults to `create`. If the request targets a data stream, an `op_type` of `create` is required. +** *`pipeline` (Optional, string)*: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. If `wait_for`, it waits for a refresh to make this operation visible to search. If `false`, it does nothing with refreshes. +** *`routing` (Optional, string)*: A custom value that is used to route operations to a specific shard. +** *`timeout` (Optional, string | -1 | 0)*: The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur. +** *`version` (Optional, number)*: An explicit version number for concurrency control. It must be a non-negative long number. +** *`version_type` (Optional, Enum("internal" | "external" | "external_gte" | "force"))*: The version type. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. You can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). The default value of `1` means it waits for each primary shard to be active. ** *`require_alias` (Optional, boolean)*: If `true`, the destination must be an index alias. [discrete] @@ -642,22 +1076,13 @@ client.knnSearch({ index, knn }) ==== Arguments * *Request (object):* -** *`index` (string | string[])*: A list of index names to search; -use `_all` or to perform the operation on all indices +** *`index` (string | string[])*: A list of index names to search; use `_all` or to perform the operation on all indices ** *`knn` ({ field, query_vector, k, num_candidates })*: kNN query to execute -** *`_source` (Optional, boolean | { excludes, includes })*: Indicates which source fields are returned for matching documents. These -fields are returned in the hits._source property of the search response. -** *`docvalue_fields` (Optional, { field, format, include_unmapped }[])*: The request returns doc values for field names matching these patterns -in the hits.fields property of the response. Accepts wildcard (*) patterns. -** *`stored_fields` (Optional, string | string[])*: 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. You can pass _source: true to return both source fields -and stored fields in the search response. -** *`fields` (Optional, string | string[])*: The request returns values for field names matching these patterns -in the hits.fields property of the response. Accepts wildcard (*) patterns. -** *`filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type } | { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type }[])*: Query to filter the documents that can match. The kNN search will return the top -`k` documents that also match this filter. The value can be a single query or a -list of queries. If `filter` isn't provided, all documents are allowed to match. +** *`_source` (Optional, boolean | { excludes, includes })*: Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response. +** *`docvalue_fields` (Optional, { field, format, include_unmapped }[])*: The request returns doc values for field names matching these patterns in the hits.fields property of the response. Accepts wildcard (*) patterns. +** *`stored_fields` (Optional, string | string[])*: 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. You can pass _source: true to return both source fields and stored fields in the search response. +** *`fields` (Optional, string | string[])*: The request returns values for field names matching these patterns in the hits.fields property of the response. Accepts wildcard (*) patterns. +** *`filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type } | { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type }[])*: Query to filter the documents that can match. The kNN search will return the top `k` documents that also match this filter. The value can be a single query or a list of queries. If `filter` isn't provided, all documents are allowed to match. ** *`routing` (Optional, string)*: A list of specific routing values [discrete] @@ -680,19 +1105,14 @@ client.mget({ ... }) ** *`index` (Optional, string)*: Name of the index to retrieve documents from when `ids` are specified, or when a document in the `docs` array does not specify an index. ** *`docs` (Optional, { _id, _index, routing, _source, stored_fields, version, version_type }[])*: The documents you want to retrieve. Required if no index is specified in the request URI. ** *`ids` (Optional, string | string[])*: The IDs of the documents you want to retrieve. Allowed when the index is specified in the request URI. -** *`force_synthetic_source` (Optional, boolean)*: Should this request force synthetic _source? -Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. -Fetches with this enabled will be slower the enabling synthetic source natively in the index. +** *`force_synthetic_source` (Optional, boolean)*: Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index. ** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`realtime` (Optional, boolean)*: If `true`, the request is real-time as opposed to near-real-time. ** *`refresh` (Optional, boolean)*: If `true`, the request refreshes relevant shards before retrieving documents. ** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. ** *`_source` (Optional, boolean | string | string[])*: True or false to return the `_source` field or not, or a list of fields to return. -** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. -You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. -** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the `_source_excludes` query parameter. -If the `_source` parameter is `false`, this parameter is ignored. +** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. +** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. ** *`stored_fields` (Optional, string | string[])*: If `true`, retrieves the document fields stored in the index rather than the document `_source`. [discrete] @@ -702,12 +1122,12 @@ Run multiple searches. The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. The structure is as follows: -``` +---- header\n body\n header\n body\n -``` +---- This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node. @@ -731,12 +1151,7 @@ client.msearch({ ... }) ** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. ** *`ignore_throttled` (Optional, boolean)*: If true, concrete, expanded or aliased indices are ignored when frozen. ** *`ignore_unavailable` (Optional, boolean)*: If true, missing or closed indices are not included in the response. -** *`include_named_queries_score` (Optional, 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) -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. +** *`include_named_queries_score` (Optional, 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) 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. ** *`max_concurrent_searches` (Optional, number)*: Maximum number of concurrent searches the multi search API can execute. ** *`max_concurrent_shard_requests` (Optional, number)*: Maximum number of concurrent shard requests that each sub-search request executes per node. ** *`pre_filter_shard_size` (Optional, number)*: 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. 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 i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint. @@ -758,16 +1173,12 @@ client.msearchTemplate({ ... }) ==== Arguments * *Request (object):* -** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases to search. -Supports wildcards (`*`). -To search all data streams and indices, omit this parameter or use `*`. +** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases to search. Supports wildcards (`*`). To search all data streams and indices, omit this parameter or use `*`. ** *`search_templates` (Optional, { allow_no_indices, expand_wildcards, ignore_unavailable, index, preference, request_cache, routing, search_type, ccs_minimize_roundtrips, allow_partial_search_results, ignore_throttled } | { aggregations, collapse, query, explain, ext, stored_fields, docvalue_fields, knn, from, highlight, indices_boost, min_score, post_filter, profile, rescore, script_fields, search_after, size, sort, _source, fields, terminate_after, stats, timeout, track_scores, track_total_hits, version, runtime_mappings, seq_no_primary_term, pit, suggest }[])* ** *`ccs_minimize_roundtrips` (Optional, boolean)*: If `true`, network round-trips are minimized for cross-cluster search requests. ** *`max_concurrent_searches` (Optional, number)*: Maximum number of concurrent searches the API can run. -** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: The type of the search operation. -Available options: `query_then_fetch`, `dfs_query_then_fetch`. -** *`rest_total_hits_as_int` (Optional, boolean)*: If `true`, the response returns `hits.total` as an integer. -If `false`, it returns `hits.total` as an object. +** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: The type of the search operation. Available options: `query_then_fetch`, `dfs_query_then_fetch`. +** *`rest_total_hits_as_int` (Optional, boolean)*: If `true`, the response returns `hits.total` as an integer. If `false`, it returns `hits.total` as an object. ** *`typed_keys` (Optional, boolean)*: If `true`, the response prefixes aggregation and suggester names with their respective types. [discrete] @@ -791,14 +1202,12 @@ client.mtermvectors({ ... }) ** *`index` (Optional, string)*: Name of the index that contains the documents. ** *`docs` (Optional, { _id, _index, routing, _source, stored_fields, version, version_type }[])*: Array of existing or artificial documents. ** *`ids` (Optional, string[])*: Simplified syntax to specify documents by their ID if they're in the same index. -** *`fields` (Optional, string | string[])*: List or wildcard expressions of fields to include in the statistics. -Used as the default list unless a specific field list is provided in the `completion_fields` or `fielddata_fields` parameters. +** *`fields` (Optional, string | string[])*: List or wildcard expressions of fields to include in the statistics. Used as the default list unless a specific field list is provided in the `completion_fields` or `fielddata_fields` parameters. ** *`field_statistics` (Optional, boolean)*: If `true`, the response includes the document count, sum of document frequencies, and sum of total term frequencies. ** *`offsets` (Optional, boolean)*: If `true`, the response includes term offsets. ** *`payloads` (Optional, boolean)*: If `true`, the response includes term payloads. ** *`positions` (Optional, boolean)*: If `true`, the response includes term positions. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`realtime` (Optional, boolean)*: If true, the request is real-time as opposed to near-real-time. ** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. ** *`term_statistics` (Optional, boolean)*: If true, the response includes term frequency and document frequency. @@ -817,7 +1226,33 @@ search requests using the same point in time. For example, if refreshes happen b 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. {ref}/point-in-time-api.html[Endpoint documentation] [source,ts] @@ -829,17 +1264,13 @@ client.openPointInTime({ index, keep_alive }) * *Request (object):* ** *`index` (string | string[])*: A list of index names to open point in time; use `_all` or empty string to perform the operation on all indices -** *`keep_alive` (string | -1 | 0)*: Extends the time to live of the corresponding point in time. -** *`index_filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Allows to filter indices if the provided query rewrites to `match_none` on every shard. +** *`keep_alive` (string | -1 | 0)*: Extend the length of time that the point in time persists. +** *`index_filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Filter indices if the provided query rewrites to `match_none` on every shard. ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. -** *`allow_partial_search_results` (Optional, boolean)*: 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. +** *`preference` (Optional, string)*: The node or shard the operation should be performed on. By default, it is random. +** *`routing` (Optional, string)*: A custom value that is used to route operations to a specific shard. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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. It supports a list of values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. +** *`allow_partial_search_results` (Optional, boolean)*: 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. [discrete] === ping @@ -866,15 +1297,11 @@ client.putScript({ id, script }) ==== Arguments * *Request (object):* -** *`id` (string)*: Identifier for the stored script or search template. -Must be unique within the cluster. +** *`id` (string)*: Identifier for the stored script or search template. Must be unique within the cluster. ** *`script` ({ lang, options, source })*: Contains the script or search template, its parameters, and its language. -** *`context` (Optional, string)*: Context in which the script or search template should run. -To prevent errors, the API immediately compiles the script or template in this context. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. -If no response is received before the timeout expires, the request fails and returns an error. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. -If no response is received before the timeout expires, the request fails and returns an error. +** *`context` (Optional, string)*: Context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] === rank_eval @@ -892,8 +1319,7 @@ client.rankEval({ requests }) * *Request (object):* ** *`requests` ({ id, request, ratings, template_id, params }[])*: A set of typical search requests, together with their provided ratings. -** *`index` (Optional, string | string[])*: List of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported. -To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`. +** *`index` (Optional, string | string[])*: List of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported. To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`. ** *`metric` (Optional, { precision, recall, mean_reciprocal_rank, dcg, expected_reciprocal_rank })*: Definition of the evaluation metric to calculate. ** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. ** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: Whether to expand wildcard expression to concrete indices that are open, closed or both. @@ -903,7 +1329,187 @@ To target all data streams and indices in a cluster, omit this parameter or use [discrete] === reindex Reindex documents. -Copies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself. + +Copy documents from a source to a destination. +You can copy all documents to the destination index or reindex a subset of the documents. +The source can be any existing index, alias, or data stream. +The destination must differ from the source. +For example, you cannot reindex a data stream into itself. + +IMPORTANT: Reindex requires `_source` to be enabled for all documents in the source. +The destination should be configured as wanted before calling the reindex API. +Reindex does not copy the settings from the source or its associated template. +Mappings, shard counts, and replicas, for example, must be configured ahead of time. + +If the Elasticsearch security features are enabled, you must have the following security privileges: + +* The `read` index privilege for the source data stream, index, or alias. +* The `write` index privilege for the destination data stream, index, or index alias. +* To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias. +* If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias. + +If reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting. +Automatic data stream creation requires a matching index template with data stream enabled. + +The `dest` element can be configured like the index API to control optimistic concurrency control. +Omitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID. + +Setting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source. + +Setting `op_type` to `create` causes the reindex API to create only missing documents in the destination. +All existing documents will cause a version conflict. + +IMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`. +A reindex can only add new documents to a destination data stream. +It cannot update existing documents in a destination data stream. + +By default, version conflicts abort the reindex process. +To continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`. +In this case, the response includes a count of the version conflicts that were encountered. +Note that the handling of other error types is unaffected by the `conflicts` property. +Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query. + +NOTE: The reindex API makes no effort to handle ID collisions. +The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior. +Instead, make sure that IDs are unique by using a script. + +**Running reindex asynchronously** + +If the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. +Elasticsearch creates a record of this task as a document at `_tasks/`. + +**Reindex from multiple sources** + +If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources. +That way you can resume the process if there are any errors by removing the partially completed source and starting over. +It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel. + +For example, you can use a bash script like this: + +---- +for index in i1 i2 i3 i4 i5; do + curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{ + "source": { + "index": "'$index'" + }, + "dest": { + "index": "'$index'-reindexed" + } + }' +done +---- + +**Throttling** + +Set `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations. +Requests are throttled by padding each batch with a wait time. +To turn off throttling, set `requests_per_second` to `-1`. + +The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding. +The padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing. +By default the batch size is `1000`, so if `requests_per_second` is set to `500`: + +---- +target_time = 1000 / 500 per second = 2 seconds +wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds +---- + +Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set. +This is "bursty" instead of "smooth". + +**Slicing** + +Reindex supports sliced scroll to parallelize the reindexing process. +This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts. + +NOTE: Reindexing from remote clusters does not support manual or automatic slicing. + +You can slice a reindex request manually by providing a slice ID and total number of slices to each request. +You can also let reindex automatically parallelize by using sliced scroll to slice on `_id`. +The `slices` parameter specifies the number of slices to use. + +Adding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks: + +* You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices. +* Fetching the status of the task for the request with `slices` only contains the status of completed slices. +* These sub-requests are individually addressable for things like cancellation and rethrottling. +* Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally. +* Canceling the request with `slices` will cancel each sub-request. +* Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution. +* Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed. +* Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time. + +If slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices. +If slicing manually or otherwise tuning automatic slicing, use the following guidelines. + +Query performance is most efficient when the number of slices is equal to the number of shards in the index. +If that number is large (for example, `500`), choose a lower number as too many slices will hurt performance. +Setting slices higher than the number of shards generally does not improve efficiency and adds overhead. + +Indexing performance scales linearly across available resources with the number of slices. + +Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources. + +**Modify documents during reindexing** + +Like `_update_by_query`, reindex operations support a script that modifies the document. +Unlike `_update_by_query`, the script is allowed to modify the document's metadata. + +Just as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination. +For example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the `noop` counter in the response body. +Set `ctx.op` to `delete` if your script decides that the document must be deleted from the destination. +The deletion will be reported in the `deleted` counter in the response body. +Setting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`. + +Think of the possibilities! Just be careful; you are able to change: + +* `_id` +* `_index` +* `_version` +* `_routing` + +Setting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request. +It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API. + +**Reindex from remote** + +Reindex supports reindexing from a remote Elasticsearch cluster. +The `host` parameter must contain a scheme, host, port, and optional path. +The `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication. +Be sure to use HTTPS when using basic authentication or the password will be sent in plain text. +There are a range of settings available to configure the behavior of the HTTPS connection. + +When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key. +Remote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting. +It can be set to a comma delimited list of allowed remote host and port combinations. +Scheme is ignored; only the host and port are used. +For example: + +---- +reindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"] +---- + +The list of allowed hosts must be configured on any nodes that will coordinate the reindex. +This feature should work with remote clusters of any version of Elasticsearch. +This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version. + +WARNING: Elasticsearch does not support forward compatibility across major versions. +For example, you cannot reindex from a 7.x cluster into a 6.x cluster. + +To enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification. + +NOTE: Reindexing from remote clusters does not support manual or automatic slicing. + +Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb. +If the remote index includes very large documents you'll need to use a smaller batch size. +It is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field. +Both default to 30 seconds. + +**Configuring SSL parameters** + +Reindex from remote supports configurable SSL settings. +These must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore. +It is not possible to configure SSL in the body of the reindex request. {ref}/docs-reindex.html[Endpoint documentation] [source,ts] @@ -916,19 +1522,16 @@ client.reindex({ dest, source }) * *Request (object):* ** *`dest` ({ index, op_type, pipeline, routing, version_type })*: The destination you are copying to. ** *`source` ({ index, query, remote, size, slice, sort, _source, runtime_mappings })*: The source you are copying from. -** *`conflicts` (Optional, Enum("abort" | "proceed"))*: Set to proceed to continue reindexing even if there are conflicts. -** *`max_docs` (Optional, number)*: The maximum number of documents to reindex. +** *`conflicts` (Optional, Enum("abort" | "proceed"))*: Indicates whether to continue reindexing even when there are conflicts. +** *`max_docs` (Optional, number)*: The maximum number of documents to reindex. By default, all documents are reindexed. If it is a value less then or equal to `scroll_size`, a scroll will not be used to retrieve the results for the operation. If `conflicts` is set to `proceed`, the reindex operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query. ** *`script` (Optional, { source, id, params, lang, options })*: The script to run to update the document source or metadata when reindexing. ** *`size` (Optional, number)* ** *`refresh` (Optional, boolean)*: If `true`, the request refreshes affected shards to make this operation visible to search. -** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. -Defaults to no throttle. -** *`scroll` (Optional, string | -1 | 0)*: Specifies how long a consistent view of the index should be maintained for scrolled search. -** *`slices` (Optional, number | Enum("auto"))*: The number of slices this task should be divided into. -Defaults to 1 slice, meaning the task isn’t sliced into subtasks. -** *`timeout` (Optional, string | -1 | 0)*: Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). +** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. By default, there is no throttle. +** *`scroll` (Optional, string | -1 | 0)*: The period of time that a consistent view of the index should be maintained for scrolled search. +** *`slices` (Optional, number | Enum("auto"))*: The number of slices this task should be divided into. It defaults to one slice, which means the task isn't sliced into subtasks. Reindex supports sliced scroll to parallelize the reindexing process. This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts. NOTE: Reindexing from remote clusters does not support manual or automatic slicing. If set to `auto`, Elasticsearch chooses the number of slices to use. This setting will use one slice per shard, up to a certain limit. If there are multiple sources, it will choose the number of slices based on the index or backing index with the smallest number of shards. +** *`timeout` (Optional, string | -1 | 0)*: The period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards. By default, Elasticsearch waits for at least one minute before failing. The actual wait time could be longer, particularly when multiple waits occur. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. Set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). The default value is one, which means it waits for each primary shard to be active. ** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks until the operation is complete. ** *`require_alias` (Optional, boolean)*: If `true`, the destination must be an index alias. @@ -937,6 +1540,15 @@ Set to `all` or any positive integer up to the total number of shards in the ind Throttle a reindex operation. Change the number of requests per second for a particular reindex operation. +For example: + +---- +POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 +---- + +Rethrottling that speeds up the query takes effect immediately. +Rethrottling that slows down the query will take effect after completing the current batch. +This behavior prevents scroll timeouts. {ref}/docs-reindex.html[Endpoint documentation] [source,ts] @@ -947,8 +1559,8 @@ client.reindexRethrottle({ task_id }) ==== Arguments * *Request (object):* -** *`task_id` (string)*: Identifier for the task. -** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. +** *`task_id` (string)*: The task identifier, which can be found by using the tasks API. +** *`requests_per_second` (Optional, float)*: The throttle for this request in sub-requests per second. It can be either `-1` to turn off throttling or any decimal number like `1.7` or `12` to throttle to that level. [discrete] === render_search_template @@ -965,16 +1577,10 @@ client.renderSearchTemplate({ ... }) ==== Arguments * *Request (object):* -** *`id` (Optional, string)*: ID of the search template to render. -If no `source` is specified, this or the `id` request body parameter is required. +** *`id` (Optional, string)*: ID of the search template to render. If no `source` is specified, this or the `id` request body parameter is required. ** *`file` (Optional, string)* -** *`params` (Optional, Record)*: Key-value pairs used to replace Mustache variables in the template. -The key is the variable name. -The value is the variable value. -** *`source` (Optional, string)*: An inline search template. -Supports the same parameters as the search API's request body. -These parameters also support Mustache variables. -If no `id` or `` is specified, this parameter is required. +** *`params` (Optional, Record)*: Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. +** *`source` (Optional, string)*: An inline search template. Supports the same parameters as the search API's request body. These parameters also support Mustache variables. If no `id` or `` is specified, this parameter is required. [discrete] === scripts_painless_execute @@ -1032,6 +1638,21 @@ 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. + {ref}/search-search.html[Endpoint documentation] [source,ts] ---- @@ -1041,147 +1662,72 @@ client.search({ ... }) ==== Arguments * *Request (object):* -** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases to search. -Supports wildcards (`*`). -To search all data streams and indices, omit this parameter or use `*` or `_all`. +** *`index` (Optional, string | string[])*: A 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`. ** *`aggregations` (Optional, Record)*: Defines the aggregations that are run as part of the search request. ** *`collapse` (Optional, { field, inner_hits, max_concurrent_group_searches, collapse })*: Collapses search results the values of the specified field. -** *`explain` (Optional, boolean)*: If true, returns detailed information about score computation as part of a hit. +** *`explain` (Optional, boolean)*: If `true`, the request returns detailed information about score computation as part of a hit. ** *`ext` (Optional, Record)*: Configuration of search extensions defined by Elasticsearch plugins. -** *`from` (Optional, number)*: Starting document offset. -Needs to be non-negative. -By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. -To page through more hits, use the `search_after` parameter. +** *`from` (Optional, number)*: 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. ** *`highlight` (Optional, { encoder, fields })*: Specifies the highlighter to use for retrieving highlighted snippets from one or more fields in your search results. -** *`track_total_hits` (Optional, boolean | number)*: 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. -** *`indices_boost` (Optional, Record[])*: Boosts the _score of documents from specified indices. -** *`docvalue_fields` (Optional, { field, format, include_unmapped }[])*: Array of wildcard (`*`) patterns. -The request returns doc values for field names matching these patterns in the `hits.fields` property of the response. -** *`knn` (Optional, { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits } | { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits }[])*: Defines the approximate kNN search to run. -** *`rank` (Optional, { rrf })*: Defines the Reciprocal Rank Fusion (RRF) to use. -** *`min_score` (Optional, number)*: Minimum `_score` for matching documents. -Documents with a lower `_score` are not included in the search results. -** *`post_filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Use the `post_filter` parameter to filter search results. -The search hits are filtered after the aggregations are calculated. -A post filter has no impact on the aggregation results. -** *`profile` (Optional, boolean)*: Set to `true` to return detailed timing information about the execution of individual components in a search request. -NOTE: This is a debugging tool and adds significant overhead to search execution. -** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Defines the search definition using the Query DSL. +** *`track_total_hits` (Optional, boolean | number)*: 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. +** *`indices_boost` (Optional, Record[])*: 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. +** *`docvalue_fields` (Optional, { field, format, include_unmapped }[])*: 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. +** *`knn` (Optional, { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits, rescore_vector } | { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits, rescore_vector }[])*: The approximate kNN search to run. +** *`rank` (Optional, { rrf })*: The Reciprocal Rank Fusion (RRF) to use. +** *`min_score` (Optional, number)*: The minimum `_score` for matching documents. Documents with a lower `_score` are not included in the search results. +** *`post_filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Use the `post_filter` parameter to filter search results. The search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results. +** *`profile` (Optional, boolean)*: Set to `true` to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution. +** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: The search definition using the Query DSL. ** *`rescore` (Optional, { window_size, query, learning_to_rank } | { window_size, query, learning_to_rank }[])*: Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the `query` and `post_filter` phases. -** *`retriever` (Optional, { standard, knn, rrf, text_similarity_reranker, rule })*: 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. +** *`retriever` (Optional, { standard, knn, rrf, text_similarity_reranker, rule })*: 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`. ** *`script_fields` (Optional, Record)*: Retrieve a script evaluation (based on different fields) for each hit. ** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: Used to retrieve the next page of hits using a set of sort values from the previous page. -** *`size` (Optional, number)*: 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. -** *`slice` (Optional, { field, id, max })*: Can be used to split a scrolled search into multiple slices that can be consumed independently. +** *`size` (Optional, number)*: 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` property. +** *`slice` (Optional, { field, id, max })*: Split a scrolled search into multiple slices that can be consumed independently. ** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: A list of : pairs. -** *`_source` (Optional, boolean | { excludes, includes })*: Indicates which source fields are returned for matching documents. -These fields are returned in the hits._source property of the search response. -** *`fields` (Optional, { field, format, include_unmapped }[])*: Array of wildcard (`*`) patterns. -The request returns values for field names matching these patterns in the `hits.fields` property of the response. +** *`_source` (Optional, boolean | { excludes, includes })*: 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`. +** *`fields` (Optional, { field, format, include_unmapped }[])*: An array of wildcard (`*`) field patterns. The request returns values for field names matching these patterns in the `hits.fields` property of the response. ** *`suggest` (Optional, { text })*: Defines a suggester that provides similar looking terms based on a provided text. -** *`terminate_after` (Optional, number)*: 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. -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. -If set to `0` (default), the query does not terminate early. -** *`timeout` (Optional, string)*: Specifies the period of time to wait for a response from each shard. -If no response is received before the timeout expires, the request fails and returns an error. -Defaults to no timeout. -** *`track_scores` (Optional, boolean)*: If true, calculate and return document scores, even if the scores are not used for sorting. -** *`version` (Optional, boolean)*: If true, returns document version as part of a hit. -** *`seq_no_primary_term` (Optional, boolean)*: If `true`, returns sequence number and primary term of the last modification of each hit. -** *`stored_fields` (Optional, string | string[])*: 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`. -You can pass `_source: true` to return both source fields and stored fields in the search response. -** *`pit` (Optional, { id, keep_alive })*: Limits the search to a point in time (PIT). -If you provide a PIT, you cannot specify an `` in the request path. -** *`runtime_mappings` (Optional, Record)*: Defines one or more runtime fields in the search request. -These fields take precedence over mapped fields with the same name. -** *`stats` (Optional, string[])*: 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. -** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. -This behavior applies even if the request targets other open indices. -For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. -** *`allow_partial_search_results` (Optional, boolean)*: If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. -** *`analyzer` (Optional, string)*: Analyzer to use for the query string. -This parameter can only be used when the q query string parameter is specified. -** *`analyze_wildcard` (Optional, boolean)*: If true, wildcard and prefix queries are analyzed. -This parameter can only be used when the q query string parameter is specified. -** *`batched_reduce_size` (Optional, number)*: 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. -** *`ccs_minimize_roundtrips` (Optional, boolean)*: If true, network round-trips between the coordinating node and the remote clusters are minimized when executing cross-cluster search (CCS) requests. -** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: AND or OR. -This parameter can only be used when the `q` query string parameter is specified. -** *`df` (Optional, string)*: 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. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. +** *`terminate_after` (Optional, number)*: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. 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. +** *`timeout` (Optional, string)*: 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. +** *`track_scores` (Optional, boolean)*: If `true`, calculate and return document scores, even if the scores are not used for sorting. +** *`version` (Optional, boolean)*: If `true`, the request returns the document version as part of a hit. +** *`seq_no_primary_term` (Optional, boolean)*: If `true`, the request returns sequence number and primary term of the last modification of each hit. +** *`stored_fields` (Optional, string | string[])*: A 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` property defaults to `false`. You can pass `_source: true` to return both source fields and stored fields in the search response. +** *`pit` (Optional, { id, keep_alive })*: Limit the search to a point in time (PIT). If you provide a PIT, you cannot specify an `` in the request path. +** *`runtime_mappings` (Optional, Record)*: One or more runtime fields in the search request. These fields take precedence over mapped fields with the same name. +** *`stats` (Optional, string[])*: 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. +** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. +** *`allow_partial_search_results` (Optional, boolean)*: 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`. +** *`analyzer` (Optional, string)*: The analyzer to use for the query string. This parameter can be used only when the `q` query string parameter is specified. +** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. This parameter can be used only when the `q` query string parameter is specified. +** *`batched_reduce_size` (Optional, number)*: The number of shard results that should be reduced at once on the coordinating node. 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. +** *`ccs_minimize_roundtrips` (Optional, boolean)*: If `true`, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests. +** *`default_operator` (Optional, Enum("and" | "or"))*: 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. +** *`df` (Optional, string)*: 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. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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. It supports a list of values such as `open,hidden`. ** *`ignore_throttled` (Optional, boolean)*: If `true`, concrete, expanded or aliased indices will be ignored when frozen. ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. -** *`include_named_queries_score` (Optional, 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) -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. -** *`lenient` (Optional, 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. -** *`max_concurrent_shard_requests` (Optional, number)*: Defines the number of concurrent shard requests per node this search executes 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. -** *`min_compatible_shard_node` (Optional, string)*: The minimum version of the node that can handle the request -Any handling node with a lower version will fail the request. -** *`preference` (Optional, string)*: 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. -** *`pre_filter_shard_size` (Optional, number)*: 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. -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. -** *`request_cache` (Optional, boolean)*: If `true`, the caching of search results is enabled for requests where `size` is `0`. -Defaults to index level settings. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`scroll` (Optional, string | -1 | 0)*: Period to retain the search context for scrolling. See Scroll search results. -By default, this value cannot exceed `1d` (24 hours). -You can change this limit using the `search.max_keep_alive` cluster-level setting. -** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: How distributed term frequencies are calculated for relevance scoring. -** *`suggest_field` (Optional, string)*: Specifies which field to use for suggestions. -** *`suggest_mode` (Optional, Enum("missing" | "popular" | "always"))*: Specifies the suggest mode. -This parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified. -** *`suggest_size` (Optional, number)*: Number of suggestions to return. -This parameter can only be used when the `suggest_field` and `suggest_text` query string parameters are specified. -** *`suggest_text` (Optional, string)*: 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. +** *`include_named_queries_score` (Optional, boolean)*: 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. +** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the `q` query string parameter is specified. +** *`max_concurrent_shard_requests` (Optional, number)*: 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. +** *`min_compatible_shard_node` (Optional, string)*: The minimum version of the node that can handle the request Any handling node with a lower version will fail the request. +** *`preference` (Optional, string)*: 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. +** *`pre_filter_shard_size` (Optional, number)*: 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. +** *`request_cache` (Optional, boolean)*: If `true`, the caching of search results is enabled for requests where `size` is `0`. It defaults to index level settings. +** *`routing` (Optional, string)*: A custom value that is used to route operations to a specific shard. +** *`scroll` (Optional, string | -1 | 0)*: The period to retain the search context for scrolling. By default, this value cannot exceed `1d` (24 hours). You can change this limit by using the `search.max_keep_alive` cluster-level setting. +** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: Indicates how distributed term frequencies are calculated for relevance scoring. +** *`suggest_field` (Optional, string)*: The field to use for suggestions. +** *`suggest_mode` (Optional, Enum("missing" | "popular" | "always"))*: The suggest mode. This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. +** *`suggest_size` (Optional, number)*: 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_text` (Optional, string)*: The source text for which the suggestions should be returned. This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. ** *`typed_keys` (Optional, boolean)*: If `true`, aggregation and suggester names are be prefixed by their respective types in the response. ** *`rest_total_hits_as_int` (Optional, boolean)*: Indicates whether `hits.total` should be rendered as an integer or an object in the rest search response. -** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. -You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. -If the `_source` parameter is `false`, this parameter is ignored. -** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. -If this parameter is specified, only these source fields are returned. -You can exclude fields from this subset using the `_source_excludes` query parameter. -If the `_source` parameter is `false`, this parameter is ignored. -** *`q` (Optional, string)*: Query in the Lucene query string syntax using query parameter search. -Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing. -** *`force_synthetic_source` (Optional, boolean)*: Should this request force synthetic _source? -Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. -Fetches with this enabled will be slower the enabling synthetic source natively in the index. +** *`_source_excludes` (Optional, string | string[])*: A list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`_source_includes` (Optional, string | string[])*: A list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. +** *`q` (Optional, string)*: 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. +** *`force_synthetic_source` (Optional, boolean)*: Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index. [discrete] === search_mvt @@ -1203,46 +1749,20 @@ client.searchMvt({ index, field, zoom, x, y }) ** *`zoom` (number)*: Zoom level for the vector tile to search ** *`x` (number)*: X coordinate for the vector tile to search ** *`y` (number)*: Y coordinate for the vector tile to search -** *`aggs` (Optional, Record)*: Sub-aggregations for the geotile_grid. - -Supports the following aggregation types: -- avg -- cardinality -- max -- min -- sum -** *`buffer` (Optional, number)*: Size, in pixels, of a clipping buffer outside the tile. This allows renderers -to avoid outline artifacts from geometries that extend past the extent of the tile. -** *`exact_bounds` (Optional, boolean)*: If false, the meta layer’s feature is the bounding box of the tile. -If true, the meta layer’s feature is a bounding box resulting from a -geo_bounds aggregation. The aggregation runs on values that intersect -the // tile with wrap_longitude set to false. The resulting -bounding box may be larger than the vector tile. +** *`aggs` (Optional, Record)*: Sub-aggregations for the geotile_grid. Supports the following aggregation types: - avg - cardinality - max - min - sum +** *`buffer` (Optional, number)*: Size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile. +** *`exact_bounds` (Optional, boolean)*: If false, the meta layer’s feature is the bounding box of the tile. If true, the meta layer’s feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the // tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile. ** *`extent` (Optional, number)*: Size, in pixels, of a side of the tile. Vector tiles are square with equal sides. -** *`fields` (Optional, string | string[])*: Fields to return in the `hits` layer. Supports wildcards (`*`). -This parameter does not support fields with array values. Fields with array -values may return inconsistent results. +** *`fields` (Optional, string | string[])*: Fields to return in the `hits` layer. Supports wildcards (`*`). This parameter does not support fields with array values. Fields with array values may return inconsistent results. ** *`grid_agg` (Optional, Enum("geotile" | "geohex"))*: Aggregation used to create a grid for the `field`. -** *`grid_precision` (Optional, number)*: Additional zoom levels available through the aggs layer. For example, if is 7 -and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results -don’t include the aggs layer. -** *`grid_type` (Optional, Enum("grid" | "point" | "centroid"))*: Determines the geometry type for features in the aggs layer. In the aggs layer, -each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon -of the cells bounding box. If 'point' each feature is a Point that is the centroid -of the cell. +** *`grid_precision` (Optional, number)*: Additional zoom levels available through the aggs layer. For example, if is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don’t include the aggs layer. +** *`grid_type` (Optional, Enum("grid" | "point" | "centroid"))*: Determines the geometry type for features in the aggs layer. In the aggs layer, each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon of the cells bounding box. If 'point' each feature is a Point that is the centroid of the cell. ** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Query DSL used to filter documents for the search. -** *`runtime_mappings` (Optional, Record)*: Defines one or more runtime fields in the search request. These fields take -precedence over mapped fields with the same name. -** *`size` (Optional, number)*: Maximum number of features to return in the hits layer. Accepts 0-10000. -If 0, results don’t include the hits layer. -** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: Sorts features in the hits layer. By default, the API calculates a bounding -box for each feature. It sorts features based on this box’s diagonal length, -from longest to shortest. -** *`track_total_hits` (Optional, boolean | number)*: 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. -** *`with_labels` (Optional, boolean)*: If `true`, the hits and aggs layers will contain additional point features representing -suggested label positions for the original features. +** *`runtime_mappings` (Optional, Record)*: Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name. +** *`size` (Optional, number)*: Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don’t include the hits layer. +** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: Sorts features in the hits layer. By default, the API calculates a bounding box for each feature. It sorts features based on this box’s diagonal length, from longest to shortest. +** *`track_total_hits` (Optional, boolean | number)*: 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. +** *`with_labels` (Optional, boolean)*: If `true`, the hits and aggs layers will contain additional point features representing suggested label positions for the original features. [discrete] === search_shards @@ -1262,17 +1782,12 @@ client.searchShards({ ... }) * *Request (object):* ** *`index` (Optional, string | string[])*: Returns the indices and shards that a search request would be executed against. -** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. -This behavior applies even if the request targets other open indices. -For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. -Valid values are: `all`, `open`, `closed`, `hidden`, `none`. +** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. ** *`local` (Optional, boolean)*: If `true`, the request retrieves information from the local node only. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. [discrete] @@ -1288,33 +1803,20 @@ client.searchTemplate({ ... }) ==== Arguments * *Request (object):* -** *`index` (Optional, string | string[])*: List of data streams, indices, -and aliases to search. Supports wildcards (*). +** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases to search. Supports wildcards (*). ** *`explain` (Optional, boolean)*: If `true`, returns detailed information about score calculation as part of each hit. -** *`id` (Optional, string)*: ID of the search template to use. If no source is specified, -this parameter is required. -** *`params` (Optional, Record)*: Key-value pairs used to replace Mustache variables in the template. -The key is the variable name. -The value is the variable value. +** *`id` (Optional, string)*: ID of the search template to use. If no source is specified, this parameter is required. +** *`params` (Optional, Record)*: Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. ** *`profile` (Optional, boolean)*: If `true`, the query execution is profiled. -** *`source` (Optional, string)*: An inline search template. Supports the same parameters as the search API's -request body. Also supports Mustache variables. If no id is specified, this -parameter is required. -** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. -This behavior applies even if the request targets other open indices. -For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. +** *`source` (Optional, string)*: An inline search template. Supports the same parameters as the search API's request body. Also supports Mustache variables. If no id is specified, this parameter is required. +** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. ** *`ccs_minimize_roundtrips` (Optional, boolean)*: If `true`, network round-trips are minimized for cross-cluster search requests. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. -Valid values are: `all`, `open`, `closed`, `hidden`, `none`. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. ** *`ignore_throttled` (Optional, boolean)*: If `true`, specified concrete, expanded, or aliased indices are not included in the response when throttled. ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`scroll` (Optional, string | -1 | 0)*: Specifies how long a consistent view of the index -should be maintained for scrolled search. +** *`scroll` (Optional, string | -1 | 0)*: Specifies how long a consistent view of the index should be maintained for scrolled search. ** *`search_type` (Optional, Enum("query_then_fetch" | "dfs_query_then_fetch"))*: The type of the search operation. ** *`rest_total_hits_as_int` (Optional, boolean)*: If true, hits.total are rendered as an integer in the response. ** *`typed_keys` (Optional, boolean)*: If `true`, the response prefixes aggregation and suggester names with their respective types. @@ -1369,14 +1871,12 @@ client.termvectors({ index }) ** *`doc` (Optional, object)*: An artificial document (a document not present in the index) for which you want to retrieve term vectors. ** *`filter` (Optional, { max_doc_freq, max_num_terms, max_term_freq, max_word_length, min_doc_freq, min_term_freq, min_word_length })*: Filter terms based on their tf-idf scores. ** *`per_field_analyzer` (Optional, Record)*: Overrides the default per-field analyzer. -** *`fields` (Optional, string | string[])*: List or wildcard expressions of fields to include in the statistics. -Used as the default list unless a specific field list is provided in the `completion_fields` or `fielddata_fields` parameters. +** *`fields` (Optional, string | string[])*: List or wildcard expressions of fields to include in the statistics. Used as the default list unless a specific field list is provided in the `completion_fields` or `fielddata_fields` parameters. ** *`field_statistics` (Optional, boolean)*: If `true`, the response includes the document count, sum of document frequencies, and sum of total term frequencies. ** *`offsets` (Optional, boolean)*: If `true`, the response includes term offsets. ** *`payloads` (Optional, boolean)*: If `true`, the response includes term payloads. ** *`positions` (Optional, boolean)*: If `true`, the response includes term positions. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`realtime` (Optional, boolean)*: If true, the request is real-time as opposed to near-real-time. ** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. ** *`term_statistics` (Optional, boolean)*: If `true`, the response includes term frequency and document frequency. @@ -1386,7 +1886,24 @@ Random by default. [discrete] === update Update a document. -Updates a document by running a script or passing a partial document. + +Update a document by running a script or passing a partial document. + +If the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias. + +The script can update, delete, or skip modifying the document. +The API also supports passing a partial document, which is merged into the existing document. +To fully replace an existing document, use the index API. +This operation: + +* Gets the document (collocated with the shard) from the index. +* Runs the specified script. +* Indexes the result. + +The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation. + +The `_source` field must be enabled to use this API. +In addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp). {ref}/docs-update.html[Endpoint documentation] [source,ts] @@ -1397,35 +1914,26 @@ client.update({ id, index }) ==== Arguments * *Request (object):* -** *`id` (string)*: Document ID -** *`index` (string)*: The name of the index -** *`detect_noop` (Optional, boolean)*: Set to false to disable setting 'result' in the response -to 'noop' if no change to the document occurred. -** *`doc` (Optional, object)*: A partial update to an existing document. -** *`doc_as_upsert` (Optional, boolean)*: Set to true to use the contents of 'doc' as the value of 'upsert' -** *`script` (Optional, { source, id, params, lang, options })*: Script to execute to update the document. -** *`scripted_upsert` (Optional, boolean)*: Set to true to execute the script whether or not the document exists. -** *`_source` (Optional, boolean | { excludes, includes })*: Set to false to disable source retrieval. You can also specify a comma-separated -list of the fields you want to retrieve. -** *`upsert` (Optional, object)*: If the document does not already exist, the contents of 'upsert' are inserted as a -new document. If the document exists, the 'script' is executed. +** *`id` (string)*: A unique identifier for the document to be updated. +** *`index` (string)*: The name of the target index. By default, the index is created automatically if it doesn't exist. +** *`detect_noop` (Optional, boolean)*: If `true`, the `result` in the response is set to `noop` (no operation) when there are no changes to the document. +** *`doc` (Optional, object)*: A partial update to an existing document. If both `doc` and `script` are specified, `doc` is ignored. +** *`doc_as_upsert` (Optional, boolean)*: If `true`, use the contents of 'doc' as the value of 'upsert'. NOTE: Using ingest pipelines with `doc_as_upsert` is not supported. +** *`script` (Optional, { source, id, params, lang, options })*: The script to run to update the document. +** *`scripted_upsert` (Optional, boolean)*: If `true`, run the script whether or not the document exists. +** *`_source` (Optional, boolean | { excludes, includes })*: If `false`, turn off source retrieval. You can also specify a list of the fields you want to retrieve. +** *`upsert` (Optional, object)*: If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run. ** *`if_primary_term` (Optional, number)*: Only perform the operation if the document has this primary term. ** *`if_seq_no` (Optional, number)*: Only perform the operation if the document has this sequence number. ** *`lang` (Optional, string)*: The script language. -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If 'true', Elasticsearch refreshes the affected shards to make this operation -visible to search, if 'wait_for' then wait for a refresh to make this operation -visible to search, if 'false' do nothing with refreshes. -** *`require_alias` (Optional, boolean)*: If true, the destination must be an index alias. -** *`retry_on_conflict` (Optional, number)*: Specify how many times should the operation be retried when a conflict occurs. -** *`routing` (Optional, string)*: Custom value used to route operations to a specific shard. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for dynamic mapping updates and active shards. -This guarantees Elasticsearch waits for at least the timeout before failing. -The actual wait time could be longer, particularly when multiple waits occur. -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operations. -Set to 'all' or any positive integer up to the total number of shards in the index -(number_of_replicas+1). Defaults to 1 meaning the primary shard. -** *`_source_excludes` (Optional, string | string[])*: Specify the source fields you want to exclude. -** *`_source_includes` (Optional, string | string[])*: Specify the source fields you want to retrieve. +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes. +** *`require_alias` (Optional, boolean)*: If `true`, the destination must be an index alias. +** *`retry_on_conflict` (Optional, number)*: The number of times the operation should be retried when a conflict occurs. +** *`routing` (Optional, string)*: A custom value used to route operations to a specific shard. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur. +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of copies of each shard that must be active before proceeding with the operation. Set to 'all' or any positive integer up to the total number of shards in the index (`number_of_replicas`+1). The default value of `1` means it waits for each primary shard to be active. +** *`_source_excludes` (Optional, string | string[])*: The source fields you want to exclude. +** *`_source_includes` (Optional, string | string[])*: The source fields you want to retrieve. [discrete] === update_by_query @@ -1442,33 +1950,23 @@ client.updateByQuery({ index }) ==== Arguments * *Request (object):* -** *`index` (string | string[])*: List of data streams, indices, and aliases to search. -Supports wildcards (`*`). -To search all data streams or indices, omit this parameter or use `*` or `_all`. +** *`index` (string | string[])*: List of data streams, indices, and aliases to search. Supports wildcards (`*`). To search all data streams or indices, omit this parameter or use `*` or `_all`. ** *`max_docs` (Optional, number)*: The maximum number of documents to update. ** *`query` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Specifies the documents to update using the Query DSL. ** *`script` (Optional, { source, id, params, lang, options })*: The script to run to update the document source or metadata when updating. ** *`slice` (Optional, { field, id, max })*: Slice the request manually using the provided slice ID and total number of slices. ** *`conflicts` (Optional, Enum("abort" | "proceed"))*: What to do if update by query hits version conflicts: `abort` or `proceed`. -** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. -This behavior applies even if the request targets other open indices. -For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. +** *`allow_no_indices` (Optional, boolean)*: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. ** *`analyzer` (Optional, string)*: Analyzer to use for the query string. ** *`analyze_wildcard` (Optional, boolean)*: If `true`, wildcard and prefix queries are analyzed. ** *`default_operator` (Optional, Enum("and" | "or"))*: The default operator for query string query: `AND` or `OR`. -** *`df` (Optional, string)*: Field to use as default where no field prefix is given in the query string. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. -Valid values are: `all`, `open`, `closed`, `hidden`, `none`. +** *`df` (Optional, string)*: Field to use as default where no field prefix is given in the query string. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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 a list of values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. ** *`from` (Optional, number)*: Starting offset (default: 0) ** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error if it targets a missing or closed index. ** *`lenient` (Optional, boolean)*: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. -** *`pipeline` (Optional, string)*: ID of the pipeline to use to preprocess incoming documents. -If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. -If a final pipeline is configured it will always run, regardless of the value of this parameter. -** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. -Random by default. +** *`pipeline` (Optional, string)*: ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. +** *`preference` (Optional, string)*: Specifies the node or shard the operation should be performed on. Random by default. ** *`q` (Optional, string)*: Query in the Lucene query string syntax. ** *`refresh` (Optional, boolean)*: If `true`, Elasticsearch refreshes affected shards to make the operation visible to search. ** *`request_cache` (Optional, boolean)*: If `true`, the request cache is used for this request. @@ -1481,18 +1979,11 @@ Random by default. ** *`slices` (Optional, number | Enum("auto"))*: The number of slices this task should be divided into. ** *`sort` (Optional, string[])*: A list of : pairs. ** *`stats` (Optional, string[])*: Specific `tag` of the request for logging and statistical purposes. -** *`terminate_after` (Optional, number)*: 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. -When possible, let Elasticsearch perform early termination automatically. -Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. +** *`terminate_after` (Optional, number)*: 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. 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. ** *`timeout` (Optional, string | -1 | 0)*: Period each update request waits for the following operations: dynamic mapping updates, waiting for active shards. ** *`version` (Optional, boolean)*: If `true`, returns the document version as part of a hit. ** *`version_type` (Optional, boolean)*: Should the document increment the version number (internal) on hit or not (reindex) -** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. -Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). +** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). ** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks until the operation is complete. [discrete] @@ -1622,7 +2113,7 @@ Defaults to 10,000 hits. ** *`indices_boost` (Optional, Record[])*: Boosts the _score of documents from specified indices. ** *`docvalue_fields` (Optional, { field, format, include_unmapped }[])*: Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response. -** *`knn` (Optional, { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits } | { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits }[])*: Defines the approximate kNN search to run. +** *`knn` (Optional, { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits, rescore_vector } | { field, query_vector, query_vector_builder, k, num_candidates, boost, filter, similarity, inner_hits, rescore_vector }[])*: Defines the approximate kNN search to run. ** *`min_score` (Optional, number)*: Minimum _score for matching documents. Documents with a lower _score are not included in the search results. ** *`post_filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })* @@ -1794,10 +2285,11 @@ If no response is received before the timeout expires, the request fails and ret [discrete] ==== aliases Get aliases. -Retrieves the cluster’s index aliases, including filter and routing information. -The API does not return data stream aliases. -CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. +Get the cluster's index aliases, including filter and routing information. +This API does not return data stream aliases. + +IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. {ref}/cat-alias.html[Endpoint documentation] [source,ts] @@ -1810,17 +2302,24 @@ client.cat.aliases({ ... }) * *Request (object):* ** *`name` (Optional, string | string[])*: A list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`. -** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: Whether to expand wildcard expression to concrete indices that are open, closed or both. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: 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. +It supports a list of values, such as `open,hidden`. ** *`local` (Optional, boolean)*: If `true`, the request computes the list of selected nodes from the local cluster state. If `false` the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`master_timeout` (Optional, string | -1 | 0)*: The period to wait for a connection to the master node. +If the master node is not available before the timeout expires, the request fails and returns an error. +To indicated that the request should never timeout, you can set it to `-1`. [discrete] ==== allocation -Provides a snapshot of the number of shards allocated to each data node and their disk space. -IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. +Get shard allocation information. + +Get a snapshot of the number of shards allocated to each data node and their disk space. + +IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. {ref}/cat-allocation.html[Endpoint documentation] [source,ts] @@ -1832,7 +2331,7 @@ client.cat.allocation({ ... }) ==== Arguments * *Request (object):* -** *`node_id` (Optional, string | string[])*: List of node identifiers or names used to limit the returned information. +** *`node_id` (Optional, string | string[])*: A list of node identifiers or names used to limit the returned information. ** *`bytes` (Optional, Enum("b" | "kb" | "mb" | "gb" | "tb" | "pb"))*: The unit used to display byte values. ** *`local` (Optional, boolean)*: If `true`, the request computes the list of selected nodes from the local cluster state. If `false` the list of selected nodes are computed @@ -1843,10 +2342,11 @@ node will send requests for further information to each selected node. [discrete] ==== component_templates Get component templates. -Returns information about component templates in a cluster. + +Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. -CAT APIs are only intended for human consumption using the command line or Kibana console. +IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API. {ref}/cat-component-templates.html[Endpoint documentation] @@ -1859,20 +2359,23 @@ client.cat.componentTemplates({ ... }) ==== Arguments * *Request (object):* -** *`name` (Optional, string)*: The name of the component template. Accepts wildcard expressions. If omitted, all component templates are returned. +** *`name` (Optional, string)*: The name of the component template. +It accepts wildcard expressions. +If it is omitted, all component templates are returned. ** *`local` (Optional, boolean)*: If `true`, the request computes the list of selected nodes from the local cluster state. If `false` the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`master_timeout` (Optional, string | -1 | 0)*: The period to wait for a connection to the master node. [discrete] ==== count Get a document count. -Provides quick access to a document count for a data stream, an index, or an entire cluster. + +Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process. -CAT APIs are only intended for human consumption using the command line or Kibana console. +IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API. {ref}/cat-count.html[Endpoint documentation] @@ -1885,12 +2388,16 @@ client.cat.count({ ... }) ==== Arguments * *Request (object):* -** *`index` (Optional, string | string[])*: List of data streams, indices, and aliases used to limit the request. -Supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. +** *`index` (Optional, string | string[])*: A list of data streams, indices, and aliases used to limit the request. +It supports wildcards (`*`). +To target all data streams and indices, omit this parameter or use `*` or `_all`. [discrete] ==== fielddata -Returns the amount of heap memory currently used by the field data cache on every data node in the cluster. +Get field data cache information. + +Get the amount of heap memory currently used by the field data cache on every data node in the cluster. + IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes stats API. @@ -1910,8 +2417,9 @@ To retrieve all fields, omit this parameter. [discrete] ==== health -Returns the health status of a cluster, similar to the cluster health API. -IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. +Get the cluster health status. + +IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: @@ -1937,7 +2445,8 @@ client.cat.health({ ... }) [discrete] ==== help Get CAT help. -Returns help for the CAT APIs. + +Get help for the CAT APIs. {ref}/cat.html[Endpoint documentation] [source,ts] @@ -1949,7 +2458,8 @@ client.cat.help() [discrete] ==== indices Get index information. -Returns high-level information about indices in a cluster, including backing indices for data streams. + +Get high-level information about indices in a cluster, including backing indices for data streams. Use this request to get the following information for each index in a cluster: - shard count @@ -1986,7 +2496,10 @@ Supports wildcards (`*`). To target all data streams and indices, omit this para [discrete] ==== master -Returns information about the master node, including the ID, bound IP address, and name. +Get master node information. + +Get information about the master node, including the ID, bound IP address, and name. + IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. {ref}/cat-master.html[Endpoint documentation] @@ -2008,9 +2521,10 @@ node will send requests for further information to each selected node. [discrete] ==== ml_data_frame_analytics Get data frame analytics jobs. -Returns configuration and usage information about data frame analytics jobs. -CAT APIs are only intended for human consumption using the Kibana +Get configuration and usage information about data frame analytics jobs. + +IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API. @@ -2035,12 +2549,13 @@ response. [discrete] ==== ml_datafeeds Get datafeeds. -Returns configuration and usage information about datafeeds. + +Get configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. -CAT APIs are only intended for human consumption using the Kibana +IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API. @@ -2071,12 +2586,13 @@ partial matches. [discrete] ==== ml_jobs Get anomaly detection jobs. -Returns configuration and usage information for anomaly detection jobs. + +Get configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. -CAT APIs are only intended for human consumption using the Kibana +IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get anomaly detection job statistics API. @@ -2108,9 +2624,10 @@ matches. [discrete] ==== ml_trained_models Get trained models. -Returns configuration and usage information about inference trained models. -CAT APIs are only intended for human consumption using the Kibana +Get configuration and usage information about inference trained models. + +IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API. @@ -2137,7 +2654,9 @@ If `false`, the API returns a 404 status code when there are no matches or only [discrete] ==== nodeattrs -Returns information about custom node attributes. +Get node attribute information. + +Get information about custom node attributes. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. {ref}/cat-nodeattrs.html[Endpoint documentation] @@ -2158,7 +2677,9 @@ node will send requests for further information to each selected node. [discrete] ==== nodes -Returns information about the nodes in a cluster. +Get node information. + +Get information about the nodes in a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. {ref}/cat-nodes.html[Endpoint documentation] @@ -2179,7 +2700,9 @@ client.cat.nodes({ ... }) [discrete] ==== pending_tasks -Returns cluster-level changes that have not yet been executed. +Get pending task information. + +Get information about cluster-level changes that have not yet taken effect. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API. {ref}/cat-pending-tasks.html[Endpoint documentation] @@ -2201,7 +2724,9 @@ node will send requests for further information to each selected node. [discrete] ==== plugins -Returns a list of plugins running on each node of a cluster. +Get plugin information. + +Get a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. {ref}/cat-plugins.html[Endpoint documentation] @@ -2223,7 +2748,9 @@ node will send requests for further information to each selected node. [discrete] ==== recovery -Returns information about ongoing and completed shard recoveries. +Get shard recovery information. + +Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API. @@ -2247,7 +2774,9 @@ Supports wildcards (`*`). To target all data streams and indices, omit this para [discrete] ==== repositories -Returns the snapshot repositories for a cluster. +Get snapshot repository information. + +Get a list of snapshot repositories for a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API. {ref}/cat-repositories.html[Endpoint documentation] @@ -2268,7 +2797,9 @@ node will send requests for further information to each selected node. [discrete] ==== segments -Returns low-level information about the Lucene segments in index shards. +Get segment information. + +Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API. @@ -2294,7 +2825,9 @@ node will send requests for further information to each selected node. [discrete] ==== shards -Returns information about the shards in a cluster. +Get shard information. + +Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. @@ -2317,7 +2850,9 @@ To target all data streams and indices, omit this parameter or use `*` or `_all` [discrete] ==== snapshots -Returns information about the snapshots stored in one or more repositories. +Get snapshot information. + +Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API. @@ -2341,7 +2876,9 @@ If any repository fails during the request, Elasticsearch returns an error. [discrete] ==== tasks -Returns information about tasks currently executing in the cluster. +Get task information. + +Get information about tasks currently running in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API. {ref}/tasks.html[Endpoint documentation] @@ -2365,7 +2902,9 @@ If no response is received before the timeout expires, the request fails and ret [discrete] ==== templates -Returns information about index templates in a cluster. +Get index template information. + +Get information about the index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get index template API. @@ -2389,7 +2928,9 @@ node will send requests for further information to each selected node. [discrete] ==== thread_pool -Returns thread pool statistics for each node in a cluster. +Get thread pool statistics. + +Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. @@ -2414,8 +2955,9 @@ node will send requests for further information to each selected node. [discrete] ==== transforms -Get transforms. -Returns configuration and usage information about transforms. +Get transform information. + +Get configuration and usage information about transforms. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For @@ -2460,6 +3002,7 @@ client.ccr.deleteAutoFollowPattern({ name }) * *Request (object):* ** *`name` (string)*: The name of the auto follow pattern. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== follow @@ -2497,6 +3040,7 @@ be deferred until the total bytes of queued operations goes below the limit. When the timeout has elapsed, the poll for operations will return to the follower so that it can update some statistics. Then the follower will immediately attempt to read from the leader again. ** *`settings` (Optional, { index, mode, routing_path, soft_deletes, sort, number_of_shards, number_of_replicas, number_of_routing_shards, check_on_startup, codec, routing_partition_size, load_fixed_bitset_filters_eagerly, hidden, auto_expand_replicas, merge, search, refresh_interval, max_result_window, max_inner_result_window, max_rescore_window, max_docvalue_fields_search, max_script_fields, max_ngram_diff, max_shingle_diff, blocks, max_refresh_listeners, analyze, highlight, max_terms_count, max_regex_length, routing, gc_deletes, default_pipeline, final_pipeline, lifecycle, provided_name, creation_date, creation_date_string, uuid, version, verified_before_close, format, max_slices_per_scroll, translog, query_string, priority, top_metrics_max_size, analysis, settings, time_series, queries, similarity, mapping, indexing.slowlog, indexing_pressure, store })*: Settings to override from the leader index. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. ** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: Specifies the number of shards to wait on being active before responding. This defaults to waiting on none of the shards to be active. A shard must be restored from the leader index before being active. Restoring a follower shard requires transferring all the @@ -2519,6 +3063,7 @@ client.ccr.followInfo({ index }) * *Request (object):* ** *`index` (string | string[])*: A list of index patterns; use `_all` to perform the operation on all indices +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== follow_stats @@ -2537,6 +3082,7 @@ client.ccr.followStats({ index }) * *Request (object):* ** *`index` (string | string[])*: A list of index patterns; use `_all` to perform the operation on all indices +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== forget_follower @@ -2568,6 +3114,7 @@ client.ccr.forgetFollower({ index }) ** *`follower_index` (Optional, string)* ** *`follower_index_uuid` (Optional, string)* ** *`leader_remote_cluster` (Optional, string)* +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== get_auto_follow_pattern @@ -2585,6 +3132,7 @@ client.ccr.getAutoFollowPattern({ ... }) * *Request (object):* ** *`name` (Optional, string)*: Specifies the auto-follow pattern collection that you want to retrieve. If you do not specify a name, the API returns information for all collections. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== pause_auto_follow_pattern @@ -2608,6 +3156,7 @@ client.ccr.pauseAutoFollowPattern({ name }) * *Request (object):* ** *`name` (string)*: The name of the auto follow pattern that should pause discovering new indices to follow. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== pause_follow @@ -2628,6 +3177,7 @@ client.ccr.pauseFollow({ index }) * *Request (object):* ** *`index` (string)*: The name of the follower index that should pause following its leader index. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== put_auto_follow_pattern @@ -2665,6 +3215,7 @@ client.ccr.putAutoFollowPattern({ name, remote_cluster }) ** *`max_write_buffer_size` (Optional, number | string)*: The maximum total bytes of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the total bytes of queued operations goes below the limit. ** *`max_write_request_operation_count` (Optional, number)*: The maximum number of operations per bulk write request executed on the follower. ** *`max_write_request_size` (Optional, number | string)*: The maximum total bytes of operations per bulk write request executed on the follower. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== resume_auto_follow_pattern @@ -2684,6 +3235,7 @@ client.ccr.resumeAutoFollowPattern({ name }) * *Request (object):* ** *`name` (string)*: The name of the auto follow pattern to resume discovering new indices to follow. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== resume_follow @@ -2714,6 +3266,7 @@ client.ccr.resumeFollow({ index }) ** *`max_write_request_operation_count` (Optional, number)* ** *`max_write_request_size` (Optional, string)* ** *`read_poll_timeout` (Optional, string | -1 | 0)* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== stats @@ -2723,9 +3276,15 @@ This API returns stats about auto-following and the same shard-level stats as th {ref}/ccr-get-stats.html[Endpoint documentation] [source,ts] ---- -client.ccr.stats() +client.ccr.stats({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== unfollow @@ -2747,6 +3306,7 @@ client.ccr.unfollow({ index }) * *Request (object):* ** *`index` (string)*: The name of the follower index that should be turned into a regular index. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] === cluster @@ -2774,6 +3334,7 @@ client.cluster.allocationExplain({ ... }) ** *`shard` (Optional, number)*: Specifies the ID of the shard that you would like an explanation for. ** *`include_disk_info` (Optional, boolean)*: If true, returns information about disk usage and shard sizes. ** *`include_yes_decisions` (Optional, boolean)*: If true, returns YES decisions in explanation. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== delete_component_template @@ -2811,6 +3372,7 @@ client.cluster.deleteVotingConfigExclusions({ ... }) ==== Arguments * *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. ** *`wait_for_removal` (Optional, boolean)*: Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from @@ -2999,6 +3561,7 @@ client.cluster.postVotingConfigExclusions({ ... }) voting configuration. If specified, you may not also specify node_ids. ** *`node_ids` (Optional, string | string[])*: A list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify node_names. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. ** *`timeout` (Optional, string | -1 | 0)*: When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning. If the timeout expires before the appropriate condition @@ -3880,6 +4443,7 @@ client.enrich.deletePolicy({ name }) * *Request (object):* ** *`name` (string)*: Enrich policy to delete. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== execute_policy @@ -3897,6 +4461,7 @@ client.enrich.executePolicy({ name }) * *Request (object):* ** *`name` (string)*: Enrich policy to execute. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. ** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks other enrich policy execution requests until complete. [discrete] @@ -3916,6 +4481,7 @@ client.enrich.getPolicy({ ... }) * *Request (object):* ** *`name` (Optional, string | string[])*: List of enrich policy names used to limit the request. To return information for all enrich policies, omit this parameter. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== put_policy @@ -3936,6 +4502,7 @@ client.enrich.putPolicy({ name }) ** *`geo_match` (Optional, { enrich_fields, indices, match_field, query, name, elasticsearch_version })*: Matches enrich data to incoming documents based on a `geo_shape` query. ** *`match` (Optional, { enrich_fields, indices, match_field, query, name, elasticsearch_version })*: Matches enrich data to incoming documents based on a `term` query. ** *`range` (Optional, { enrich_fields, indices, match_field, query, name, elasticsearch_version })*: Matches a number, date, or IP address in incoming documents to a range in the enrich index based on a `term` query. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== stats @@ -3945,9 +4512,14 @@ Returns enrich coordinator statistics and information about enrich policies that {ref}/enrich-stats-api.html[Endpoint documentation] [source,ts] ---- -client.enrich.stats() +client.enrich.stats({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] === eql @@ -4053,25 +4625,100 @@ parameter to get a smaller or larger set of samples. To retrieve more than one s === esql [discrete] ==== async_query -Executes an ESQL request asynchronously +Run an async ES|QL query. +Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available. + +The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties. {ref}/esql-async-query-api.html[Endpoint documentation] [source,ts] ---- -client.esql.asyncQuery() +client.esql.asyncQuery({ query }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`query` (string)*: The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results. +** *`columnar` (Optional, boolean)*: By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results. +** *`filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. +** *`locale` (Optional, string)* +** *`params` (Optional, number | number | string | boolean | null | User-defined value[])*: To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters. +** *`profile` (Optional, boolean)*: If provided and `true` the response will include an extra `profile` object +with information on how the query was executed. This information is for human debugging +and its format can change at any time but it can give some insight into the performance +of each part of the query. +** *`tables` (Optional, Record>)*: Tables to use with the LOOKUP operation. The top level key is the table +name and the next level key is the column name. +** *`delimiter` (Optional, string)*: The character to use between values within a CSV row. +It is valid only for the CSV format. +** *`drop_null_columns` (Optional, boolean)*: Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results. +If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns. +** *`format` (Optional, Enum("csv" | "json" | "tsv" | "txt" | "yaml" | "cbor" | "smile" | "arrow"))*: A short version of the Accept header, for example `json` or `yaml`. +** *`keep_alive` (Optional, string | -1 | 0)*: The period for which the query and its results are stored in the cluster. +The default period is five days. +When this period expires, the query and its results are deleted, even if the query is still ongoing. +If the `keep_on_completion` parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the `wait_for_completion_timeout` parameter, regardless of this value. +** *`keep_on_completion` (Optional, boolean)*: Indicates whether the query and its results are stored in the cluster. +If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the `wait_for_completion_timeout` parameter. +** *`wait_for_completion_timeout` (Optional, string | -1 | 0)*: The period to wait for the request to finish. +By default, the request waits for 1 second for the query results. +If the query completes during this period, results are returned +Otherwise, a query ID is returned that can later be used to retrieve the results. + +[discrete] +==== async_query_delete +Delete an async ES|QL query. +If the query is still running, it is cancelled. +Otherwise, the stored results are deleted. + +If the Elasticsearch security features are enabled, only the following users can use this API to delete a query: + +* The authenticated user that submitted the original query request +* Users with the `cancel_task` cluster privilege + +{ref}/esql-async-query-delete-api.html[Endpoint documentation] +[source,ts] +---- +client.esql.asyncQueryDelete({ id }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`id` (string)*: The unique identifier of the query. +A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. +A query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`. [discrete] ==== async_query_get -Retrieves the results of a previously submitted async query request given its ID. +Get async ES|QL query results. +Get the current status and available results or stored results for an ES|QL asynchronous query. +If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API. {ref}/esql-async-query-get-api.html[Endpoint documentation] [source,ts] ---- -client.esql.asyncQueryGet() +client.esql.asyncQueryGet({ id }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`id` (string)*: The unique identifier of the query. +A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. +A query ID is also provided when the request was submitted with the `keep_on_completion` parameter set to `true`. +** *`drop_null_columns` (Optional, boolean)*: Indicates whether columns that are entirely `null` will be removed from the `columns` and `values` portion of the results. +If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns. +** *`keep_alive` (Optional, string | -1 | 0)*: The period for which the query and its results are stored in the cluster. +When this period expires, the query and its results are deleted, even if the query is still ongoing. +** *`wait_for_completion_timeout` (Optional, string | -1 | 0)*: The period to wait for the request to finish. +By default, the request waits for complete query results. +If the request completes during the period specified in this parameter, complete query results are returned. +Otherwise, the response returns an `is_running` value of `true` and no results. [discrete] ==== query @@ -4122,9 +4769,14 @@ In order for a feature state to be listed in this API and recognized as a valid {ref}/get-features-api.html[Endpoint documentation] [source,ts] ---- -client.features.getFeatures() +client.features.getFeatures({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== reset_features @@ -4149,9 +4801,14 @@ IMPORTANT: The features installed on the node you submit this request to are the {ref}/modules-snapshots.html[Endpoint documentation] [source,ts] ---- -client.features.resetFeatures() +client.features.resetFeatures({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] === fleet @@ -4391,7 +5048,6 @@ To target all data streams and indices, use `*` or `_all`. ** *`only_errors` (Optional, boolean)*: Filters the returned indices to only indices that are managed by ILM and are in an error state, either due to an encountering an error while executing the policy, or attempting to use a policy that does not exist. ** *`only_managed` (Optional, boolean)*: Filters the returned indices to only indices that are managed by ILM. ** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== get_lifecycle @@ -4433,9 +5089,9 @@ Using node roles enables ILM to automatically move the indices between data tier Migrating away from custom node attributes routing can be manually performed. This API provides an automated way of performing three out of the four manual steps listed in the migration guide: -1. Stop setting the custom hot attribute on new indices. -2. Remove custom allocation settings from existing ILM policies. -3. Replace custom allocation settings from existing indices with the corresponding tier preference. +. Stop setting the custom hot attribute on new indices. +. Remove custom allocation settings from existing ILM policies. +. Replace custom allocation settings from existing indices with the corresponding tier preference. ILM must be stopped before performing the migration. Use the stop ILM and get ILM status APIs to wait until the reported operation mode is `STOPPED`. @@ -4561,8 +5217,8 @@ client.ilm.start({ ... }) ==== Arguments * *Request (object):* -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`timeout` (Optional, string | -1 | 0)*: Explicit operation timeout +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== stop @@ -4583,8 +5239,8 @@ client.ilm.stop({ ... }) ==== Arguments * *Request (object):* -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`timeout` (Optional, string | -1 | 0)*: Explicit operation timeout +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] === indices @@ -4648,6 +5304,22 @@ If specified, the `analyzer` parameter overrides this value. If an array of strings is provided, it is analyzed as a multi-value field. ** *`tokenizer` (Optional, string | { type, tokenize_on_chars, max_token_length } | { type, max_token_length } | { type, custom_token_chars, max_gram, min_gram, token_chars } | { type, buffer_size } | { type } | { type } | { type, custom_token_chars, max_gram, min_gram, token_chars } | { type, buffer_size, delimiter, replacement, reverse, skip } | { type, flags, group, pattern } | { type, pattern } | { type, pattern } | { type, max_token_length } | { type } | { type, max_token_length } | { type, max_token_length } | { type, rule_files } | { type, discard_punctuation, mode, nbest_cost, nbest_examples, user_dictionary, user_dictionary_rules, discard_compound_token } | { type, decompound_mode, discard_punctuation, user_dictionary, user_dictionary_rules })*: Tokenizer to use to convert text into tokens. +[discrete] +==== cancel_migrate_reindex +Cancel a migration reindex operation. + +Cancel a migration reindex attempt for a data stream or index. +[source,ts] +---- +client.indices.cancelMigrateReindex({ index }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`index` (string | string[])*: The index or data stream name + [discrete] ==== clear_cache Clear the cache. @@ -4871,6 +5543,24 @@ Cannot be longer than 255 bytes. Multi-byte characters count towards this limit ** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. ** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. +[discrete] +==== create_from +Create an index from a source index. + +Copy the mappings and settings from the source index to a destination index while allowing request settings and mappings to override the source values. +[source,ts] +---- +client.indices.createFrom({ source, dest }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`source` (string)*: The source index or data stream name +** *`dest` (string)*: The destination index or data stream name +** *`create_from` (Optional, { mappings_override, settings_override, remove_index_blocks })* + [discrete] ==== data_streams_stats Get data stream stats. @@ -5239,10 +5929,6 @@ If the request can target data streams, this argument determines whether wildcar Supports a list of values, such as `open,hidden`. ** *`ignore_unavailable` (Optional, boolean)*: If `true`, missing or closed indices are not included in the response. ** *`fields` (Optional, string | string[])*: List or wildcard expressions of fields to include in the statistics. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. -If no response is received before the timeout expires, the request fails and returns an error. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. -If no response is received before the timeout expires, the request fails and returns an error. ** *`wait_for_active_shards` (Optional, number | Enum("all" | "index-setting"))*: The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). @@ -5336,9 +6022,9 @@ Once an index receive no more writes, its shards can be force-merged to a single This can be a good idea because single-segment shards can sometimes use simpler and more efficient data structures to perform searches. For example: -``` +---- POST /.ds-my-data-stream-2099.03.07-000001/_forcemerge?max_num_segments=1 -``` +---- {ref}/indices-forcemerge.html[Endpoint documentation] [source,ts] @@ -5394,6 +6080,8 @@ such as open,hidden. ==== get_alias Get aliases. Retrieves information for one or more data stream or index aliases. + +{ref}/indices-get-alias.html[Endpoint documentation] [source,ts] ---- client.indices.getAlias({ ... }) @@ -5560,6 +6248,22 @@ Valid values are: `all`, `open`, `closed`, `hidden`, `none`. ** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. +[discrete] +==== get_migrate_reindex_status +Get the migration reindexing status. + +Get the status of a migration reindex attempt for a data stream or index. +[source,ts] +---- +client.indices.getMigrateReindexStatus({ index }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`index` (string | string[])*: The index or data stream name. + [discrete] ==== get_settings Get index settings. @@ -5622,6 +6326,24 @@ To return all index templates, omit this parameter or use a value of `_all` or ` ** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. +[discrete] +==== migrate_reindex +Reindex legacy backing indices. + +Reindex all legacy backing indices for a data stream. +This operation occurs in a persistent task. +The persistent task ID is returned immediately and the reindexing work is completed in that task. +[source,ts] +---- +client.indices.migrateReindex({ ... }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`reindex` (Optional, { mode, source })* + [discrete] ==== migrate_to_data_stream Convert an index alias to a data stream. @@ -5945,7 +6667,7 @@ a new date field is added instead of string. not used at all by Elasticsearch, but can be used to store application-specific metadata. ** *`numeric_detection` (Optional, boolean)*: Automatically map strings into numeric data types for all fields. -** *`properties` (Optional, Record)*: Mapping for a field. For new fields, this mapping can include: +** *`properties` (Optional, Record)*: Mapping for a field. For new fields, this mapping can include: - Field name - Field data type @@ -6530,9 +7252,9 @@ Split an index into a new index with more primary shards. You can do make an index read-only with the following request using the add index block API: -``` +---- PUT /my_source_index/_block/write -``` +---- The current write index on a data stream cannot be split. In order to split the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be split. @@ -6756,50 +7478,116 @@ client.inference.inference({ inference_id, input }) * *Request (object):* ** *`inference_id` (string)*: The inference Id -** *`input` (string | string[])*: Inference input. -Either a string or an array of strings. +** *`input` (string | string[])*: Inference input. +Either a string or an array of strings. +** *`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion"))*: The task type +** *`query` (Optional, string)*: Query input, required for rerank task. +Not required for other tasks. +** *`task_settings` (Optional, User-defined value)*: Optional task settings +** *`timeout` (Optional, string | -1 | 0)*: Specifies the amount of time to wait for the inference request to complete. + +[discrete] +==== put +Create an inference endpoint. +When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. +After creating the endpoint, wait for the model deployment to complete before using it. +To verify the deployment status, use the get trained model statistics API. +Look for `"state": "fully_allocated"` in the response and ensure that the `"allocation_count"` matches the `"target_allocation_count"`. +Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources. + +IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. +For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. +However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs. + +{ref}/put-inference-api.html[Endpoint documentation] +[source,ts] +---- +client.inference.put({ inference_id }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`inference_id` (string)*: The inference Id +** *`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion"))*: The task type +** *`inference_config` (Optional, { service, service_settings, task_settings })* + +[discrete] +==== stream_inference +Perform streaming inference. +Get real-time responses for completion tasks by delivering answers incrementally, reducing response times during computation. +This API works only with the completion task type. + +IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs. + +This API requires the `monitor_inference` cluster privilege (the built-in `inference_admin` and `inference_user` roles grant this privilege). You must use a client that supports streaming. + +{ref}/stream-inference-api.html[Endpoint documentation] +[source,ts] +---- +client.inference.streamInference({ inference_id, input }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`inference_id` (string)*: The unique identifier for the inference endpoint. +** *`input` (string | string[])*: The text on which you want to perform the inference task. +It can be a single string or an array. + +NOTE: Inference endpoints for the completion task type currently only support a single string as input. +** *`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion"))*: The type of task that the model performs. + +[discrete] +==== unified_inference +Perform inference on the service using the Unified Schema +[source,ts] +---- +client.inference.unifiedInference({ inference_id, messages }) +---- + +[discrete] +==== Arguments + +* *Request (object):* +** *`inference_id` (string)*: The inference Id +** *`messages` ({ content, role, tool_call_id, tool_calls }[])*: A list of objects representing the conversation. ** *`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion"))*: The task type -** *`query` (Optional, string)*: Query input, required for rerank task. -Not required for other tasks. -** *`task_settings` (Optional, User-defined value)*: Optional task settings +** *`model` (Optional, string)*: The ID of the model to use. +** *`max_completion_tokens` (Optional, number)*: The upper bound limit for the number of tokens that can be generated for a completion request. +** *`stop` (Optional, string[])*: A sequence of strings to control when the model should stop generating additional tokens. +** *`temperature` (Optional, float)*: The sampling temperature to use. +** *`tool_choice` (Optional, string | { type, function })*: Controls which tool is called by the model. +** *`tools` (Optional, { type, function }[])*: A list of tools that the model can call. +** *`top_p` (Optional, float)*: Nucleus sampling, an alternative to sampling with temperature. ** *`timeout` (Optional, string | -1 | 0)*: Specifies the amount of time to wait for the inference request to complete. [discrete] -==== put -Create an inference endpoint. -When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. -After creating the endpoint, wait for the model deployment to complete before using it. -To verify the deployment status, use the get trained model statistics API. -Look for `"state": "fully_allocated"` in the response and ensure that the `"allocation_count"` matches the `"target_allocation_count"`. -Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources. +==== update +Update an inference endpoint. -IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. +Modify `task_settings`, secrets (within `service_settings`), or `num_allocations` for an inference endpoint, depending on the specific endpoint service and `task_type`. + +IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs. -{ref}/put-inference-api.html[Endpoint documentation] +{ref}/update-inference-api.html[Endpoint documentation] [source,ts] ---- -client.inference.put({ inference_id }) +client.inference.update({ inference_id }) ---- [discrete] ==== Arguments * *Request (object):* -** *`inference_id` (string)*: The inference Id -** *`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion"))*: The task type +** *`inference_id` (string)*: The unique identifier of the inference endpoint. +** *`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion"))*: The type of inference task that the model performs. ** *`inference_config` (Optional, { service, service_settings, task_settings })* -[discrete] -==== stream_inference -Perform streaming inference -[source,ts] ----- -client.inference.streamInference() ----- - - [discrete] === ingest [discrete] @@ -6896,8 +7684,6 @@ client.ingest.getGeoipDatabase({ ... }) ** *`id` (Optional, string | string[])*: List of database configuration IDs to retrieve. Wildcard (`*`) expressions are supported. To get all database configurations, omit this parameter or use `*`. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. -If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== get_ip_location_database @@ -7066,9 +7852,15 @@ If the operator privileges feature is enabled, only operator users can use this {ref}/delete-license.html[Endpoint documentation] [source,ts] ---- -client.license.delete() +client.license.delete({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== get @@ -7138,6 +7930,8 @@ client.license.post({ ... }) ** *`license` (Optional, { expiry_date_in_millis, issue_date_in_millis, start_date_in_millis, issued_to, issuer, max_nodes, max_resource_units, signature, type, uid })* ** *`licenses` (Optional, { expiry_date_in_millis, issue_date_in_millis, start_date_in_millis, issued_to, issuer, max_nodes, max_resource_units, signature, type, uid }[])*: A sequence of one or more JSON documents containing the license information. ** *`acknowledge` (Optional, boolean)*: Specifies whether you acknowledge the license changes. +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== post_start_basic @@ -7162,6 +7956,8 @@ client.license.postStartBasic({ ... }) * *Request (object):* ** *`acknowledge` (Optional, boolean)*: whether the user has acknowledged acknowledge messages (default: false) +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== post_start_trial @@ -7185,6 +7981,7 @@ client.license.postStartTrial({ ... }) * *Request (object):* ** *`acknowledge` (Optional, boolean)*: whether the user has acknowledged acknowledge messages (default: false) ** *`type_query_string` (Optional, string)* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] === logstash @@ -7577,6 +8374,7 @@ client.ml.deleteTrainedModel({ model_id }) * *Request (object):* ** *`model_id` (string)*: The unique identifier of the trained model. ** *`force` (Optional, boolean)*: Forcefully deletes a trained model that is referenced by ingest pipelines or has a started deployment. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== delete_trained_model_alias @@ -7871,10 +8669,10 @@ option, the API returns information for the first hundred data frame analytics jobs. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no data frame analytics +. Contains wildcard expressions and there are no data frame analytics jobs that match. -2. Contains the `_all` string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains the `_all` string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. The default value returns an empty data_frame_analytics array when there are no matches and the subset of results when there are partial matches. @@ -7905,10 +8703,10 @@ option, the API returns information for the first hundred data frame analytics jobs. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no data frame analytics +. Contains wildcard expressions and there are no data frame analytics jobs that match. -2. Contains the `_all` string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains the `_all` string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. The default value returns an empty data_frame_analytics array when there are no matches and the subset of results when there are partial matches. @@ -7943,9 +8741,9 @@ wildcard expression. If you do not specify one of these options, the API returns information about all datafeeds. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no datafeeds that match. -2. Contains the `_all` string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains wildcard expressions and there are no datafeeds that match. +. Contains the `_all` string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. The default value is `true`, which returns an empty `datafeeds` array when there are no matches and the subset of results when there are @@ -7976,9 +8774,9 @@ wildcard expression. If you do not specify one of these options, the API returns information about all datafeeds. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no datafeeds that match. -2. Contains the `_all` string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains wildcard expressions and there are no datafeeds that match. +. Contains the `_all` string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. The default value is `true`, which returns an empty `datafeeds` array when there are no matches and the subset of results when there are @@ -8062,9 +8860,9 @@ you do not specify one of these options, the API returns information for all anomaly detection jobs. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no jobs that match. -2. Contains the _all string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains wildcard expressions and there are no jobs that match. +. Contains the _all string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. If `true`, the API returns an empty `jobs` array when there are no matches and the subset of results when there are partial @@ -8094,9 +8892,9 @@ group name, or a wildcard expression. If you do not specify one of these options, the API returns information for all anomaly detection jobs. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no jobs that match. -2. Contains the _all string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains wildcard expressions and there are no jobs that match. +. Contains the _all string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. The default value is `true`, which returns an empty `jobs` array when there are no matches and the subset of results when there are partial @@ -8124,8 +8922,6 @@ client.ml.getMemoryStats({ ... }) * *Request (object):* ** *`node_id` (Optional, string)*: The names of particular nodes in the cluster to target. For example, `nodeId1,nodeId2` or `ml:true` -** *`human` (Optional, boolean)*: Specify this query parameter to include the fields with units in the response. Otherwise only -the `_in_bytes` sizes are returned in the response. ** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. ** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request @@ -9073,10 +9869,10 @@ lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no data frame analytics +. Contains wildcard expressions and there are no data frame analytics jobs that match. -2. Contains the _all string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains the _all string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. The default value is true, which returns an empty data_frame_analytics array when there are no matches and the subset of results when there are @@ -9454,9 +10250,6 @@ client.nodes.hotThreads({ ... }) a task from an empty queue) are filtered out. ** *`interval` (Optional, string | -1 | 0)*: The interval to do the second sampling of threads. ** *`snapshots` (Optional, number)*: Number of samples of thread stacktrace. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response -is received before the timeout expires, the request fails and -returns an error. ** *`threads` (Optional, number)*: Specifies the number of hot threads to provide information for. ** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. @@ -9481,7 +10274,6 @@ client.nodes.info({ ... }) ** *`node_id` (Optional, string | string[])*: List of node IDs or names used to limit returned information. ** *`metric` (Optional, string | string[])*: Limits the information returned to the specific metrics. Supports a list, such as http,ingest. ** *`flat_settings` (Optional, boolean)*: If true, returns settings in flat format. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. ** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] @@ -9536,7 +10328,6 @@ client.nodes.stats({ ... }) ** *`groups` (Optional, boolean)*: List of search groups to include in the search statistics. ** *`include_segment_file_sizes` (Optional, boolean)*: If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested). ** *`level` (Optional, Enum("cluster" | "indices" | "shards"))*: Indicates whether statistics are aggregated at the cluster, index, or shard level. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. ** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. ** *`types` (Optional, string[])*: A list of document types for the indexing index metric. ** *`include_unloaded_segments` (Optional, boolean)*: If `true`, the response includes information from segments that are not loaded into memory. @@ -9743,7 +10534,7 @@ Thus the job can be deleted, leaving behind the rolled up data for analysis. If you wish to also remove the rollup data and the rollup index contains the data for only a single job, you can delete the whole rollup index. If the rollup index stores data from several jobs, you must issue a delete-by-query that targets the rollup job's identifier in the rollup index. For example: -``` +---- POST my_rollup_index/_delete_by_query { "query": { @@ -9752,7 +10543,7 @@ POST my_rollup_index/_delete_by_query } } } -``` +---- {ref}/rollup-delete-job.html[Endpoint documentation] [source,ts] @@ -9797,8 +10588,8 @@ This API is useful because a rollup job is often configured to rollup only a sub Furthermore, only certain aggregations can be configured for various fields, leading to a limited subset of functionality depending on that configuration. This API enables you to inspect an index and determine: -1. Does this index have associated rollup data somewhere in the cluster? -2. If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live? +. Does this index have associated rollup data somewhere in the cluster? +. If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live? {ref}/rollup-get-rollup-caps.html[Endpoint documentation] [source,ts] @@ -9901,7 +10692,7 @@ The following functionality is not available: The rollup search API has the capability to search across both "live" non-rollup data and the aggregated rollup data. This is done by simply adding the live indices to the URI. For example: -``` +---- GET sensor-1,sensor_rollup/_rollup_search { "size": 0, @@ -9913,7 +10704,7 @@ GET sensor-1,sensor_rollup/_rollup_search } } } -``` +---- The rollup search endpoint does two things when the search runs: @@ -9973,9 +10764,9 @@ If you try to stop a job that is already stopped, nothing happens. Since only a stopped job can be deleted, it can be useful to block the API until the indexer has fully stopped. This is accomplished with the `wait_for_completion` query parameter, and optionally a timeout. For example: -``` +---- POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s -``` +---- The parameter blocks the API call from returning until either the job has moved to STOPPED or the specified time has elapsed. If the specified time elapses without the job moving to STOPPED, a timeout exception occurs. @@ -10219,8 +11010,6 @@ It supports wildcards (`*`). ** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: Whether to expand wildcard expression to concrete indices that are open, closed or both. ** *`allow_no_indices` (Optional, boolean)*: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified) ** *`ignore_unavailable` (Optional, boolean)*: Whether specified concrete indices should be ignored when unavailable (missing or closed) -** *`pretty` (Optional, boolean)* -** *`human` (Optional, boolean)* [discrete] ==== mount @@ -10277,6 +11066,17 @@ Activate a user profile. Create or update a user profile on behalf of another user. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. +Individual users and external applications should not call this API directly. +The calling application must have either an `access_token` or a combination of `username` and `password` for the user that the profile document is intended for. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + +This API creates or updates a profile document for end users with information that is extracted from the user's authentication object including `username`, `full_name,` `roles`, and the authentication realm. +For example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token. + +When updating a profile document, the API enables the document if it was disabled. +Any updates do not change existing content for either the `labels` or `data` fields. + {ref}/security-api-activate-user-profile.html[Endpoint documentation] [source,ts] ---- @@ -10287,10 +11087,17 @@ client.security.activateUserProfile({ grant_type }) ==== Arguments * *Request (object):* -** *`grant_type` (Enum("password" | "access_token"))* -** *`access_token` (Optional, string)* -** *`password` (Optional, string)* -** *`username` (Optional, string)* +** *`grant_type` (Enum("password" | "access_token"))*: The type of grant. +** *`access_token` (Optional, string)*: The user's Elasticsearch access token or JWT. +Both `access` and `id` JWT token types are supported and they depend on the underlying JWT realm configuration. +If you specify the `access_token` grant type, this parameter is required. +It is not valid with other grant types. +** *`password` (Optional, string)*: The user's password. +If you specify the `password` grant type, this parameter is required. +It is not valid with other grant types. +** *`username` (Optional, string)*: The username that identifies the user. +If you specify the `password` grant type, this parameter is required. +It is not valid with other grant types. [discrete] ==== authenticate @@ -10455,13 +11262,20 @@ client.security.clearCachedPrivileges({ application }) ==== Arguments * *Request (object):* -** *`application` (string)*: A list of application names +** *`application` (string)*: A list of applications. +To clear all applications, use an asterism (`*`). +It does not support other wildcard patterns. [discrete] ==== clear_cached_realms Clear the user cache. -Evict users from the user cache. You can completely clear the cache or evict specific users. +Evict users from the user cache. +You can completely clear the cache or evict specific users. + +User credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request. +There are realm settings that you can use to configure the user cache. +For more information, refer to the documentation about controlling the user cache. {ref}/security-api-clear-cache.html[Endpoint documentation] [source,ts] @@ -10473,8 +11287,11 @@ client.security.clearCachedRealms({ realms }) ==== Arguments * *Request (object):* -** *`realms` (string | string[])*: List of realms to clear -** *`usernames` (Optional, string[])*: List of usernames to clear from the cache +** *`realms` (string | string[])*: A list of realms. +To clear all realms, use an asterisk (`*`). +It does not support other wildcard patterns. +** *`usernames` (Optional, string[])*: A list of the users to clear from the cache. +If you do not specify this parameter, the API evicts all users from the user cache. [discrete] ==== clear_cached_roles @@ -10492,13 +11309,20 @@ client.security.clearCachedRoles({ name }) ==== Arguments * *Request (object):* -** *`name` (string | string[])*: Role name +** *`name` (string | string[])*: A list of roles to evict from the role cache. +To evict all roles, use an asterisk (`*`). +It does not support other wildcard patterns. [discrete] ==== clear_cached_service_tokens Clear service account token caches. Evict a subset of all entries from the service account token caches. +Two separate caches exist for service account tokens: one cache for tokens backed by the `service_tokens` file, and another for tokens backed by the `.security` index. +This API clears matching entries from both caches. + +The cache for service account tokens backed by the `.security` index is cleared automatically on state changes of the security index. +The cache for tokens backed by the `service_tokens` file is cleared automatically on file changes. {ref}/security-api-clear-service-token-caches.html[Endpoint documentation] [source,ts] @@ -10510,19 +11334,29 @@ client.security.clearCachedServiceTokens({ namespace, service, name }) ==== Arguments * *Request (object):* -** *`namespace` (string)*: An identifier for the namespace -** *`service` (string)*: An identifier for the service name -** *`name` (string | string[])*: A list of service token names +** *`namespace` (string)*: The namespace, which is a top-level grouping of service accounts. +** *`service` (string)*: The name of the service, which must be unique within its namespace. +** *`name` (string | string[])*: A list of token names to evict from the service account token caches. +Use a wildcard (`*`) to evict all tokens that belong to a service account. +It does not support other wildcard patterns. [discrete] ==== create_api_key Create an API key. Create an API key for access without requiring basic authentication. + +IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. +If you specify privileges, the API returns an error. + A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. + NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys. +The API keys are created by the Elasticsearch API key service, which is automatically enabled. +To configure or turn off the API key service, refer to API key service setting documentation. + {ref}/security-api-create-api-key.html[Endpoint documentation] [source,ts] ---- @@ -10533,9 +11367,18 @@ client.security.createApiKey({ ... }) ==== Arguments * *Request (object):* -** *`expiration` (Optional, string | -1 | 0)*: Expiration time for the API key. By default, API keys never expire. -** *`name` (Optional, string)*: Specifies the name for this API key. -** *`role_descriptors` (Optional, Record)*: An array of role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, then the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors then the resultant permissions would be an intersection of API keys permissions and authenticated user’s permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for create role API. For more details, see create or update roles API. +** *`expiration` (Optional, string | -1 | 0)*: The expiration time for the API key. +By default, API keys never expire. +** *`name` (Optional, string)*: A name for the API key. +** *`role_descriptors` (Optional, Record)*: An array of role descriptors for this API key. +When it is not specified or it is an empty array, the API key will have a point in time snapshot of permissions of the authenticated user. +If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the authenticated user's permissions thereby limiting the access scope for API keys. +The structure of role descriptor is the same as the request for the create role API. +For more details, refer to the create or update roles API. + +NOTE: Due to the way in which this permission intersection is calculated, it is not possible to create an API key that is a child of another API key, unless the derived key is created without any privileges. +In this case, you must explicitly specify a role descriptor with no privileges. +The derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs. ** *`metadata` (Optional, Record)*: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with `_` are reserved for system usage. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. @@ -10588,6 +11431,9 @@ Create a service account token. Create a service accounts token for access without requiring basic authentication. +NOTE: Service account tokens never expire. +You must actively delete them if they are no longer needed. + {ref}/security-api-create-service-token.html[Endpoint documentation] [source,ts] ---- @@ -10598,14 +11444,22 @@ client.security.createServiceToken({ namespace, service }) ==== Arguments * *Request (object):* -** *`namespace` (string)*: An identifier for the namespace -** *`service` (string)*: An identifier for the service name -** *`name` (Optional, string)*: An identifier for the token name +** *`namespace` (string)*: The name of the namespace, which is a top-level grouping of service accounts. +** *`service` (string)*: The name of the service. +** *`name` (Optional, string)*: The name for the service account token. +If omitted, a random name will be generated. + +Token names must be at least one and no more than 256 characters. +They can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (`-`), and underscores (`_`), but cannot begin with an underscore. + +NOTE: Token names must be unique in the context of the associated service account. +They must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as `//`. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` then refresh the affected shards to make this operation visible to search, if `wait_for` (the default) then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] ==== delegate_pki Delegate PKI authentication. + This API implements the exchange of an X509Certificate chain for an Elasticsearch access token. The certificate chain is validated, according to RFC 5280, by sequentially considering the trust configuration of every installed PKI realm that has `delegation.enabled` set to `true`. A successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm. @@ -10636,6 +11490,11 @@ This may be followed by additional certificates; each subsequent certificate is ==== delete_privileges Delete application privileges. +To use this API, you must have one of the following privileges: + +* The `manage_security` cluster privilege (or a greater privilege such as `all`). +* The "Manage Application Privileges" global privilege for the application being referenced in the request. + {ref}/security-api-delete-privilege.html[Endpoint documentation] [source,ts] ---- @@ -10646,8 +11505,9 @@ client.security.deletePrivileges({ application, name }) ==== Arguments * *Request (object):* -** *`application` (string)*: Application name -** *`name` (string | string[])*: Privilege name +** *`application` (string)*: The name of the application. +Application privileges are always associated with exactly one application. +** *`name` (string | string[])*: The name of the privilege. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] @@ -10655,6 +11515,8 @@ client.security.deletePrivileges({ application, name }) Delete roles. Delete roles in the native realm. +The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. +The delete roles API cannot remove roles that are defined in roles files. {ref}/security-api-delete-role.html[Endpoint documentation] [source,ts] @@ -10666,13 +11528,17 @@ client.security.deleteRole({ name }) ==== Arguments * *Request (object):* -** *`name` (string)*: Role name +** *`name` (string)*: The name of the role. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] ==== delete_role_mapping Delete role mappings. +Role mappings define which roles are assigned to each user. +The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. +The delete role mappings API cannot remove role mappings that are defined in role mapping files. + {ref}/security-api-delete-role-mapping.html[Endpoint documentation] [source,ts] ---- @@ -10683,7 +11549,8 @@ client.security.deleteRoleMapping({ name }) ==== Arguments * *Request (object):* -** *`name` (string)*: Role-mapping name +** *`name` (string)*: The distinct name that identifies the role mapping. +The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] @@ -10702,9 +11569,9 @@ client.security.deleteServiceToken({ namespace, service, name }) ==== Arguments * *Request (object):* -** *`namespace` (string)*: An identifier for the namespace -** *`service` (string)*: An identifier for the service name -** *`name` (string)*: An identifier for the token name +** *`namespace` (string)*: The namespace, which is a top-level grouping of service accounts. +** *`service` (string)*: The service name. +** *`name` (string)*: The name of the service account token. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` then refresh the affected shards to make this operation visible to search, if `wait_for` (the default) then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] @@ -10723,7 +11590,7 @@ client.security.deleteUser({ username }) ==== Arguments * *Request (object):* -** *`username` (string)*: username +** *`username` (string)*: An identifier for the user. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] @@ -10731,6 +11598,8 @@ client.security.deleteUser({ username }) Disable users. Disable users in the native realm. +By default, when you create users, they are enabled. +You can use this API to revoke a user's access to Elasticsearch. {ref}/security-api-disable-user.html[Endpoint documentation] [source,ts] @@ -10742,7 +11611,7 @@ client.security.disableUser({ username }) ==== Arguments * *Request (object):* -** *`username` (string)*: The username of the user to disable +** *`username` (string)*: An identifier for the user. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] @@ -10751,6 +11620,13 @@ Disable a user profile. Disable user profiles so that they are not visible in user profile searches. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. +Individual users and external applications should not call this API directly. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + +When you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches. +To re-enable a disabled user profile, use the enable user profile API . + {ref}/security-api-disable-user-profile.html[Endpoint documentation] [source,ts] ---- @@ -10762,15 +11638,16 @@ client.security.disableUserProfile({ uid }) * *Request (object):* ** *`uid` (string)*: Unique identifier for the user profile. -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If 'true', Elasticsearch refreshes the affected shards to make this operation -visible to search, if 'wait_for' then wait for a refresh to make this operation -visible to search, if 'false' do nothing with refreshes. +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. +If 'wait_for', it waits for a refresh to make this operation visible to search. +If 'false', it does nothing with refreshes. [discrete] ==== enable_user Enable users. Enable users in the native realm. +By default, when you create users, they are enabled. {ref}/security-api-enable-user.html[Endpoint documentation] [source,ts] @@ -10782,7 +11659,7 @@ client.security.enableUser({ username }) ==== Arguments * *Request (object):* -** *`username` (string)*: The username of the user to enable +** *`username` (string)*: An identifier for the user. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. [discrete] @@ -10791,6 +11668,13 @@ Enable a user profile. Enable user profiles to make them visible in user profile searches. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. +Individual users and external applications should not call this API directly. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + +When you activate a user profile, it's automatically enabled and visible in user profile searches. +If you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again. + {ref}/security-api-enable-user-profile.html[Endpoint documentation] [source,ts] ---- @@ -10801,10 +11685,11 @@ client.security.enableUserProfile({ uid }) ==== Arguments * *Request (object):* -** *`uid` (string)*: Unique identifier for the user profile. +** *`uid` (string)*: A unique identifier for the user profile. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If 'true', Elasticsearch refreshes the affected shards to make this operation -visible to search, if 'wait_for' then wait for a refresh to make this operation -visible to search, if 'false' do nothing with refreshes. +visible to search. +If 'wait_for', it waits for a refresh to make this operation visible to search. +If 'false', nothing is done with refreshes. [discrete] ==== enroll_kibana @@ -10812,6 +11697,9 @@ Enroll Kibana. Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster. +NOTE: This API is currently intended for internal use only by Kibana. +Kibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled. + {ref}/security-api-kibana-enrollment.html[Endpoint documentation] [source,ts] ---- @@ -10825,6 +11713,9 @@ Enroll a node. Enroll a new node to allow it to join an existing cluster with security features enabled. +The response contains all the necessary information for the joining node to bootstrap discovery and security related settings so that it can successfully join the cluster. +The response contains key and certificate material that allows the caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster. + {ref}/security-api-node-enrollment.html[Endpoint documentation] [source,ts] ---- @@ -10885,6 +11776,11 @@ client.security.getBuiltinPrivileges() ==== get_privileges Get application privileges. +To use this API, you must have one of the following privileges: + +* The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`). +* The "Manage Application Privileges" global privilege for the application being referenced in the request. + {ref}/security-api-get-privileges.html[Endpoint documentation] [source,ts] ---- @@ -10895,8 +11791,11 @@ client.security.getPrivileges({ ... }) ==== Arguments * *Request (object):* -** *`application` (Optional, string)*: Application name -** *`name` (Optional, string | string[])*: Privilege name +** *`application` (Optional, string)*: The name of the application. +Application privileges are always associated with exactly one application. +If you do not specify this parameter, the API returns information about all privileges for all applications. +** *`name` (Optional, string | string[])*: The name of the privilege. +If you do not specify this parameter, the API returns information about all privileges for the requested application. [discrete] ==== get_role @@ -10916,7 +11815,9 @@ client.security.getRole({ ... }) ==== Arguments * *Request (object):* -** *`name` (Optional, string | string[])*: The name of the role. You can specify multiple roles as a list. If you do not specify this parameter, the API returns information about all roles. +** *`name` (Optional, string | string[])*: The name of the role. +You can specify multiple roles as a list. +If you do not specify this parameter, the API returns information about all roles. [discrete] ==== get_role_mapping @@ -10944,6 +11845,8 @@ Get service accounts. Get a list of service accounts that match the provided path parameters. +NOTE: Currently, only the `elastic/fleet-server` service account is available. + {ref}/security-api-get-service-accounts.html[Endpoint documentation] [source,ts] ---- @@ -10954,13 +11857,23 @@ client.security.getServiceAccounts({ ... }) ==== Arguments * *Request (object):* -** *`namespace` (Optional, string)*: Name of the namespace. Omit this parameter to retrieve information about all service accounts. If you omit this parameter, you must also omit the `service` parameter. -** *`service` (Optional, string)*: Name of the service name. Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`. +** *`namespace` (Optional, string)*: The name of the namespace. +Omit this parameter to retrieve information about all service accounts. +If you omit this parameter, you must also omit the `service` parameter. +** *`service` (Optional, string)*: The service name. +Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`. [discrete] ==== get_service_credentials Get service account credentials. +To use this API, you must have at least the `read_security` cluster privilege (or a greater privilege such as `manage_service_account` or `manage_security`). + +The response includes service account tokens that were created with the create service account tokens API as well as file-backed tokens from all nodes of the cluster. + +NOTE: For tokens backed by the `service_tokens` file, the API collects them from all nodes of the cluster. +Tokens with the same name from different nodes are assumed to be the same token and are only counted once towards the total number of service tokens. + {ref}/security-api-get-service-credentials.html[Endpoint documentation] [source,ts] ---- @@ -10971,25 +11884,49 @@ client.security.getServiceCredentials({ namespace, service }) ==== Arguments * *Request (object):* -** *`namespace` (string)*: Name of the namespace. -** *`service` (string)*: Name of the service name. +** *`namespace` (string)*: The name of the namespace. +** *`service` (string)*: The service name. [discrete] ==== get_settings -Retrieve settings for the security system indices +Get security index settings. + +Get the user-configurable settings for the security internal index (`.security` and associated indices). +Only a subset of the index settings — those that are user-configurable—will be shown. +This includes: + +* `index.auto_expand_replicas` +* `index.number_of_replicas` {ref}/security-api-get-settings.html[Endpoint documentation] [source,ts] ---- -client.security.getSettings() +client.security.getSettings({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. +If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== get_token Get a token. Create a bearer token for access without requiring basic authentication. +The tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface. +Alternatively, you can explicitly enable the `xpack.security.authc.token.enabled` setting. +When you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface. + +The get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body. + +A successful get token API call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available. + +The tokens returned by the get token API have a finite period of time for which they are valid and after that time period, they can no longer be used. +That time period is defined by the `xpack.security.authc.token.timeout` setting. +If you want to invalidate a token immediately, you can do so by using the invalidate token API. {ref}/security-api-get-token.html[Endpoint documentation] [source,ts] @@ -11001,12 +11938,22 @@ client.security.getToken({ ... }) ==== Arguments * *Request (object):* -** *`grant_type` (Optional, Enum("password" | "client_credentials" | "_kerberos" | "refresh_token"))* -** *`scope` (Optional, string)* -** *`password` (Optional, string)* -** *`kerberos_ticket` (Optional, string)* -** *`refresh_token` (Optional, string)* -** *`username` (Optional, string)* +** *`grant_type` (Optional, Enum("password" | "client_credentials" | "_kerberos" | "refresh_token"))*: The type of grant. +Supported grant types are: `password`, `_kerberos`, `client_credentials`, and `refresh_token`. +** *`scope` (Optional, string)*: The scope of the token. +Currently tokens are only issued for a scope of FULL regardless of the value sent with the request. +** *`password` (Optional, string)*: The user's password. +If you specify the `password` grant type, this parameter is required. +This parameter is not valid with any other supported grant type. +** *`kerberos_ticket` (Optional, string)*: The base64 encoded kerberos ticket. +If you specify the `_kerberos` grant type, this parameter is required. +This parameter is not valid with any other supported grant type. +** *`refresh_token` (Optional, string)*: The string that was returned when you created the token, which enables you to extend its life. +If you specify the `refresh_token` grant type, this parameter is required. +This parameter is not valid with any other supported grant type. +** *`username` (Optional, string)*: The username that identifies the user. +If you specify the `password` grant type, this parameter is required. +This parameter is not valid with any other supported grant type. [discrete] ==== get_user @@ -11025,12 +11972,17 @@ client.security.getUser({ ... }) * *Request (object):* ** *`username` (Optional, string | string[])*: An identifier for the user. You can specify multiple usernames as a list. If you omit this parameter, the API retrieves information about all users. -** *`with_profile_uid` (Optional, boolean)*: If true will return the User Profile ID for a user, if any. +** *`with_profile_uid` (Optional, boolean)*: Determines whether to retrieve the user profile UID, if it exists, for the users. [discrete] ==== get_user_privileges Get user privileges. +Get the security privileges for the logged in user. +All users can use this API, but only to determine their own privileges. +To check the privileges of other users, you must use the run as feature. +To check whether a user has a specific list of privileges, use the has privileges API. + {ref}/security-api-get-user-privileges.html[Endpoint documentation] [source,ts] ---- @@ -11051,6 +12003,10 @@ Get a user profile. Get a user's profile using the unique profile ID. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. +Individual users and external applications should not call this API directly. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + {ref}/security-api-get-user-profile.html[Endpoint documentation] [source,ts] ---- @@ -11062,9 +12018,9 @@ client.security.getUserProfile({ uid }) * *Request (object):* ** *`uid` (string | string[])*: A unique identifier for the user profile. -** *`data` (Optional, string | string[])*: List of filters for the `data` field of the profile document. -To return all content use `data=*`. To return a subset of content -use `data=` to retrieve content nested under the specified ``. +** *`data` (Optional, string | string[])*: A list of filters for the `data` field of the profile document. +To return all content use `data=*`. +To return a subset of content use `data=` to retrieve content nested under the specified ``. By default returns no `data` content. [discrete] @@ -11073,12 +12029,19 @@ Grant an API key. Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. -The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created. -It is not possible to use this API to create an API key without that user’s credentials. +The caller must have authentication credentials for the user on whose behalf the API key will be created. +It is not possible to use this API to create an API key without that user's credentials. +The supported user authentication credential types are: + +* username and password +* Elasticsearch access tokens +* JWTs + The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user. This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. +The API keys are created by the Elasticsearch API key service, which is automatically enabled. A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. @@ -11095,15 +12058,16 @@ client.security.grantApiKey({ api_key, grant_type }) ==== Arguments * *Request (object):* -** *`api_key` ({ name, expiration, role_descriptors, metadata })*: Defines the API key. +** *`api_key` ({ name, expiration, role_descriptors, metadata })*: The API key. ** *`grant_type` (Enum("access_token" | "password"))*: The type of grant. Supported grant types are: `access_token`, `password`. -** *`access_token` (Optional, string)*: The user’s access token. +** *`access_token` (Optional, string)*: The user's access token. If you specify the `access_token` grant type, this parameter is required. It is not valid with other grant types. ** *`username` (Optional, string)*: The user name that identifies the user. If you specify the `password` grant type, this parameter is required. It is not valid with other grant types. -** *`password` (Optional, string)*: The user’s password. If you specify the `password` grant type, this parameter is required. +** *`password` (Optional, string)*: The user's password. +If you specify the `password` grant type, this parameter is required. It is not valid with other grant types. ** *`run_as` (Optional, string)*: The name of the user to be impersonated. @@ -11112,6 +12076,8 @@ It is not valid with other grant types. Check user privileges. Determine whether the specified user has a specified list of privileges. +All users can use this API, but only to determine their own privileges. +To check the privileges of other users, you must use the run as feature. {ref}/security-api-has-privileges.html[Endpoint documentation] [source,ts] @@ -11134,6 +12100,9 @@ Check user profile privileges. Determine whether the users associated with the specified user profile IDs have all the requested privileges. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + {ref}/security-api-has-privileges-user-profile.html[Endpoint documentation] [source,ts] ---- @@ -11145,7 +12114,7 @@ client.security.hasPrivilegesUserProfile({ uids, privileges }) * *Request (object):* ** *`uids` (string[])*: A list of profile IDs. The privileges are checked for associated users of the profiles. -** *`privileges` ({ application, cluster, index })* +** *`privileges` ({ application, cluster, index })*: An object containing all the privileges to be checked. [discrete] ==== invalidate_api_key @@ -11153,11 +12122,15 @@ Invalidate API keys. This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted. -The `manage_api_key` privilege allows deleting any API keys. -The `manage_own_api_key` only allows deleting API keys that are owned by the user. + +To use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges. +The `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys. +The `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys. +The `manage_own_api_key` only allows deleting REST API keys that are owned by the user. In addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats: + - Set the parameter `owner=true`. -- Or, set both `username` and `realm_name` to match the user’s identity. +- Or, set both `username` and `realm_name` to match the user's identity. - Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field. {ref}/security-api-invalidate-api-key.html[Endpoint documentation] @@ -11175,12 +12148,14 @@ client.security.invalidateApiKey({ ... }) This parameter cannot be used with any of `name`, `realm_name`, or `username`. ** *`name` (Optional, string)*: An API key name. This parameter cannot be used with any of `ids`, `realm_name` or `username`. -** *`owner` (Optional, boolean)*: Can be used to query API keys owned by the currently authenticated user. +** *`owner` (Optional, boolean)*: Query API keys owned by the currently authenticated user. The `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones. + +NOTE: At least one of `ids`, `name`, `username`, and `realm_name` must be specified if `owner` is `false`. ** *`realm_name` (Optional, string)*: The name of an authentication realm. This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. ** *`username` (Optional, string)*: The username of a user. -This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. +This parameter cannot be used with either `ids` or `name` or when `owner` flag is set to `true`. [discrete] ==== invalidate_token @@ -11190,9 +12165,14 @@ The access tokens returned by the get token API have a finite period of time for After that time period, they can no longer be used. The time period is defined by the `xpack.security.authc.token.timeout` setting. -The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. +The refresh tokens returned by the get token API are only valid for 24 hours. +They can also be used exactly once. If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API. +NOTE: While all parameters are optional, at least one of them is required. +More specifically, either one of `token` or `refresh_token` parameters is required. +If none of these two are specified, then `realm_name` and/or `username` need to be specified. + {ref}/security-api-invalidate-token.html[Endpoint documentation] [source,ts] ---- @@ -11203,14 +12183,19 @@ client.security.invalidateToken({ ... }) ==== Arguments * *Request (object):* -** *`token` (Optional, string)* -** *`refresh_token` (Optional, string)* -** *`realm_name` (Optional, string)* -** *`username` (Optional, string)* +** *`token` (Optional, string)*: An access token. +This parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used. +** *`refresh_token` (Optional, string)*: A refresh token. +This parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used. +** *`realm_name` (Optional, string)*: The name of an authentication realm. +This parameter cannot be used with either `refresh_token` or `token`. +** *`username` (Optional, string)*: The username of a user. +This parameter cannot be used with either `refresh_token` or `token`. [discrete] ==== oidc_authenticate Authenticate OpenID Connect. + Exchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. @@ -11238,6 +12223,7 @@ This property is useful in cases where multiple realms are defined. [discrete] ==== oidc_logout Logout of OpenID Connect. + Invalidate an access token and a refresh token that were generated as a response to the `/_security/oidc/authenticate` API. If the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout. @@ -11261,6 +12247,7 @@ client.security.oidcLogout({ access_token }) [discrete] ==== oidc_prepare_authentication Prepare OpenID connect authentication. + Create an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch. The response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process. @@ -11295,6 +12282,24 @@ If the caller of the API does not provide a value, Elasticsearch will generate o ==== put_privileges Create or update application privileges. +To use this API, you must have one of the following privileges: + +* The `manage_security` cluster privilege (or a greater privilege such as `all`). +* The "Manage Application Privileges" global privilege for the application being referenced in the request. + +Application names are formed from a prefix, with an optional suffix that conform to the following rules: + +* The prefix must begin with a lowercase ASCII letter. +* The prefix must contain only ASCII letters or digits. +* The prefix must be at least 3 characters long. +* If the suffix exists, it must begin with either a dash `-` or `_`. +* The suffix cannot contain any of the following characters: `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*`. +* No part of the name can contain whitespace. + +Privilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`. + +Action names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`. + {ref}/security-api-put-privileges.html[Endpoint documentation] [source,ts] ---- @@ -11332,6 +12337,9 @@ client.security.putRole({ name }) ** *`global` (Optional, Record)*: An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges. ** *`indices` (Optional, { field_security, names, privileges, query, allow_restricted_indices }[])*: A list of indices permissions entries. ** *`remote_indices` (Optional, { clusters, field_security, names, privileges, query, allow_restricted_indices }[])*: A list of remote indices permissions entries. + +NOTE: Remote indices are effective for remote clusters configured with the API key based model. +They have no effect for remote clusters configured with the certificate based model. ** *`remote_cluster` (Optional, { clusters, privileges }[])*: A list of remote cluster permissions entries. ** *`metadata` (Optional, Record)*: Optional metadata. Within the metadata object, keys that begin with an underscore (`_`) are reserved for system use. ** *`run_as` (Optional, string[])*: A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected. @@ -11347,9 +12355,27 @@ Role mappings define which roles are assigned to each user. Each mapping has rules that identify users and a list of roles that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files. -This API does not create roles. Rather, it maps users to existing roles. +NOTE: This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using the create or update roles API or roles files. +**Role templates** + +The most common use for role mappings is to create a mapping from a known value on the user to a fixed role name. +For example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch. +The `roles` field is used for this purpose. + +For more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user. +The `role_templates` field is used for this purpose. + +NOTE: To use role templates successfully, the relevant scripting feature must be enabled. +Otherwise, all attempts to create a role mapping with role templates fail. + +All of the user fields that are available in the role mapping rules are also available in the role templates. +Thus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated. + +By default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user. +If the format of the template is set to "json" then the template is expected to produce a JSON string or an array of JSON strings for the role names. + {ref}/security-api-put-role-mapping.html[Endpoint documentation] [source,ts] ---- @@ -11360,12 +12386,17 @@ client.security.putRoleMapping({ name }) ==== Arguments * *Request (object):* -** *`name` (string)*: Role-mapping name -** *`enabled` (Optional, boolean)* -** *`metadata` (Optional, Record)* -** *`roles` (Optional, string[])* -** *`role_templates` (Optional, { format, template }[])* -** *`rules` (Optional, { any, all, field, except })* +** *`name` (string)*: The distinct name that identifies the role mapping. +The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. +** *`enabled` (Optional, boolean)*: Mappings that have `enabled` set to `false` are ignored when role mapping is performed. +** *`metadata` (Optional, Record)*: Additional metadata that helps define which roles are assigned to each user. +Within the metadata object, keys beginning with `_` are reserved for system usage. +** *`roles` (Optional, string[])*: A list of role names that are granted to the users that match the role mapping rules. +Exactly one of `roles` or `role_templates` must be specified. +** *`role_templates` (Optional, { format, template }[])*: A list of Mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules. +Exactly one of `roles` or `role_templates` must be specified. +** *`rules` (Optional, { any, all, field, except })*: The rules that determine which users should be matched by the mapping. +A rule is a logical condition that is expressed by using a JSON DSL. ** *`run_as` (Optional, string[])* ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. @@ -11373,8 +12404,9 @@ client.security.putRoleMapping({ name }) ==== put_user Create or update users. +Add and update users in the native realm. A password is required for adding a new user but is optional when updating an existing user. -To change a user’s password without updating any other fields, use the change password API. +To change a user's password without updating any other fields, use the change password API. {ref}/security-api-put-user.html[Endpoint documentation] [source,ts] @@ -11386,21 +12418,40 @@ client.security.putUser({ username }) ==== Arguments * *Request (object):* -** *`username` (string)*: The username of the User -** *`email` (Optional, string | null)* -** *`full_name` (Optional, string | null)* -** *`metadata` (Optional, Record)* -** *`password` (Optional, string)* -** *`password_hash` (Optional, string)* -** *`roles` (Optional, string[])* -** *`enabled` (Optional, boolean)* -** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. +** *`username` (string)*: An identifier for the user. + +NOTE: Usernames must be at least 1 and no more than 507 characters. +They can contain alphanumeric characters (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic Latin (ASCII) block. +Leading or trailing whitespace is not allowed. +** *`email` (Optional, string | null)*: The email of the user. +** *`full_name` (Optional, string | null)*: The full name of the user. +** *`metadata` (Optional, Record)*: Arbitrary metadata that you want to associate with the user. +** *`password` (Optional, string)*: The user's password. +Passwords must be at least 6 characters long. +When adding a user, one of `password` or `password_hash` is required. +When updating an existing user, the password is optional, so that other fields on the user (such as their roles) may be updated without modifying the user's password +** *`password_hash` (Optional, string)*: A hash of the user's password. +This must be produced using the same hashing algorithm as has been configured for password storage. +For more details, see the explanation of the `xpack.security.authc.password_hashing.algorithm` setting in the user cache and password hash algorithm documentation. +Using this parameter allows the client to pre-hash the password for performance and/or confidentiality reasons. +The `password` parameter and the `password_hash` parameter cannot be used in the same request. +** *`roles` (Optional, string[])*: A set of roles the user has. +The roles determine the user's access permissions. +To create a user without any roles, specify an empty list (`[]`). +** *`enabled` (Optional, boolean)*: Specifies whether the user is enabled. +** *`refresh` (Optional, Enum(true | false | "wait_for"))*: Valid values are `true`, `false`, and `wait_for`. +These values have the same meaning as in the index API, but the default value for this API is true. [discrete] ==== query_api_keys Find API keys with a query. -Get a paginated list of API keys and their information. You can optionally filter the results with a query. +Get a paginated list of API keys and their information. +You can optionally filter the results with a query. + +To use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges. +If you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own. +If you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership. {ref}/security-api-query-api-key.html[Endpoint documentation] [source,ts] @@ -11423,25 +12474,39 @@ The query supports a subset of query types, including `match_all`, `bool`, `term `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following public information associated with an API key: `id`, `type`, `name`, `creation`, `expiration`, `invalidated`, `invalidation`, `username`, `realm`, and `metadata`. -** *`from` (Optional, number)*: Starting document offset. -By default, you cannot page through more than 10,000 hits using the from and size parameters. + +NOTE: The queryable string values associated with API keys are internally mapped as keywords. +Consequently, if no `analyzer` parameter is specified for a `match` query, then the provided match query string is interpreted as a single keyword value. +Such a match query is hence equivalent to a `term` query. +** *`from` (Optional, number)*: The starting document offset. +It 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. -** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: Other than `id`, all public fields of an API key are eligible for sorting. +** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: The sort definition. +Other than `id`, all public fields of an API key are eligible for sorting. In addition, sort can also be applied to the `_doc` field to sort by index order. ** *`size` (Optional, number)*: The number of hits to return. +It must not be negative. +The `size` parameter can be set to `0`, in which case no API key matches are returned, only the aggregation results. 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. -** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: Search after definition +** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: The search after definition. ** *`with_limited_by` (Optional, boolean)*: Return the snapshot of the owner user's role descriptors associated with the API key. -An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors. -** *`with_profile_uid` (Optional, boolean)*: Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists. +An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors (effectively limited by it). +An API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has `manage_api_key` or higher privileges. +** *`with_profile_uid` (Optional, boolean)*: Determines whether to also retrieve the profile UID for the API key owner principal. +If it exists, the profile UID is returned under the `profile_uid` response field for each API key. ** *`typed_keys` (Optional, boolean)*: Determines whether aggregation names are prefixed by their respective types in the response. [discrete] ==== query_role Find roles with a query. -Get roles in a paginated manner. You can optionally filter the results with a query. +Get roles in a paginated manner. +The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. +The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. +You can optionally filter the results with a query. +Also, the results can be paginated and sorted. {ref}/security-api-query-role.html[Endpoint documentation] [source,ts] @@ -11458,16 +12523,19 @@ If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with roles: `name`, `description`, `metadata`, -`applications.application`, `applications.privileges`, `applications.resources`. -** *`from` (Optional, number)*: Starting document offset. -By default, you cannot page through more than 10,000 hits using the from and size parameters. +`applications.application`, `applications.privileges`, and `applications.resources`. +** *`from` (Optional, number)*: The starting document offset. +It 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. -** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: All public fields of a role are eligible for sorting. +** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: The sort definition. +You can sort on `username`, `roles`, or `enabled`. In addition, sort can also be applied to the `_doc` field to sort by index order. ** *`size` (Optional, number)*: The number of hits to return. +It 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. -** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: Search after definition +** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: The search after definition. [discrete] ==== query_user @@ -11476,6 +12544,9 @@ Find users with a query. Get information for users in a paginated manner. You can optionally filter the results with a query. +NOTE: As opposed to the get user API, built-in users are excluded from the result. +This API is only for native users. + {ref}/security-api-query-user.html[Endpoint documentation] [source,ts] ---- @@ -11490,23 +12561,39 @@ client.security.queryUser({ ... }) If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. -You can query the following information associated with user: `username`, `roles`, `enabled` -** *`from` (Optional, number)*: Starting document offset. -By default, you cannot page through more than 10,000 hits using the from and size parameters. +You can query the following information associated with user: `username`, `roles`, `enabled`, `full_name`, and `email`. +** *`from` (Optional, number)*: The starting document offset. +It 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. -** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: Fields eligible for sorting are: username, roles, enabled +** *`sort` (Optional, string | { _score, _doc, _geo_distance, _script } | string | { _score, _doc, _geo_distance, _script }[])*: The sort definition. +Fields eligible for sorting are: `username`, `roles`, `enabled`. In addition, sort can also be applied to the `_doc` field to sort by index order. ** *`size` (Optional, number)*: The number of hits to return. +It 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. -** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: Search after definition -** *`with_profile_uid` (Optional, boolean)*: If true will return the User Profile ID for the users in the query result, if any. +** *`search_after` (Optional, number | number | string | boolean | null | User-defined value[])*: The search after definition +** *`with_profile_uid` (Optional, boolean)*: Determines whether to retrieve the user profile UID, if it exists, for the users. [discrete] ==== saml_authenticate Authenticate SAML. -Submits a SAML response message to Elasticsearch for consumption. +Submit a SAML response message to Elasticsearch for consumption. + +NOTE: This API is intended for use by custom web applications other than Kibana. +If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + +The SAML message that is submitted can be: + +* A response to a SAML authentication request that was previously created using the SAML prepare authentication API. +* An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow. + +In either case, the SAML message needs to be a base64 encoded XML document with a root element of ``. + +After successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. +This API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch. {ref}/security-api-saml-authenticate.html[Endpoint documentation] [source,ts] @@ -11518,8 +12605,8 @@ client.security.samlAuthenticate({ content, ids }) ==== Arguments * *Request (object):* -** *`content` (string)*: The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document. -** *`ids` (string | string[])*: A json array with all the valid SAML Request Ids that the caller of the API has for the current user. +** *`content` (string)*: The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document. +** *`ids` (string | string[])*: A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. ** *`realm` (Optional, string)*: The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined. [discrete] @@ -11528,6 +12615,15 @@ Logout of SAML completely. Verifies the logout response sent from the SAML IdP. +NOTE: This API is intended for use by custom web applications other than Kibana. +If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + +The SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout. +This API verifies the response by ensuring the content is relevant and validating its signature. +An empty response is returned if the verification process is successful. +The response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding. +The caller of this API must prepare the request accordingly so that this API can handle either of them. + {ref}/security-api-saml-complete-logout.html[Endpoint documentation] [source,ts] ---- @@ -11539,7 +12635,7 @@ client.security.samlCompleteLogout({ realm, ids }) * *Request (object):* ** *`realm` (string)*: The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response. -** *`ids` (string | string[])*: A json array with all the valid SAML Request Ids that the caller of the API has for the current user. +** *`ids` (string | string[])*: A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. ** *`query_string` (Optional, string)*: If the SAML IdP sends the logout response with the HTTP-Redirect binding, this field must be set to the query string of the redirect URI. ** *`content` (Optional, string)*: If the SAML IdP sends the logout response with the HTTP-Post binding, this field must be set to the value of the SAMLResponse form parameter from the logout response. @@ -11547,7 +12643,15 @@ client.security.samlCompleteLogout({ realm, ids }) ==== saml_invalidate Invalidate SAML. -Submits a SAML LogoutRequest message to Elasticsearch for consumption. +Submit a SAML LogoutRequest message to Elasticsearch for consumption. + +NOTE: This API is intended for use by custom web applications other than Kibana. +If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + +The logout request comes from the SAML IdP during an IdP initiated Single Logout. +The custom web application can use this API to have Elasticsearch process the `LogoutRequest`. +After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message. +Thus the user can be redirected back to their IdP. {ref}/security-api-saml-invalidate.html[Endpoint documentation] [source,ts] @@ -11560,12 +12664,12 @@ client.security.samlInvalidate({ query_string }) * *Request (object):* ** *`query_string` (string)*: The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. -This query should include a single parameter named SAMLRequest that contains a SAML logout request that is deflated and Base64 encoded. -If the SAML IdP has signed the logout request, the URL should include two extra parameters named SigAlg and Signature that contain the algorithm used for the signature and the signature value itself. -In order for Elasticsearch to be able to verify the IdP’s signature, the value of the query_string field must be an exact match to the string provided by the browser. +This query should include a single parameter named `SAMLRequest` that contains a SAML logout request that is deflated and Base64 encoded. +If the SAML IdP has signed the logout request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value itself. +In order for Elasticsearch to be able to verify the IdP's signature, the value of the `query_string` field must be an exact match to the string provided by the browser. The client application must not attempt to parse or process the string in any way. -** *`acs` (Optional, string)*: The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter. -** *`realm` (Optional, string)*: The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter. +** *`acs` (Optional, string)*: The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the `realm` parameter. +** *`realm` (Optional, string)*: The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the `acs` parameter. [discrete] ==== saml_logout @@ -11573,6 +12677,12 @@ Logout of SAML. Submits a request to invalidate an access token and refresh token. +NOTE: This API is intended for use by custom web applications other than Kibana. +If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + +This API invalidates the tokens that were generated for a user by the SAML authenticate API. +If the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout). + {ref}/security-api-saml-logout.html[Endpoint documentation] [source,ts] ---- @@ -11584,7 +12694,7 @@ client.security.samlLogout({ token }) * *Request (object):* ** *`token` (string)*: The access token that was returned as a response to calling the SAML authenticate API. -Alternatively, the most recent token that was received after refreshing the original one by using a refresh_token. +Alternatively, the most recent token that was received after refreshing the original one by using a `refresh_token`. ** *`refresh_token` (Optional, string)*: The refresh token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent refresh token that was received after refreshing the original access token. @@ -11592,7 +12702,18 @@ Alternatively, the most recent refresh token that was received after refreshing ==== saml_prepare_authentication Prepare SAML authentication. -Creates a SAML authentication request (``) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch. +Create a SAML authentication request (``) as a URL string based on the configuration of the respective SAML realm in Elasticsearch. + +NOTE: This API is intended for use by custom web applications other than Kibana. +If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. + +This API returns a URL pointing to the SAML Identity Provider. +You can use the URL to redirect the browser of the user in order to continue the authentication process. +The URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded. +If the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`. +These parameters contain the algorithm used for the signature and the signature value itself. +It also returns a random string that uniquely identifies this SAML Authentication request. +The caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process. {ref}/security-api-saml-prepare-authentication.html[Endpoint documentation] [source,ts] @@ -11605,10 +12726,10 @@ client.security.samlPrepareAuthentication({ ... }) * *Request (object):* ** *`acs` (Optional, string)*: The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch. -The realm is used to generate the authentication request. You must specify either this parameter or the realm parameter. +The realm is used to generate the authentication request. You must specify either this parameter or the `realm` parameter. ** *`realm` (Optional, string)*: The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request. -You must specify either this parameter or the acs parameter. -** *`relay_state` (Optional, string)*: A string that will be included in the redirect URL that this API returns as the RelayState query parameter. +You must specify either this parameter or the `acs` parameter. +** *`relay_state` (Optional, string)*: A string that will be included in the redirect URL that this API returns as the `RelayState` query parameter. If the Authentication Request is signed, this value is used as part of the signature computation. [discrete] @@ -11617,6 +12738,9 @@ Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 Service Provider. +The SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file. +This API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch. + {ref}/security-api-saml-sp-metadata.html[Endpoint documentation] [source,ts] ---- @@ -11635,6 +12759,10 @@ Suggest a user profile. Get suggestions for user profiles that match specified search criteria. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. +Individual users and external applications should not call this API directly. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + {ref}/security-api-suggest-user-profile.html[Endpoint documentation] [source,ts] ---- @@ -11645,35 +12773,40 @@ client.security.suggestUserProfiles({ ... }) ==== Arguments * *Request (object):* -** *`name` (Optional, string)*: Query string used to match name-related fields in user profile documents. +** *`name` (Optional, string)*: A query string used to match name-related fields in user profile documents. Name-related fields are the user's `username`, `full_name`, and `email`. -** *`size` (Optional, number)*: Number of profiles to return. -** *`data` (Optional, string | string[])*: List of filters for the `data` field of the profile document. -To return all content use `data=*`. To return a subset of content -use `data=` to retrieve content nested under the specified ``. -By default returns no `data` content. +** *`size` (Optional, number)*: The number of profiles to return. +** *`data` (Optional, string | string[])*: A list of filters for the `data` field of the profile document. +To return all content use `data=*`. +To return a subset of content, use `data=` to retrieve content nested under the specified ``. +By default, the API returns no `data` content. +It is an error to specify `data` as both the query parameter and the request body field. ** *`hint` (Optional, { uids, labels })*: Extra search criteria to improve relevance of the suggestion result. Profiles matching the spcified hint are ranked higher in the response. -Profiles not matching the hint don't exclude the profile from the response -as long as the profile matches the `name` field query. +Profiles not matching the hint aren't excluded from the response as long as the profile matches the `name` field query. [discrete] ==== update_api_key Update an API key. -Updates attributes of an existing API key. +Update attributes of an existing API key. +This API supports updates to an API key's access scope, expiration, and metadata. + +To use this API, you must have at least the `manage_own_api_key` cluster privilege. Users can only update API keys that they created or that were granted to them. -Use this API to update API keys created by the create API Key or grant API Key APIs. -If you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead. -It’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key. -This API supports updates to an API key’s access scope and metadata. -The access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request. -The snapshot of the owner’s permissions is updated automatically on every call. -If you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope. -This change can occur if the owner user’s permissions have changed since the API key was created or last modified. To update another user’s API key, use the `run_as` feature to submit a request on behalf of another user. -IMPORTANT: It’s not possible to use an API key as the authentication credential for this API. -To update an API key, the owner user’s credentials are required. + +IMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required. + +Use this API to update API keys created by the create API key or grant API Key APIs. +If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead. +It's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API. + +The access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request. +The snapshot of the owner's permissions is updated automatically on every call. + +IMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope. +This change can occur if the owner user's permissions have changed since the API key was created or last modified. {ref}/security-api-update-api-key.html[Endpoint documentation] [source,ts] @@ -11686,9 +12819,20 @@ client.security.updateApiKey({ id }) * *Request (object):* ** *`id` (string)*: The ID of the API key to update. -** *`role_descriptors` (Optional, Record)*: An array of role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, then the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors then the resultant permissions would be an intersection of API keys permissions and authenticated user’s permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for create role API. For more details, see create or update roles API. -** *`metadata` (Optional, Record)*: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage. -** *`expiration` (Optional, string | -1 | 0)*: Expiration time for the API key. +** *`role_descriptors` (Optional, Record)*: The role descriptors to assign to this API key. +The API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user. +You can assign new privileges by specifying them in this parameter. +To remove assigned privileges, you can supply an empty `role_descriptors` parameter, that is to say, an empty object `{}`. +If an API key has no assigned privileges, it inherits the owner user's full permissions. +The snapshot of the owner's permissions is always updated, whether you supply the `role_descriptors` parameter or not. +The structure of a role descriptor is the same as the request for the create API keys API. +** *`metadata` (Optional, Record)*: Arbitrary metadata that you want to associate with the API key. +It supports a nested data structure. +Within the metadata object, keys beginning with `_` are reserved for system usage. +When specified, this value fully replaces the metadata previously associated with the API key. +** *`expiration` (Optional, string | -1 | 0)*: The expiration time for the API key. +By default, API keys never expire. +This property can be omitted to leave the expiration unchanged. [discrete] ==== update_cross_cluster_api_key @@ -11696,6 +12840,20 @@ Update a cross-cluster API key. Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. +To use this API, you must have at least the `manage_security` cluster privilege. +Users can only update API keys that they created. +To update another user's API key, use the `run_as` feature to submit a request on behalf of another user. + +IMPORTANT: It's not possible to use an API key as the authentication credential for this API. +To update an API key, the owner user's credentials are required. + +It's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API. + +This API supports updates to an API key's access scope, metadata, and expiration. +The owner user's information, such as the `username` and `realm`, is also updated automatically on every call. + +NOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API. + {ref}/security-api-update-cross-cluster-api-key.html[Endpoint documentation] [source,ts] ---- @@ -11711,7 +12869,7 @@ client.security.updateCrossClusterApiKey({ id, access }) The access is composed of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access. -** *`expiration` (Optional, string | -1 | 0)*: Expiration time for the API key. +** *`expiration` (Optional, string | -1 | 0)*: The expiration time for the API key. By default, API keys never expire. This property can be omitted to leave the value unchanged. ** *`metadata` (Optional, Record)*: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. @@ -11720,14 +12878,32 @@ When specified, this information fully replaces metadata previously associated w [discrete] ==== update_settings -Update settings for the security system index +Update security index settings. + +Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified. This includes `index.auto_expand_replicas` and `index.number_of_replicas`. + +NOTE: If `index.auto_expand_replicas` is set, `index.number_of_replicas` will be ignored during updates. + +If a specific index is not in use on the system and settings are provided for it, the request will be rejected. +This API does not yet support configuring the settings for indices before they are in use. {ref}/security-api-update-settings.html[Endpoint documentation] [source,ts] ---- -client.security.updateSettings() +client.security.updateSettings({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`security` (Optional, { index })*: Settings for the index used for most security configuration, including native realm users and roles configured with the API. +** *`security-profile` (Optional, { index })*: Settings for the index used to store profile information. +** *`security-tokens` (Optional, { index })*: Settings for the index used to store tokens. +** *`master_timeout` (Optional, string | -1 | 0)*: The period to wait for a connection to the master node. +If no response is received before the timeout expires, the request fails and returns an error. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for a response. +If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== update_user_profile_data @@ -11735,6 +12911,21 @@ Update user profile data. Update specific data for the user profile that is associated with a unique ID. +NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. +Individual users and external applications should not call this API directly. +Elastic reserves the right to change or remove this feature in future releases without prior notice. + +To use this API, you must have one of the following privileges: + +* The `manage_user_profile` cluster privilege. +* The `update_profile_data` global privilege for the namespaces that are referenced in the request. + +This API updates the `labels` and `data` fields of an existing user profile document with JSON objects. +New keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request. + +For both labels and data, content is namespaced by the top-level fields. +The `update_profile_data` global privilege grants privileges for updating only the allowed namespaces. + {ref}/security-api-update-user-profile-data.html[Endpoint documentation] [source,ts] ---- @@ -11746,15 +12937,19 @@ client.security.updateUserProfileData({ uid }) * *Request (object):* ** *`uid` (string)*: A unique identifier for the user profile. -** *`labels` (Optional, Record)*: Searchable data that you want to associate with the user profile. This -field supports a nested data structure. +** *`labels` (Optional, Record)*: Searchable data that you want to associate with the user profile. +This field supports a nested data structure. +Within the labels object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`). ** *`data` (Optional, Record)*: Non-searchable data that you want to associate with the user profile. This field supports a nested data structure. +Within the `data` object, top-level keys cannot begin with an underscore (`_`) or contain a period (`.`). +The data object is not searchable, but can be retrieved with the get user profile API. ** *`if_seq_no` (Optional, number)*: Only perform the operation if the document has this sequence number. ** *`if_primary_term` (Optional, number)*: Only perform the operation if the document has this primary term. ** *`refresh` (Optional, Enum(true | false | "wait_for"))*: If 'true', Elasticsearch refreshes the affected shards to make this operation -visible to search, if 'wait_for' then wait for a refresh to make this operation -visible to search, if 'false' do nothing with refreshes. +visible to search. +If 'wait_for', it waits for a refresh to make this operation visible to search. +If 'false', nothing is done with refreshes. [discrete] === shutdown @@ -11807,7 +13002,6 @@ client.shutdown.getNode({ ... }) * *Request (object):* ** *`node_id` (Optional, string | string[])*: Which node for which to retrieve the shutdown status ** *`master_timeout` (Optional, Enum("nanos" | "micros" | "ms" | "s" | "m" | "h" | "d"))*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. -** *`timeout` (Optional, Enum("nanos" | "micros" | "ms" | "s" | "m" | "h" | "d"))*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== put_node @@ -12158,7 +13352,6 @@ client.snapshot.clone({ repository, snapshot, target_snapshot, indices }) ** *`target_snapshot` (string)*: The name of the cloned snapshot to create ** *`indices` (string)* ** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`timeout` (Optional, string | -1 | 0)* [discrete] ==== create @@ -12298,14 +13491,132 @@ client.snapshot.getRepository({ ... }) [discrete] ==== repository_analyze -Analyzes a repository for correctness and performance +Analyze a snapshot repository. +Analyze the performance characteristics and any incorrect behaviour found in a repository. -{ref}/modules-snapshots.html[Endpoint documentation] +The response exposes implementation details of the analysis which may change from version to version. +The response body format is therefore not considered stable and may be different in newer versions. + +There are a large number of third-party storage systems available, not all of which are suitable for use as a snapshot repository by Elasticsearch. +Some storage systems behave incorrectly, or perform poorly, especially when accessed concurrently by multiple clients as the nodes of an Elasticsearch cluster do. This API performs a collection of read and write operations on your repository which are designed to detect incorrect behaviour and to measure the performance characteristics of your storage system. + +The default values for the parameters are deliberately low to reduce the impact of running an analysis inadvertently and to provide a sensible starting point for your investigations. +Run your first analysis with the default parameter values to check for simple problems. +If successful, run a sequence of increasingly large analyses until you encounter a failure or you reach a `blob_count` of at least `2000`, a `max_blob_size` of at least `2gb`, a `max_total_data_size` of at least `1tb`, and a `register_operation_count` of at least `100`. +Always specify a generous timeout, possibly `1h` or longer, to allow time for each analysis to run to completion. +Perform the analyses using a multi-node cluster of a similar size to your production cluster so that it can detect any problems that only arise when the repository is accessed by many nodes at once. + +If the analysis fails, Elasticsearch detected that your repository behaved unexpectedly. +This usually means you are using a third-party storage system with an incorrect or incompatible implementation of the API it claims to support. +If so, this storage system is not suitable for use as a snapshot repository. +You will need to work with the supplier of your storage system to address the incompatibilities that Elasticsearch detects. + +If the analysis is successful, the API returns details of the testing process, optionally including how long each operation took. +You can use this information to determine the performance of your storage system. +If any operation fails or returns an incorrect result, the API returns an error. +If the API returns an error, it may not have removed all the data it wrote to the repository. +The error will indicate the location of any leftover data and this path is also recorded in the Elasticsearch logs. +You should verify that this location has been cleaned up correctly. +If there is still leftover data at the specified location, you should manually remove it. + +If the connection from your client to Elasticsearch is closed while the client is waiting for the result of the analysis, the test is cancelled. +Some clients are configured to close their connection if no response is received within a certain timeout. +An analysis takes a long time to complete so you might need to relax any such client-side timeouts. +On cancellation the analysis attempts to clean up the data it was writing, but it may not be able to remove it all. +The path to the leftover data is recorded in the Elasticsearch logs. +You should verify that this location has been cleaned up correctly. +If there is still leftover data at the specified location, you should manually remove it. + +If the analysis is successful then it detected no incorrect behaviour, but this does not mean that correct behaviour is guaranteed. +The analysis attempts to detect common bugs but it does not offer 100% coverage. +Additionally, it does not test the following: + +* Your repository must perform durable writes. Once a blob has been written it must remain in place until it is deleted, even after a power loss or similar disaster. +* Your repository must not suffer from silent data corruption. Once a blob has been written, its contents must remain unchanged until it is deliberately modified or deleted. +* Your repository must behave correctly even if connectivity from the cluster is disrupted. Reads and writes may fail in this case, but they must not return incorrect results. + +IMPORTANT: An analysis writes a substantial amount of data to your repository and then reads it back again. +This consumes bandwidth on the network between the cluster and the repository, and storage space and I/O bandwidth on the repository itself. +You must ensure this load does not affect other users of these systems. +Analyses respect the repository settings `max_snapshot_bytes_per_sec` and `max_restore_bytes_per_sec` if available and the cluster setting `indices.recovery.max_bytes_per_sec` which you can use to limit the bandwidth they consume. + +NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. + +NOTE: Different versions of Elasticsearch may perform different checks for repository compatibility, with newer versions typically being stricter than older ones. +A storage system that passes repository analysis with one version of Elasticsearch may fail with a different version. +This indicates it behaves incorrectly in ways that the former version did not detect. +You must work with the supplier of your storage system to address the incompatibilities detected by the repository analysis API in any version of Elasticsearch. + +NOTE: This API may not work correctly in a mixed-version cluster. + +*Implementation details* + +NOTE: This section of documentation describes how the repository analysis API works in this version of Elasticsearch, but you should expect the implementation to vary between versions. The request parameters and response format depend on details of the implementation so may also be different in newer versions. + +The analysis comprises a number of blob-level tasks, as set by the `blob_count` parameter and a number of compare-and-exchange operations on linearizable registers, as set by the `register_operation_count` parameter. +These tasks are distributed over the data and master-eligible nodes in the cluster for execution. + +For most blob-level tasks, the executing node first writes a blob to the repository and then instructs some of the other nodes in the cluster to attempt to read the data it just wrote. +The size of the blob is chosen randomly, according to the `max_blob_size` and `max_total_data_size` parameters. +If any of these reads fails then the repository does not implement the necessary read-after-write semantics that Elasticsearch requires. + +For some blob-level tasks, the executing node will instruct some of its peers to attempt to read the data before the writing process completes. +These reads are permitted to fail, but must not return partial data. +If any read returns partial data then the repository does not implement the necessary atomicity semantics that Elasticsearch requires. + +For some blob-level tasks, the executing node will overwrite the blob while its peers are reading it. +In this case the data read may come from either the original or the overwritten blob, but the read operation must not return partial data or a mix of data from the two blobs. +If any of these reads returns partial data or a mix of the two blobs then the repository does not implement the necessary atomicity semantics that Elasticsearch requires for overwrites. + +The executing node will use a variety of different methods to write the blob. +For instance, where applicable, it will use both single-part and multi-part uploads. +Similarly, the reading nodes will use a variety of different methods to read the data back again. +For instance they may read the entire blob from start to end or may read only a subset of the data. + +For some blob-level tasks, the executing node will cancel the write before it is complete. +In this case, it still instructs some of the other nodes in the cluster to attempt to read the blob but all of these reads must fail to find the blob. + +Linearizable registers are special blobs that Elasticsearch manipulates using an atomic compare-and-exchange operation. +This operation ensures correct and strongly-consistent behavior even when the blob is accessed by multiple nodes at the same time. +The detailed implementation of the compare-and-exchange operation on linearizable registers varies by repository type. +Repository analysis verifies that that uncontended compare-and-exchange operations on a linearizable register blob always succeed. +Repository analysis also verifies that contended operations either succeed or report the contention but do not return incorrect results. +If an operation fails due to contention, Elasticsearch retries the operation until it succeeds. +Most of the compare-and-exchange operations performed by repository analysis atomically increment a counter which is represented as an 8-byte blob. +Some operations also verify the behavior on small blobs with sizes other than 8 bytes. + +{ref}/repo-analysis-api.html[Endpoint documentation] [source,ts] ---- -client.snapshot.repositoryAnalyze() +client.snapshot.repositoryAnalyze({ repository }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`repository` (string)*: The name of the repository. +** *`blob_count` (Optional, number)*: The total number of blobs to write to the repository during the test. +For realistic experiments, you should set it to at least `2000`. +** *`concurrency` (Optional, number)*: The number of operations to run concurrently during the test. +** *`detailed` (Optional, boolean)*: Indicates whether to return detailed results, including timing information for every operation performed during the analysis. +If false, it returns only a summary of the analysis. +** *`early_read_node_count` (Optional, number)*: The number of nodes on which to perform an early read operation while writing each blob. +Early read operations are only rarely performed. +** *`max_blob_size` (Optional, number | string)*: The maximum size of a blob to be written during the test. +For realistic experiments, you should set it to at least `2gb`. +** *`max_total_data_size` (Optional, number | string)*: An upper limit on the total size of all the blobs written during the test. +For realistic experiments, you should set it to at least `1tb`. +** *`rare_action_probability` (Optional, number)*: The probability of performing a rare action such as an early read, an overwrite, or an aborted write on each blob. +** *`rarely_abort_writes` (Optional, boolean)*: Indicates whether to rarely cancel writes before they complete. +** *`read_node_count` (Optional, number)*: The number of nodes on which to read a blob after writing. +** *`register_operation_count` (Optional, number)*: The minimum number of linearizable register operations to perform in total. +For realistic experiments, you should set it to at least `100`. +** *`seed` (Optional, number)*: The seed for the pseudo-random number generator used to generate the list of operations performed during the test. +To repeat the same set of operations in multiple experiments, use the same seed in each experiment. +Note that the operations are performed concurrently so might not always happen in the same order on each run. +** *`timeout` (Optional, string | -1 | 0)*: The period of time to wait for the test to complete. +If no response is received before the timeout expires, the test is cancelled and returns an error. [discrete] ==== restore @@ -12320,9 +13631,9 @@ To restore a snapshot, the cluster's global metadata must be writable. Ensure th Before you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API: -``` +---- GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream -``` +---- If no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices. @@ -12513,7 +13824,7 @@ If you specify a cursor, the API only uses the `columnar` and `time_zone` reques It ignores other request body parameters. ** *`fetch_size` (Optional, number)*: The maximum number of rows (or entries) to return in one response. ** *`field_multi_value_leniency` (Optional, boolean)*: If `false`, the API returns an exception when encountering multiple values for a field. -If `true`, the API is lenient and returns the API returns the first value from the array with no guarantee of consistent results. +If `true`, the API is lenient and returns the first value from the array with no guarantee of consistent results. ** *`filter` (Optional, { bool, boosting, common, combined_fields, constant_score, dis_max, distance_feature, exists, function_score, fuzzy, geo_bounding_box, geo_distance, geo_polygon, geo_shape, has_child, has_parent, ids, intervals, knn, match, match_all, match_bool_prefix, match_none, match_phrase, match_phrase_prefix, more_like_this, multi_match, nested, parent_id, percolate, pinned, prefix, query_string, range, rank_feature, regexp, rule, script, script_score, semantic, shape, simple_query_string, span_containing, span_field_masking, span_first, span_multi, span_near, span_not, span_or, span_term, span_within, sparse_vector, term, terms, terms_set, text_expansion, weighted_tokens, wildcard, wrapper, type })*: The Elasticsearch query DSL for additional filtering. ** *`index_using_frozen` (Optional, boolean)*: If `true`, the search can run on frozen indices. ** *`keep_alive` (Optional, string | -1 | 0)*: The retention period for an async or saved synchronous search. @@ -12744,6 +14055,10 @@ client.synonyms.putSynonymRule({ set_id, rule_id, synonyms }) [discrete] ==== cancel Cancel a task. + +WARNING: The task management API is new and should still be considered a beta feature. +The API may change in ways that are not backwards compatible. + A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away. It is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation. The get task information API will continue to list these cancelled tasks until they complete. @@ -12762,17 +14077,22 @@ client.tasks.cancel({ ... }) ==== Arguments * *Request (object):* -** *`task_id` (Optional, string | number)*: ID of the task. -** *`actions` (Optional, string | string[])*: List or wildcard expression of actions used to limit the request. -** *`nodes` (Optional, string[])*: List of node IDs or names used to limit the request. -** *`parent_task_id` (Optional, string)*: Parent task ID used to limit the tasks. -** *`wait_for_completion` (Optional, boolean)*: Should the request block until the cancellation of the task and its descendant tasks is completed. Defaults to false +** *`task_id` (Optional, string | number)*: The task identifier. +** *`actions` (Optional, string | string[])*: A list or wildcard expression of actions that is used to limit the request. +** *`nodes` (Optional, string[])*: A list of node IDs or names that is used to limit the request. +** *`parent_task_id` (Optional, string)*: A parent task ID that is used to limit the tasks. +** *`wait_for_completion` (Optional, boolean)*: If true, the request blocks until all found tasks are complete. [discrete] ==== get Get task information. Get information about a task currently running in the cluster. +WARNING: The task management API is new and should still be considered a beta feature. +The API may change in ways that are not backwards compatible. + +If the task identifier is not found, a 404 response code indicates that there are no resources that match the request. + {ref}/tasks.html[Endpoint documentation] [source,ts] ---- @@ -12783,8 +14103,8 @@ client.tasks.get({ task_id }) ==== Arguments * *Request (object):* -** *`task_id` (string)*: ID of the task. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. +** *`task_id` (string)*: The task identifier. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. ** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks until the task has completed. @@ -12793,6 +14113,63 @@ If no response is received before the timeout expires, the request fails and ret Get all tasks. Get information about the tasks currently running on one or more nodes in the cluster. +WARNING: The task management API is new and should still be considered a beta feature. +The API may change in ways that are not backwards compatible. + +**Identifying running tasks** + +The `X-Opaque-Id header`, when provided on the HTTP request header, is going to be returned as a header in the response as well as in the headers field for in the task information. +This enables you to track certain calls or associate certain tasks with the client that started them. +For example: + +---- +curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents" +---- + +The API returns the following result: + +---- +HTTP/1.1 200 OK +X-Opaque-Id: 123456 +content-type: application/json; charset=UTF-8 +content-length: 831 + +{ + "tasks" : { + "u5lcZHqcQhu-rUoFaqDphA:45" : { + "node" : "u5lcZHqcQhu-rUoFaqDphA", + "id" : 45, + "type" : "transport", + "action" : "cluster:monitor/tasks/lists", + "start_time_in_millis" : 1513823752749, + "running_time_in_nanos" : 293139, + "cancellable" : false, + "headers" : { + "X-Opaque-Id" : "123456" + }, + "children" : [ + { + "node" : "u5lcZHqcQhu-rUoFaqDphA", + "id" : 46, + "type" : "direct", + "action" : "cluster:monitor/tasks/lists[n]", + "start_time_in_millis" : 1513823752750, + "running_time_in_nanos" : 92133, + "cancellable" : false, + "parent_task_id" : "u5lcZHqcQhu-rUoFaqDphA:45", + "headers" : { + "X-Opaque-Id" : "123456" + } + } + ] + } + } + } +---- +In this example, `X-Opaque-Id: 123456` is the ID as a part of the response header. +The `X-Opaque-Id` in the task `headers` is the ID for the task that was initiated by the REST request. +The `X-Opaque-Id` in the children `headers` is the child task of the task that was initiated by the REST request. + {ref}/tasks.html[Endpoint documentation] [source,ts] ---- @@ -12803,14 +14180,19 @@ client.tasks.list({ ... }) ==== Arguments * *Request (object):* -** *`actions` (Optional, string | string[])*: List or wildcard expression of actions used to limit the request. -** *`detailed` (Optional, boolean)*: If `true`, the response includes detailed information about shard recoveries. +** *`actions` (Optional, string | string[])*: A list or wildcard expression of actions used to limit the request. +For example, you can use `cluser:*` to retrieve all cluster-related tasks. +** *`detailed` (Optional, boolean)*: If `true`, the response includes detailed information about the running tasks. This information is useful to distinguish tasks from each other but is more costly to run. -** *`group_by` (Optional, Enum("nodes" | "parents" | "none"))*: Key used to group tasks in the response. -** *`nodes` (Optional, string | string[])*: List of node IDs or names used to limit returned information. -** *`parent_task_id` (Optional, string)*: Parent task ID used to limit returned information. To return all tasks, omit this parameter or use a value of `-1`. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. +** *`group_by` (Optional, Enum("nodes" | "parents" | "none"))*: A key that is used to group tasks in the response. +The task lists can be grouped either by nodes or by parent tasks. +** *`nodes` (Optional, string | string[])*: A list of node IDs or names that is used to limit the returned information. +** *`parent_task_id` (Optional, string)*: A parent task identifier that is used to limit returned information. +To return all tasks, omit this parameter or use a value of `-1`. +If the parent task is not found, the API does not return a 404 response code. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for each node to respond. +If a node does not respond before its timeout expires, the response does not include its information. +However, timed out nodes are included in the `node_failures` property. ** *`wait_for_completion` (Optional, boolean)*: If `true`, the request blocks until the operation is complete. [discrete] @@ -13235,9 +14617,9 @@ wildcard expression. You can get information for all transforms by using ``. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no transforms that match. -2. Contains the _all string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains wildcard expressions and there are no transforms that match. +. Contains the _all string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. If this parameter is false, the request returns a 404 status code when there are no matches or only partial matches. @@ -13268,9 +14650,9 @@ wildcard expression. You can get information for all transforms by using ``. ** *`allow_no_match` (Optional, boolean)*: Specifies what to do when the request: -1. Contains wildcard expressions and there are no transforms that match. -2. Contains the _all string or no identifiers and there are no matches. -3. Contains wildcard expressions and there are only partial matches. +. Contains wildcard expressions and there are no transforms that match. +. Contains the _all string or no identifiers and there are no matches. +. Contains wildcard expressions and there are only partial matches. If this parameter is false, the request returns a 404 status code when there are no matches or only partial matches. @@ -13397,6 +14779,7 @@ client.transform.resetTransform({ transform_id }) hyphens, and underscores. It has a 64 character limit and must start and end with alphanumeric characters. ** *`force` (Optional, boolean)*: If this value is `true`, the transform is reset regardless of its current state. If it's `false`, the transform must be stopped before it can be reset. +** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. [discrete] ==== schedule_now_transform @@ -13797,9 +15180,14 @@ Start the Watcher service if it is not already running. {ref}/watcher-api-start.html[Endpoint documentation] [source,ts] ---- -client.watcher.start() +client.watcher.start({ ... }) ---- +[discrete] +==== Arguments + +* *Request (object):* +** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. [discrete] ==== stats diff --git a/src/api/api/bulk.ts b/src/api/api/bulk.ts index 06bdae72c..1ed252e37 100644 --- a/src/api/api/bulk.ts +++ b/src/api/api/bulk.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Bulk index or delete documents. Performs multiple indexing or delete operations in a single API call. This reduces overhead and can greatly increase indexing speed. + * Bulk index or delete documents. Perform multiple `index`, `create`, `delete`, and `update` actions in a single request. This reduces overhead and can greatly increase indexing speed. If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: * To use the `create` action, you must have the `create_doc`, `create`, `index`, or `write` index privilege. Data streams support only the `create` action. * To use the `index` action, you must have the `create`, `index`, or `write` index privilege. * To use the `delete` action, you must have the `delete` or `write` index privilege. * To use the `update` action, you must have the `index` or `write` index privilege. * To automatically create a data stream or index with a bulk API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. * To make the result of a bulk operation visible to search using the `refresh` parameter, you must have the `maintenance` or `manage` index privilege. Automatic data stream creation requires a matching index template with data stream enabled. The actions are specified in the request body using a newline delimited JSON (NDJSON) structure: ``` action_and_meta_data\n optional_source\n action_and_meta_data\n optional_source\n .... action_and_meta_data\n optional_source\n ``` The `index` and `create` actions expect a source on the next line and have the same semantics as the `op_type` parameter in the standard index API. A `create` action fails if a document with the same ID already exists in the target An `index` action adds or replaces a document as necessary. NOTE: Data streams support only the `create` action. To update or delete a document in a data stream, you must target the backing index containing the document. An `update` action expects that the partial doc, upsert, and script and its options are specified on the next line. A `delete` action does not expect a source on the next line and has the same semantics as the standard delete API. NOTE: The final line of data must end with a newline character (`\n`). Each newline character may be preceded by a carriage return (`\r`). When sending NDJSON data to the `_bulk` endpoint, use a `Content-Type` header of `application/json` or `application/x-ndjson`. Because this format uses literal newline characters (`\n`) as delimiters, make sure that the JSON actions and sources are not pretty printed. If you provide a target in the request path, it is used for any actions that don't explicitly specify an `_index` argument. A note on the format: the idea here is to make processing as fast as possible. As some of the actions are redirected to other shards on other nodes, only `action_meta_data` is parsed on the receiving node side. Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible. There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch. **Client suppport for bulk requests** Some of the officially supported clients provide helpers to assist with bulk requests and reindexing: * Go: Check out `esutil.BulkIndexer` * Perl: Check out `Search::Elasticsearch::Client::5_0::Bulk` and `Search::Elasticsearch::Client::5_0::Scroll` * Python: Check out `elasticsearch.helpers.*` * JavaScript: Check out `client.helpers.*` * .NET: Check out `BulkAllObservable` * PHP: Check out bulk indexing. **Submitting bulk requests with cURL** If you're providing text file input to `curl`, you must use the `--data-binary` flag instead of plain `-d`. The latter doesn't preserve newlines. For example: ``` $ cat requests { "index" : { "_index" : "test", "_id" : "1" } } { "field1" : "value1" } $ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo {"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]} ``` **Optimistic concurrency control** Each `index` and `delete` action within a bulk API call may include the `if_seq_no` and `if_primary_term` parameters in their respective action and meta data lines. The `if_seq_no` and `if_primary_term` parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details. **Versioning** Each bulk item can include the version value using the `version` field. It automatically follows the behavior of the index or delete operation based on the `_version` mapping. It also support the `version_type`. **Routing** Each bulk item can include the routing value using the `routing` field. It automatically follows the behavior of the index or delete operation based on the `_routing` mapping. NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. **Wait for active shards** When making bulk calls, you can set the `wait_for_active_shards` parameter to require a minimum number of shard copies to be active before starting to process the bulk request. **Refresh** Control when the changes made by this request are visible to search. NOTE: Only the shards that receive the bulk request will be affected by refresh. Imagine a `_bulk?refresh=wait_for` request with three documents in it that happen to be routed to different shards in an index with five shards. The request will only wait for those three shards to refresh. The other two shards that make up the index do not participate in the `_bulk` request at all. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-bulk.html | Elasticsearch API documentation} */ export default async function BulkApi (this: That, params: T.BulkRequest | TB.BulkRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/cat.ts b/src/api/api/cat.ts index 0ed45cc06..a013e291a 100644 --- a/src/api/api/cat.ts +++ b/src/api/api/cat.ts @@ -45,7 +45,7 @@ export default class Cat { } /** - * Get aliases. Retrieves the cluster’s index aliases, including filter and routing information. The API does not return data stream aliases. CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. + * Get aliases. Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases. IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-alias.html | Elasticsearch API documentation} */ async aliases (this: That, params?: T.CatAliasesRequest | TB.CatAliasesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -85,7 +85,7 @@ export default class Cat { } /** - * Provides a snapshot of the number of shards allocated to each data node and their disk space. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. + * Get shard allocation information. Get a snapshot of the number of shards allocated to each data node and their disk space. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-allocation.html | Elasticsearch API documentation} */ async allocation (this: That, params?: T.CatAllocationRequest | TB.CatAllocationRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -125,7 +125,7 @@ export default class Cat { } /** - * Get component templates. Returns information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API. + * Get component templates. Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-component-templates.html | Elasticsearch API documentation} */ async componentTemplates (this: That, params?: T.CatComponentTemplatesRequest | TB.CatComponentTemplatesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -165,7 +165,7 @@ export default class Cat { } /** - * Get a document count. Provides quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process. CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API. + * Get a document count. Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-count.html | Elasticsearch API documentation} */ async count (this: That, params?: T.CatCountRequest | TB.CatCountRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -205,7 +205,7 @@ export default class Cat { } /** - * Returns the amount of heap memory currently used by the field data cache on every data node in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes stats API. + * Get field data cache information. Get the amount of heap memory currently used by the field data cache on every data node in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes stats API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-fielddata.html | Elasticsearch API documentation} */ async fielddata (this: That, params?: T.CatFielddataRequest | TB.CatFielddataRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -245,7 +245,7 @@ export default class Cat { } /** - * Returns the health status of a cluster, similar to the cluster health API. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: `HH:MM:SS`, which is human-readable but includes no date information; `Unix epoch time`, which is machine-sortable and includes date information. The latter format is useful for cluster recoveries that take multiple days. You can use the cat health API to verify cluster health across multiple nodes. You also can use the API to track the recovery of a large cluster over a longer period of time. + * Get the cluster health status. IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: `HH:MM:SS`, which is human-readable but includes no date information; `Unix epoch time`, which is machine-sortable and includes date information. The latter format is useful for cluster recoveries that take multiple days. You can use the cat health API to verify cluster health across multiple nodes. You also can use the API to track the recovery of a large cluster over a longer period of time. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-health.html | Elasticsearch API documentation} */ async health (this: That, params?: T.CatHealthRequest | TB.CatHealthRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -275,7 +275,7 @@ export default class Cat { } /** - * Get CAT help. Returns help for the CAT APIs. + * Get CAT help. Get help for the CAT APIs. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat.html | Elasticsearch API documentation} */ async help (this: That, params?: T.CatHelpRequest | TB.CatHelpRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -305,7 +305,7 @@ export default class Cat { } /** - * Get index information. Returns high-level information about indices in a cluster, including backing indices for data streams. Use this request to get the following information for each index in a cluster: - shard count - document count - deleted document count - primary store size - total store size of all shards, including shard replicas These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. To get an accurate count of Elasticsearch documents, use the cat count or count APIs. CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use an index endpoint. + * Get index information. Get high-level information about indices in a cluster, including backing indices for data streams. Use this request to get the following information for each index in a cluster: - shard count - document count - deleted document count - primary store size - total store size of all shards, including shard replicas These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. To get an accurate count of Elasticsearch documents, use the cat count or count APIs. CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use an index endpoint. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-indices.html | Elasticsearch API documentation} */ async indices (this: That, params?: T.CatIndicesRequest | TB.CatIndicesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -345,7 +345,7 @@ export default class Cat { } /** - * Returns information about the master node, including the ID, bound IP address, and name. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. + * Get master node information. Get information about the master node, including the ID, bound IP address, and name. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-master.html | Elasticsearch API documentation} */ async master (this: That, params?: T.CatMasterRequest | TB.CatMasterRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -375,7 +375,7 @@ export default class Cat { } /** - * Get data frame analytics jobs. Returns configuration and usage information about data frame analytics jobs. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API. + * Get data frame analytics jobs. Get configuration and usage information about data frame analytics jobs. IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-dfanalytics.html | Elasticsearch API documentation} */ async mlDataFrameAnalytics (this: That, params?: T.CatMlDataFrameAnalyticsRequest | TB.CatMlDataFrameAnalyticsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -415,7 +415,7 @@ export default class Cat { } /** - * Get datafeeds. Returns configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API. + * Get datafeeds. Get configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-datafeeds.html | Elasticsearch API documentation} */ async mlDatafeeds (this: That, params?: T.CatMlDatafeedsRequest | TB.CatMlDatafeedsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -455,7 +455,7 @@ export default class Cat { } /** - * Get anomaly detection jobs. Returns configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get anomaly detection job statistics API. + * Get anomaly detection jobs. Get configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get anomaly detection job statistics API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-anomaly-detectors.html | Elasticsearch API documentation} */ async mlJobs (this: That, params?: T.CatMlJobsRequest | TB.CatMlJobsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -495,7 +495,7 @@ export default class Cat { } /** - * Get trained models. Returns configuration and usage information about inference trained models. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API. + * Get trained models. Get configuration and usage information about inference trained models. IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-trained-model.html | Elasticsearch API documentation} */ async mlTrainedModels (this: That, params?: T.CatMlTrainedModelsRequest | TB.CatMlTrainedModelsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -535,7 +535,7 @@ export default class Cat { } /** - * Returns information about custom node attributes. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. + * Get node attribute information. Get information about custom node attributes. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-nodeattrs.html | Elasticsearch API documentation} */ async nodeattrs (this: That, params?: T.CatNodeattrsRequest | TB.CatNodeattrsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -565,7 +565,7 @@ export default class Cat { } /** - * Returns information about the nodes in a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. + * Get node information. Get information about the nodes in a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-nodes.html | Elasticsearch API documentation} */ async nodes (this: That, params?: T.CatNodesRequest | TB.CatNodesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -595,7 +595,7 @@ export default class Cat { } /** - * Returns cluster-level changes that have not yet been executed. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API. + * Get pending task information. Get information about cluster-level changes that have not yet taken effect. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-pending-tasks.html | Elasticsearch API documentation} */ async pendingTasks (this: That, params?: T.CatPendingTasksRequest | TB.CatPendingTasksRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -625,7 +625,7 @@ export default class Cat { } /** - * Returns a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. + * Get plugin information. Get a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-plugins.html | Elasticsearch API documentation} */ async plugins (this: That, params?: T.CatPluginsRequest | TB.CatPluginsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -655,7 +655,7 @@ export default class Cat { } /** - * Returns information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API. + * Get shard recovery information. Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-recovery.html | Elasticsearch API documentation} */ async recovery (this: That, params?: T.CatRecoveryRequest | TB.CatRecoveryRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -695,7 +695,7 @@ export default class Cat { } /** - * Returns the snapshot repositories for a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API. + * Get snapshot repository information. Get a list of snapshot repositories for a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-repositories.html | Elasticsearch API documentation} */ async repositories (this: That, params?: T.CatRepositoriesRequest | TB.CatRepositoriesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -725,7 +725,7 @@ export default class Cat { } /** - * Returns low-level information about the Lucene segments in index shards. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API. + * Get segment information. Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-segments.html | Elasticsearch API documentation} */ async segments (this: That, params?: T.CatSegmentsRequest | TB.CatSegmentsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -765,7 +765,7 @@ export default class Cat { } /** - * Returns information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. + * Get shard information. Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-shards.html | Elasticsearch API documentation} */ async shards (this: That, params?: T.CatShardsRequest | TB.CatShardsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -805,7 +805,7 @@ export default class Cat { } /** - * Returns information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API. + * Get snapshot information. Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-snapshots.html | Elasticsearch API documentation} */ async snapshots (this: That, params?: T.CatSnapshotsRequest | TB.CatSnapshotsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -845,7 +845,7 @@ export default class Cat { } /** - * Returns information about tasks currently executing in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API. + * Get task information. Get information about tasks currently running in the cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the task management API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/tasks.html | Elasticsearch API documentation} */ async tasks (this: That, params?: T.CatTasksRequest | TB.CatTasksRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -875,7 +875,7 @@ export default class Cat { } /** - * Returns information about index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get index template API. + * Get index template information. Get information about the index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get index template API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-templates.html | Elasticsearch API documentation} */ async templates (this: That, params?: T.CatTemplatesRequest | TB.CatTemplatesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -915,7 +915,7 @@ export default class Cat { } /** - * Returns thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. + * Get thread pool statistics. Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-thread-pool.html | Elasticsearch API documentation} */ async threadPool (this: That, params?: T.CatThreadPoolRequest | TB.CatThreadPoolRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -955,7 +955,7 @@ export default class Cat { } /** - * Get transforms. Returns configuration and usage information about transforms. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get transform statistics API. + * Get transform information. Get configuration and usage information about transforms. CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get transform statistics API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/cat-transforms.html | Elasticsearch API documentation} */ async transforms (this: That, params?: T.CatTransformsRequest | TB.CatTransformsRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/count.ts b/src/api/api/count.ts index a43c454e1..fb3cdcc6c 100644 --- a/src/api/api/count.ts +++ b/src/api/api/count.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Count search results. Get the number of documents matching a query. + * Count search results. Get the number of documents matching a query. The query can either be provided using a simple query string as a parameter or using the Query DSL defined within the request body. The latter must be nested in a `query` key, which is the same as the search API. The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices. The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/search-count.html | Elasticsearch API documentation} */ export default async function CountApi (this: That, params?: T.CountRequest | TB.CountRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/create.ts b/src/api/api/create.ts index 96ab1b648..b6173c933 100644 --- a/src/api/api/create.ts +++ b/src/api/api/create.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Index a document. Adds a JSON document to the specified data stream or index and makes it searchable. If the target is an index and the document already exists, the request updates the document and increments its version. + * Create a new document in the index. You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs Using `_create` guarantees that the document is indexed only if it does not already exist. It returns a 409 response when a document with a same ID already exists in the index. To update an existing document, you must use the `//_doc/` API. If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: * To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege. * To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. Automatic data stream creation requires a matching index template with data stream enabled. **Automatically create data streams and indices** If the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream. If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates. NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation. If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed. Automatic index creation is controlled by the `action.auto_create_index` setting. If it is `true`, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow. NOTE: The `action.auto_create_index` setting affects the automatic creation of indices only. It does not affect the creation of data streams. **Routing** By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter. When setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted. NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. **Distributed** The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas. **Active shards** To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`). This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. To alter this behavior per operation, use the `wait_for_active_shards request` parameter. Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1). Specifying a negative value or a number greater than the number of shard copies will throw an error. For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard. It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-index_.html | Elasticsearch API documentation} */ export default async function CreateApi (this: That, params: T.CreateRequest | TB.CreateRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/delete.ts b/src/api/api/delete.ts index 8ab50a2cc..c67759f1b 100644 --- a/src/api/api/delete.ts +++ b/src/api/api/delete.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Delete a document. Removes a JSON document from the specified index. + * Delete a document. Remove a JSON document from the specified index. NOTE: You cannot send deletion requests directly to a data stream. To delete a document in a data stream, you must target the backing index containing the document. **Optimistic concurrency control** Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters. If a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`. **Versioning** Each document indexed is versioned. When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. Every write operation run on a document, deletes included, causes its version to be incremented. The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. The length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting. **Routing** If routing is used during indexing, the routing value also needs to be specified to delete a document. If the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request. For example: ``` DELETE /my-index-000001/_doc/1?routing=shard-1 ``` This request deletes the document with ID 1, but it is routed based on the user. The document is not deleted if the correct routing is not specified. **Distributed** The delete operation gets hashed into a specific shard ID. It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-delete.html | Elasticsearch API documentation} */ export default async function DeleteApi (this: That, params: T.DeleteRequest | TB.DeleteRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/delete_by_query.ts b/src/api/api/delete_by_query.ts index 4a307801f..fe0f531f7 100644 --- a/src/api/api/delete_by_query.ts +++ b/src/api/api/delete_by_query.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Delete documents. Deletes documents that match the specified query. + * Delete documents. Deletes documents that match the specified query. If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias: * `read` * `delete` or `write` You can specify the query criteria in the request URI or the request body using the same syntax as the search API. When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails. NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number. While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. A bulk delete request is performed for each batch of matching documents. If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. Any delete requests that completed successfully still stick, they are not rolled back. You can opt to count version conflicts instead of halting and returning by setting `conflicts` to `proceed`. Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than `max_docs` until it has successfully deleted `max_docs documents`, or it has gone through every document in the source query. **Throttling delete requests** To control the rate at which delete by query issues batches of delete operations, you can set `requests_per_second` to any positive decimal number. This pads each batch with a wait time to throttle the rate. Set `requests_per_second` to `-1` to disable throttling. Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. The padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing. By default the batch size is `1000`, so if `requests_per_second` is set to `500`: ``` target_time = 1000 / 500 per second = 2 seconds wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds ``` Since the batch is issued as a single `_bulk` request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. This is "bursty" instead of "smooth". **Slicing** Delete by query supports sliced scroll to parallelize the delete process. This can improve efficiency and provide a convenient way to break the request down into smaller parts. Setting `slices` to `auto` lets Elasticsearch choose the number of slices to use. This setting will use one slice per shard, up to a certain limit. If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. Adding slices to the delete by query operation creates sub-requests which means it has some quirks: * You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices. * Fetching the status of the task for the request with slices only contains the status of completed slices. * These sub-requests are individually addressable for things like cancellation and rethrottling. * Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally. * Canceling the request with `slices` will cancel each sub-request. * Due to the nature of `slices` each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution. * Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being deleted. * Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time. If you're slicing manually or otherwise tuning automatic slicing, keep in mind that: * Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many `slices` hurts performance. Setting `slices` higher than the number of shards generally does not improve efficiency and adds overhead. * Delete performance scales linearly across available resources with the number of slices. Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources. **Cancel a delete by query operation** Any delete by query can be canceled using the task cancel API. For example: ``` POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel ``` The task ID can be found by using the get tasks API. Cancellation should happen quickly but might take a few seconds. The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-delete-by-query.html | Elasticsearch API documentation} */ export default async function DeleteByQueryApi (this: That, params: T.DeleteByQueryRequest | TB.DeleteByQueryRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/delete_by_query_rethrottle.ts b/src/api/api/delete_by_query_rethrottle.ts index 1a625dd09..cbf7d6bda 100644 --- a/src/api/api/delete_by_query_rethrottle.ts +++ b/src/api/api/delete_by_query_rethrottle.ts @@ -40,7 +40,7 @@ interface That { transport: Transport } /** * Throttle a delete by query operation. Change the number of requests per second for a particular delete by query operation. Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts. - * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-delete-by-query.html | Elasticsearch API documentation} + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-delete-by-query.html#docs-delete-by-query-rethrottle | Elasticsearch API documentation} */ export default async function DeleteByQueryRethrottleApi (this: That, params: T.DeleteByQueryRethrottleRequest | TB.DeleteByQueryRethrottleRequest, options?: TransportRequestOptionsWithOutMeta): Promise export default async function DeleteByQueryRethrottleApi (this: That, params: T.DeleteByQueryRethrottleRequest | TB.DeleteByQueryRethrottleRequest, options?: TransportRequestOptionsWithMeta): Promise> diff --git a/src/api/api/esql.ts b/src/api/api/esql.ts index 4c8d671ed..f965ba4d3 100644 --- a/src/api/api/esql.ts +++ b/src/api/api/esql.ts @@ -45,22 +45,34 @@ export default class Esql { } /** - * Executes an ESQL request asynchronously + * Run an async ES|QL query. Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available. The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/esql-async-query-api.html | Elasticsearch API documentation} */ - async asyncQuery (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithOutMeta): Promise - async asyncQuery (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithMeta): Promise> - async asyncQuery (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise - async asyncQuery (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise { + async asyncQuery (this: That, params: T.EsqlAsyncQueryRequest | TB.EsqlAsyncQueryRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async asyncQuery (this: That, params: T.EsqlAsyncQueryRequest | TB.EsqlAsyncQueryRequest, options?: TransportRequestOptionsWithMeta): Promise> + async asyncQuery (this: That, params: T.EsqlAsyncQueryRequest | TB.EsqlAsyncQueryRequest, options?: TransportRequestOptions): Promise + async asyncQuery (this: That, params: T.EsqlAsyncQueryRequest | TB.EsqlAsyncQueryRequest, options?: TransportRequestOptions): Promise { const acceptedPath: string[] = [] + const acceptedBody: string[] = ['columnar', 'filter', 'locale', 'params', 'profile', 'query', 'tables'] const querystring: Record = {} - const body = undefined + // @ts-expect-error + const userBody: any = params?.body + let body: Record | string + if (typeof userBody === 'string') { + body = userBody + } else { + body = userBody != null ? { ...userBody } : undefined + } - params = params ?? {} for (const key in params) { - if (acceptedPath.includes(key)) { + if (acceptedBody.includes(key)) { + body = body ?? {} + // @ts-expect-error + body[key] = params[key] + } else if (acceptedPath.includes(key)) { continue } else if (key !== 'body') { + // @ts-expect-error querystring[key] = params[key] } } @@ -74,22 +86,54 @@ export default class Esql { } /** - * Retrieves the results of a previously submitted async query request given its ID. + * Delete an async ES|QL query. If the query is still running, it is cancelled. Otherwise, the stored results are deleted. If the Elasticsearch security features are enabled, only the following users can use this API to delete a query: * The authenticated user that submitted the original query request * Users with the `cancel_task` cluster privilege + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/esql-async-query-delete-api.html | Elasticsearch API documentation} + */ + async asyncQueryDelete (this: That, params: T.EsqlAsyncQueryDeleteRequest | TB.EsqlAsyncQueryDeleteRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async asyncQueryDelete (this: That, params: T.EsqlAsyncQueryDeleteRequest | TB.EsqlAsyncQueryDeleteRequest, options?: TransportRequestOptionsWithMeta): Promise> + async asyncQueryDelete (this: That, params: T.EsqlAsyncQueryDeleteRequest | TB.EsqlAsyncQueryDeleteRequest, options?: TransportRequestOptions): Promise + async asyncQueryDelete (this: That, params: T.EsqlAsyncQueryDeleteRequest | TB.EsqlAsyncQueryDeleteRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['id'] + const querystring: Record = {} + const body = undefined + + for (const key in params) { + if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + const method = 'DELETE' + const path = `/_query/async/${encodeURIComponent(params.id.toString())}` + const meta: TransportRequestMetadata = { + name: 'esql.async_query_delete', + pathParts: { + id: params.id + } + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } + + /** + * Get async ES|QL query results. Get the current status and available results or stored results for an ES|QL asynchronous query. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/esql-async-query-get-api.html | Elasticsearch API documentation} */ - async asyncQueryGet (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithOutMeta): Promise - async asyncQueryGet (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithMeta): Promise> - async asyncQueryGet (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise - async asyncQueryGet (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise { + async asyncQueryGet (this: That, params: T.EsqlAsyncQueryGetRequest | TB.EsqlAsyncQueryGetRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async asyncQueryGet (this: That, params: T.EsqlAsyncQueryGetRequest | TB.EsqlAsyncQueryGetRequest, options?: TransportRequestOptionsWithMeta): Promise> + async asyncQueryGet (this: That, params: T.EsqlAsyncQueryGetRequest | TB.EsqlAsyncQueryGetRequest, options?: TransportRequestOptions): Promise + async asyncQueryGet (this: That, params: T.EsqlAsyncQueryGetRequest | TB.EsqlAsyncQueryGetRequest, options?: TransportRequestOptions): Promise { const acceptedPath: string[] = ['id'] const querystring: Record = {} const body = undefined - params = params ?? {} for (const key in params) { if (acceptedPath.includes(key)) { continue } else if (key !== 'body') { + // @ts-expect-error querystring[key] = params[key] } } diff --git a/src/api/api/exists.ts b/src/api/api/exists.ts index f97d7f0a3..375a48320 100644 --- a/src/api/api/exists.ts +++ b/src/api/api/exists.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Check a document. Checks if a specified document exists. + * Check a document. Verify that a document exists. For example, check to see if a document with the `_id` 0 exists: ``` HEAD my-index-000001/_doc/0 ``` If the document exists, the API returns a status code of `200 - OK`. If the document doesn’t exist, the API returns `404 - Not Found`. **Versioning support** You can use the `version` parameter to check the document only if its current version is equal to the specified one. Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. The old version of the document doesn't disappear immediately, although you won't be able to access it. Elasticsearch cleans up deleted documents in the background as you continue to index more data. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-get.html | Elasticsearch API documentation} */ export default async function ExistsApi (this: That, params: T.ExistsRequest | TB.ExistsRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/exists_source.ts b/src/api/api/exists_source.ts index b748cbc42..41e1cd2bd 100644 --- a/src/api/api/exists_source.ts +++ b/src/api/api/exists_source.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Check for a document source. Checks if a document's `_source` is stored. + * Check for a document source. Check whether a document source exists in an index. For example: ``` HEAD my-index-000001/_source/1 ``` A document's source is not available if it is disabled in the mapping. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-get.html | Elasticsearch API documentation} */ export default async function ExistsSourceApi (this: That, params: T.ExistsSourceRequest | TB.ExistsSourceRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/get.ts b/src/api/api/get.ts index bc5793f7f..4fb99932a 100644 --- a/src/api/api/get.ts +++ b/src/api/api/get.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Get a document by its ID. Retrieves the document with the specified ID from an index. + * Get a document by its ID. Get a document and its source or stored fields from an index. By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search). In the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields. To turn off realtime behavior, set the `realtime` parameter to false. **Source filtering** By default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off. You can turn off `_source` retrieval by using the `_source` parameter: ``` GET my-index-000001/_doc/0?_source=false ``` If you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields. This can be helpful with large documents where partial retrieval can save on network overhead Both parameters take a comma separated list of fields or wildcard expressions. For example: ``` GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities ``` If you only want to specify includes, you can use a shorter notation: ``` GET my-index-000001/_doc/0?_source=*.id ``` **Routing** If routing is used during indexing, the routing value also needs to be specified to retrieve a document. For example: ``` GET my-index-000001/_doc/2?routing=user1 ``` This request gets the document with ID 2, but it is routed based on the user. The document is not fetched if the correct routing is not specified. **Distributed** The GET operation is hashed into a specific shard ID. It is then redirected to one of the replicas within that shard ID and returns the result. The replicas are the primary shard and its replicas within that shard ID group. This means that the more replicas you have, the better your GET scaling will be. **Versioning support** You can use the `version` parameter to retrieve the document only if its current version is equal to the specified one. Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. The old version of the document doesn't disappear immediately, although you won't be able to access it. Elasticsearch cleans up deleted documents in the background as you continue to index more data. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-get.html | Elasticsearch API documentation} */ export default async function GetApi (this: That, params: T.GetRequest | TB.GetRequest, options?: TransportRequestOptionsWithOutMeta): Promise> diff --git a/src/api/api/get_source.ts b/src/api/api/get_source.ts index 75568ce77..1b1dcd987 100644 --- a/src/api/api/get_source.ts +++ b/src/api/api/get_source.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Get a document's source. Returns the source of a document. + * Get a document's source. Get the source of a document. For example: ``` GET my-index-000001/_source/1 ``` You can use the source filtering parameters to control which parts of the `_source` are returned: ``` GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities ``` * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-get.html | Elasticsearch API documentation} */ export default async function GetSourceApi (this: That, params: T.GetSourceRequest | TB.GetSourceRequest, options?: TransportRequestOptionsWithOutMeta): Promise> diff --git a/src/api/api/index.ts b/src/api/api/index.ts index 628e02705..3003f0d9f 100644 --- a/src/api/api/index.ts +++ b/src/api/api/index.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Index a document. Adds a JSON document to the specified data stream or index and makes it searchable. If the target is an index and the document already exists, the request updates the document and increments its version. + * Create or update a document in an index. Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version. NOTE: You cannot use this API to send update requests for existing documents in a data stream. If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: * To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege. * To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege. * To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. Automatic data stream creation requires a matching index template with data stream enabled. NOTE: Replica shards might not all be started when an indexing operation returns successfully. By default, only the primary is required. Set `wait_for_active_shards` to change this default behavior. **Automatically create data streams and indices** If the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream. If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates. NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation. If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed. Automatic index creation is controlled by the `action.auto_create_index` setting. If it is `true`, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow. NOTE: The `action.auto_create_index` setting affects the automatic creation of indices only. It does not affect the creation of data streams. **Optimistic concurrency control** Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters. If a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`. **Routing** By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter. When setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted. NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. **Distributed** The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas. **Active shards** To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`). This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. To alter this behavior per operation, use the `wait_for_active_shards request` parameter. Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1). Specifying a negative value or a number greater than the number of shard copies will throw an error. For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard. It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed. **No operation (noop) updates** When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. If this isn't acceptable use the `_update` API with `detect_noop` set to `true`. The `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source. There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates. **Versioning** Each indexed document is given a version number. By default, internal versioning is used that starts at 1 and increments with each update, deletes included. Optionally, the version number can be set to an external value (for example, if maintained in a database). To enable this functionality, `version_type` should be set to `external`. The value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`. NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks. When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example: ``` PUT my-index-000001/_doc/1?version=2&version_type=external { "user": { "id": "elkbee" } } In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-index_.html | Elasticsearch API documentation} */ export default async function IndexApi (this: That, params: T.IndexRequest | TB.IndexRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/indices.ts b/src/api/api/indices.ts index 4aeb13a55..c1f58bfd0 100644 --- a/src/api/api/indices.ts +++ b/src/api/api/indices.ts @@ -129,6 +129,38 @@ export default class Indices { return await this.transport.request({ path, method, querystring, body, meta }, options) } + /** + * Cancel a migration reindex operation. Cancel a migration reindex attempt for a data stream or index. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/migrate-data-stream.html | Elasticsearch API documentation} + */ + async cancelMigrateReindex (this: That, params: T.IndicesCancelMigrateReindexRequest | TB.IndicesCancelMigrateReindexRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async cancelMigrateReindex (this: That, params: T.IndicesCancelMigrateReindexRequest | TB.IndicesCancelMigrateReindexRequest, options?: TransportRequestOptionsWithMeta): Promise> + async cancelMigrateReindex (this: That, params: T.IndicesCancelMigrateReindexRequest | TB.IndicesCancelMigrateReindexRequest, options?: TransportRequestOptions): Promise + async cancelMigrateReindex (this: That, params: T.IndicesCancelMigrateReindexRequest | TB.IndicesCancelMigrateReindexRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['index'] + const querystring: Record = {} + const body = undefined + + for (const key in params) { + if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + const method = 'POST' + const path = `/_migration/reindex/${encodeURIComponent(params.index.toString())}/_cancel` + const meta: TransportRequestMetadata = { + name: 'indices.cancel_migrate_reindex', + pathParts: { + index: params.index + } + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } + /** * Clear the cache. Clear the cache of one or more indices. For data streams, the API clears the caches of the stream's backing indices. By default, the clear cache API clears all caches. To clear only specific caches, use the `fielddata`, `query`, or `request` parameters. To clear the cache only of specific fields, use the `fields` parameter. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/indices-clearcache.html | Elasticsearch API documentation} @@ -322,6 +354,44 @@ export default class Indices { return await this.transport.request({ path, method, querystring, body, meta }, options) } + /** + * Create an index from a source index. Copy the mappings and settings from the source index to a destination index while allowing request settings and mappings to override the source values. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/migrate-data-stream.html | Elasticsearch API documentation} + */ + async createFrom (this: That, params: T.IndicesCreateFromRequest | TB.IndicesCreateFromRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async createFrom (this: That, params: T.IndicesCreateFromRequest | TB.IndicesCreateFromRequest, options?: TransportRequestOptionsWithMeta): Promise> + async createFrom (this: That, params: T.IndicesCreateFromRequest | TB.IndicesCreateFromRequest, options?: TransportRequestOptions): Promise + async createFrom (this: That, params: T.IndicesCreateFromRequest | TB.IndicesCreateFromRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['source', 'dest'] + const acceptedBody: string[] = ['create_from'] + const querystring: Record = {} + // @ts-expect-error + let body: any = params.body ?? undefined + + for (const key in params) { + if (acceptedBody.includes(key)) { + // @ts-expect-error + body = params[key] + } else if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + const method = 'PUT' + const path = `/_create_from/${encodeURIComponent(params.source.toString())}/${encodeURIComponent(params.dest.toString())}` + const meta: TransportRequestMetadata = { + name: 'indices.create_from', + pathParts: { + source: params.source, + dest: params.dest + } + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } + /** * Get data stream stats. Retrieves statistics for one or more data streams. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/data-streams.html | Elasticsearch API documentation} @@ -946,6 +1016,7 @@ export default class Indices { /** * Get aliases. Retrieves information for one or more data stream or index aliases. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/indices-get-alias.html | Elasticsearch API documentation} */ async getAlias (this: That, params?: T.IndicesGetAliasRequest | TB.IndicesGetAliasRequest, options?: TransportRequestOptionsWithOutMeta): Promise async getAlias (this: That, params?: T.IndicesGetAliasRequest | TB.IndicesGetAliasRequest, options?: TransportRequestOptionsWithMeta): Promise> @@ -1212,6 +1283,38 @@ export default class Indices { return await this.transport.request({ path, method, querystring, body, meta }, options) } + /** + * Get the migration reindexing status. Get the status of a migration reindex attempt for a data stream or index. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/migrate-data-stream.html | Elasticsearch API documentation} + */ + async getMigrateReindexStatus (this: That, params: T.IndicesGetMigrateReindexStatusRequest | TB.IndicesGetMigrateReindexStatusRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async getMigrateReindexStatus (this: That, params: T.IndicesGetMigrateReindexStatusRequest | TB.IndicesGetMigrateReindexStatusRequest, options?: TransportRequestOptionsWithMeta): Promise> + async getMigrateReindexStatus (this: That, params: T.IndicesGetMigrateReindexStatusRequest | TB.IndicesGetMigrateReindexStatusRequest, options?: TransportRequestOptions): Promise + async getMigrateReindexStatus (this: That, params: T.IndicesGetMigrateReindexStatusRequest | TB.IndicesGetMigrateReindexStatusRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['index'] + const querystring: Record = {} + const body = undefined + + for (const key in params) { + if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + const method = 'GET' + const path = `/_migration/reindex/${encodeURIComponent(params.index.toString())}/_status` + const meta: TransportRequestMetadata = { + name: 'indices.get_migrate_reindex_status', + pathParts: { + index: params.index + } + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } + /** * Get index settings. Get setting information for one or more indices. For data streams, it returns setting information for the stream's backing indices. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/indices-get-settings.html | Elasticsearch API documentation} @@ -1299,6 +1402,40 @@ export default class Indices { return await this.transport.request({ path, method, querystring, body, meta }, options) } + /** + * Reindex legacy backing indices. Reindex all legacy backing indices for a data stream. This operation occurs in a persistent task. The persistent task ID is returned immediately and the reindexing work is completed in that task. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/migrate-data-stream.html | Elasticsearch API documentation} + */ + async migrateReindex (this: That, params: T.IndicesMigrateReindexRequest | TB.IndicesMigrateReindexRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async migrateReindex (this: That, params: T.IndicesMigrateReindexRequest | TB.IndicesMigrateReindexRequest, options?: TransportRequestOptionsWithMeta): Promise> + async migrateReindex (this: That, params: T.IndicesMigrateReindexRequest | TB.IndicesMigrateReindexRequest, options?: TransportRequestOptions): Promise + async migrateReindex (this: That, params: T.IndicesMigrateReindexRequest | TB.IndicesMigrateReindexRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = [] + const acceptedBody: string[] = ['reindex'] + const querystring: Record = {} + // @ts-expect-error + let body: any = params.body ?? undefined + + for (const key in params) { + if (acceptedBody.includes(key)) { + // @ts-expect-error + body = params[key] + } else if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + const method = 'POST' + const path = '/_migration/reindex' + const meta: TransportRequestMetadata = { + name: 'indices.migrate_reindex' + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } + /** * Convert an index alias to a data stream. Converts an index alias to a data stream. You must have a matching index template that is data stream enabled. The alias must meet the following criteria: The alias must have a write index; All indices for the alias must have a `@timestamp` field mapping of a `date` or `date_nanos` field type; The alias must not have any filters; The alias must not use custom routing. If successful, the request removes the alias and creates a data stream with the same name. The indices for the alias become hidden backing indices for the stream. The write index for the alias becomes the write index for the stream. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/data-streams.html | Elasticsearch API documentation} diff --git a/src/api/api/inference.ts b/src/api/api/inference.ts index 88fd677c0..0ecbd491f 100644 --- a/src/api/api/inference.ts +++ b/src/api/api/inference.ts @@ -226,22 +226,34 @@ export default class Inference { } /** - * Perform streaming inference - * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/post-stream-inference-api.html | Elasticsearch API documentation} + * Perform streaming inference. Get real-time responses for completion tasks by delivering answers incrementally, reducing response times during computation. This API works only with the completion task type. IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs. This API requires the `monitor_inference` cluster privilege (the built-in `inference_admin` and `inference_user` roles grant this privilege). You must use a client that supports streaming. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/stream-inference-api.html | Elasticsearch API documentation} */ - async streamInference (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithOutMeta): Promise - async streamInference (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithMeta): Promise> - async streamInference (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise - async streamInference (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise { + async streamInference (this: That, params: T.InferenceStreamInferenceRequest | TB.InferenceStreamInferenceRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async streamInference (this: That, params: T.InferenceStreamInferenceRequest | TB.InferenceStreamInferenceRequest, options?: TransportRequestOptionsWithMeta): Promise> + async streamInference (this: That, params: T.InferenceStreamInferenceRequest | TB.InferenceStreamInferenceRequest, options?: TransportRequestOptions): Promise + async streamInference (this: That, params: T.InferenceStreamInferenceRequest | TB.InferenceStreamInferenceRequest, options?: TransportRequestOptions): Promise { const acceptedPath: string[] = ['inference_id', 'task_type'] + const acceptedBody: string[] = ['input'] const querystring: Record = {} - const body = undefined + // @ts-expect-error + const userBody: any = params?.body + let body: Record | string + if (typeof userBody === 'string') { + body = userBody + } else { + body = userBody != null ? { ...userBody } : undefined + } - params = params ?? {} for (const key in params) { - if (acceptedPath.includes(key)) { + if (acceptedBody.includes(key)) { + body = body ?? {} + // @ts-expect-error + body[key] = params[key] + } else if (acceptedPath.includes(key)) { continue } else if (key !== 'body') { + // @ts-expect-error querystring[key] = params[key] } } @@ -264,4 +276,101 @@ export default class Inference { } return await this.transport.request({ path, method, querystring, body, meta }, options) } + + /** + * Perform inference on the service using the Unified Schema + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/unified-inference-api.html | Elasticsearch API documentation} + */ + async unifiedInference (this: That, params: T.InferenceUnifiedInferenceRequest | TB.InferenceUnifiedInferenceRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async unifiedInference (this: That, params: T.InferenceUnifiedInferenceRequest | TB.InferenceUnifiedInferenceRequest, options?: TransportRequestOptionsWithMeta): Promise> + async unifiedInference (this: That, params: T.InferenceUnifiedInferenceRequest | TB.InferenceUnifiedInferenceRequest, options?: TransportRequestOptions): Promise + async unifiedInference (this: That, params: T.InferenceUnifiedInferenceRequest | TB.InferenceUnifiedInferenceRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['task_type', 'inference_id'] + const acceptedBody: string[] = ['messages', 'model', 'max_completion_tokens', 'stop', 'temperature', 'tool_choice', 'tools', 'top_p'] + const querystring: Record = {} + // @ts-expect-error + const userBody: any = params?.body + let body: Record | string + if (typeof userBody === 'string') { + body = userBody + } else { + body = userBody != null ? { ...userBody } : undefined + } + + for (const key in params) { + if (acceptedBody.includes(key)) { + body = body ?? {} + // @ts-expect-error + body[key] = params[key] + } else if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + let method = '' + let path = '' + if (params.task_type != null && params.inference_id != null) { + method = 'POST' + path = `/_inference/${encodeURIComponent(params.task_type.toString())}/${encodeURIComponent(params.inference_id.toString())}/_unified` + } else { + method = 'POST' + path = `/_inference/${encodeURIComponent(params.inference_id.toString())}/_unified` + } + const meta: TransportRequestMetadata = { + name: 'inference.unified_inference', + pathParts: { + task_type: params.task_type, + inference_id: params.inference_id + } + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } + + /** + * Update an inference endpoint. Modify `task_settings`, secrets (within `service_settings`), or `num_allocations` for an inference endpoint, depending on the specific endpoint service and `task_type`. IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/update-inference-api.html | Elasticsearch API documentation} + */ + async update (this: That, params: T.InferenceUpdateRequest | TB.InferenceUpdateRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async update (this: That, params: T.InferenceUpdateRequest | TB.InferenceUpdateRequest, options?: TransportRequestOptionsWithMeta): Promise> + async update (this: That, params: T.InferenceUpdateRequest | TB.InferenceUpdateRequest, options?: TransportRequestOptions): Promise + async update (this: That, params: T.InferenceUpdateRequest | TB.InferenceUpdateRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['inference_id', 'task_type'] + const acceptedBody: string[] = ['inference_config'] + const querystring: Record = {} + // @ts-expect-error + let body: any = params.body ?? undefined + + for (const key in params) { + if (acceptedBody.includes(key)) { + // @ts-expect-error + body = params[key] + } else if (acceptedPath.includes(key)) { + continue + } else if (key !== 'body') { + // @ts-expect-error + querystring[key] = params[key] + } + } + + let method = '' + let path = '' + if (params.task_type != null && params.inference_id != null) { + method = 'POST' + path = `/_inference/${encodeURIComponent(params.task_type.toString())}/${encodeURIComponent(params.inference_id.toString())}/_update` + } else { + method = 'POST' + path = `/_inference/${encodeURIComponent(params.inference_id.toString())}/_update` + } + const meta: TransportRequestMetadata = { + name: 'inference.update', + pathParts: { + inference_id: params.inference_id, + task_type: params.task_type + } + } + return await this.transport.request({ path, method, querystring, body, meta }, options) + } } diff --git a/src/api/api/open_point_in_time.ts b/src/api/api/open_point_in_time.ts index 07ea72cee..611caab33 100644 --- a/src/api/api/open_point_in_time.ts +++ b/src/api/api/open_point_in_time.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Open a point in time. A search request by default runs against the most recent visible data of the target indices, which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple search requests using the same point in time. For example, if refreshes happen between `search_after` requests, then the results of those requests might not be consistent as changes happening 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. + * Open a point in time. A search request by default runs against the most recent visible data of the target indices, which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple search requests using the same point in time. For example, if refreshes happen between `search_after` requests, then the results of those requests might not be consistent as changes happening 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. 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. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/point-in-time-api.html | Elasticsearch API documentation} */ export default async function OpenPointInTimeApi (this: That, params: T.OpenPointInTimeRequest | TB.OpenPointInTimeRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/reindex.ts b/src/api/api/reindex.ts index 2ce1c09bf..018ba1769 100644 --- a/src/api/api/reindex.ts +++ b/src/api/api/reindex.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Reindex documents. Copies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself. + * Reindex documents. Copy documents from a source to a destination. You can copy all documents to the destination index or reindex a subset of the documents. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself. IMPORTANT: Reindex requires `_source` to be enabled for all documents in the source. The destination should be configured as wanted before calling the reindex API. Reindex does not copy the settings from the source or its associated template. Mappings, shard counts, and replicas, for example, must be configured ahead of time. If the Elasticsearch security features are enabled, you must have the following security privileges: * The `read` index privilege for the source data stream, index, or alias. * The `write` index privilege for the destination data stream, index, or index alias. * To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias. * If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias. If reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting. Automatic data stream creation requires a matching index template with data stream enabled. The `dest` element can be configured like the index API to control optimistic concurrency control. Omitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID. Setting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source. Setting `op_type` to `create` causes the reindex API to create only missing documents in the destination. All existing documents will cause a version conflict. IMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`. A reindex can only add new documents to a destination data stream. It cannot update existing documents in a destination data stream. By default, version conflicts abort the reindex process. To continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`. In this case, the response includes a count of the version conflicts that were encountered. Note that the handling of other error types is unaffected by the `conflicts` property. Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query. NOTE: The reindex API makes no effort to handle ID collisions. The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior. Instead, make sure that IDs are unique by using a script. **Running reindex asynchronously** If the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at `_tasks/`. **Reindex from multiple sources** If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources. That way you can resume the process if there are any errors by removing the partially completed source and starting over. It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel. For example, you can use a bash script like this: ``` for index in i1 i2 i3 i4 i5; do curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{ "source": { "index": "'$index'" }, "dest": { "index": "'$index'-reindexed" } }' done ``` **Throttling** Set `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations. Requests are throttled by padding each batch with a wait time. To turn off throttling, set `requests_per_second` to `-1`. The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding. The padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing. By default the batch size is `1000`, so if `requests_per_second` is set to `500`: ``` target_time = 1000 / 500 per second = 2 seconds wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds ``` Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set. This is "bursty" instead of "smooth". **Slicing** Reindex supports sliced scroll to parallelize the reindexing process. This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts. NOTE: Reindexing from remote clusters does not support manual or automatic slicing. You can slice a reindex request manually by providing a slice ID and total number of slices to each request. You can also let reindex automatically parallelize by using sliced scroll to slice on `_id`. The `slices` parameter specifies the number of slices to use. Adding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks: * You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices. * Fetching the status of the task for the request with `slices` only contains the status of completed slices. * These sub-requests are individually addressable for things like cancellation and rethrottling. * Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally. * Canceling the request with `slices` will cancel each sub-request. * Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution. * Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed. * Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time. If slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices. If slicing manually or otherwise tuning automatic slicing, use the following guidelines. Query performance is most efficient when the number of slices is equal to the number of shards in the index. If that number is large (for example, `500`), choose a lower number as too many slices will hurt performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead. Indexing performance scales linearly across available resources with the number of slices. Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources. **Modify documents during reindexing** Like `_update_by_query`, reindex operations support a script that modifies the document. Unlike `_update_by_query`, the script is allowed to modify the document's metadata. Just as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination. For example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the `noop` counter in the response body. Set `ctx.op` to `delete` if your script decides that the document must be deleted from the destination. The deletion will be reported in the `deleted` counter in the response body. Setting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`. Think of the possibilities! Just be careful; you are able to change: * `_id` * `_index` * `_version` * `_routing` Setting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request. It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API. **Reindex from remote** Reindex supports reindexing from a remote Elasticsearch cluster. The `host` parameter must contain a scheme, host, port, and optional path. The `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication. Be sure to use HTTPS when using basic authentication or the password will be sent in plain text. There are a range of settings available to configure the behavior of the HTTPS connection. When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key. Remote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting. It can be set to a comma delimited list of allowed remote host and port combinations. Scheme is ignored; only the host and port are used. For example: ``` reindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"] ``` The list of allowed hosts must be configured on any nodes that will coordinate the reindex. This feature should work with remote clusters of any version of Elasticsearch. This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version. WARNING: Elasticsearch does not support forward compatibility across major versions. For example, you cannot reindex from a 7.x cluster into a 6.x cluster. To enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification. NOTE: Reindexing from remote clusters does not support manual or automatic slicing. Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb. If the remote index includes very large documents you'll need to use a smaller batch size. It is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field. Both default to 30 seconds. **Configuring SSL parameters** Reindex from remote supports configurable SSL settings. These must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore. It is not possible to configure SSL in the body of the reindex request. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-reindex.html | Elasticsearch API documentation} */ export default async function ReindexApi (this: That, params: T.ReindexRequest | TB.ReindexRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/reindex_rethrottle.ts b/src/api/api/reindex_rethrottle.ts index d279496a3..519db1479 100644 --- a/src/api/api/reindex_rethrottle.ts +++ b/src/api/api/reindex_rethrottle.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Throttle a reindex operation. Change the number of requests per second for a particular reindex operation. + * Throttle a reindex operation. Change the number of requests per second for a particular reindex operation. For example: ``` POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 ``` Rethrottling that speeds up the query takes effect immediately. Rethrottling that slows down the query will take effect after completing the current batch. This behavior prevents scroll timeouts. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-reindex.html | Elasticsearch API documentation} */ export default async function ReindexRethrottleApi (this: That, params: T.ReindexRethrottleRequest | TB.ReindexRethrottleRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/search.ts b/src/api/api/search.ts index 7ec27b967..240f75db5 100644 --- a/src/api/api/search.ts +++ b/src/api/api/search.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Run a search. 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. + * Run a search. 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. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/search-search.html | Elasticsearch API documentation} */ export default async function SearchApi> (this: That, params?: T.SearchRequest | TB.SearchRequest, options?: TransportRequestOptionsWithOutMeta): Promise> diff --git a/src/api/api/security.ts b/src/api/api/security.ts index d11e3e4ce..a57ea864b 100644 --- a/src/api/api/security.ts +++ b/src/api/api/security.ts @@ -45,7 +45,7 @@ export default class Security { } /** - * Activate a user profile. Create or update a user profile on behalf of another user. + * Activate a user profile. Create or update a user profile on behalf of another user. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. The calling application must have either an `access_token` or a combination of `username` and `password` for the user that the profile document is intended for. Elastic reserves the right to change or remove this feature in future releases without prior notice. This API creates or updates a profile document for end users with information that is extracted from the user's authentication object including `username`, `full_name,` `roles`, and the authentication realm. For example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token. When updating a profile document, the API enables the document if it was disabled. Any updates do not change existing content for either the `labels` or `data` fields. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-activate-user-profile.html | Elasticsearch API documentation} */ async activateUserProfile (this: That, params: T.SecurityActivateUserProfileRequest | TB.SecurityActivateUserProfileRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -355,7 +355,7 @@ export default class Security { } /** - * Clear the user cache. Evict users from the user cache. You can completely clear the cache or evict specific users. + * Clear the user cache. Evict users from the user cache. You can completely clear the cache or evict specific users. User credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request. There are realm settings that you can use to configure the user cache. For more information, refer to the documentation about controlling the user cache. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-clear-cache.html | Elasticsearch API documentation} */ async clearCachedRealms (this: That, params: T.SecurityClearCachedRealmsRequest | TB.SecurityClearCachedRealmsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -419,7 +419,7 @@ export default class Security { } /** - * Clear service account token caches. Evict a subset of all entries from the service account token caches. + * Clear service account token caches. Evict a subset of all entries from the service account token caches. Two separate caches exist for service account tokens: one cache for tokens backed by the `service_tokens` file, and another for tokens backed by the `.security` index. This API clears matching entries from both caches. The cache for service account tokens backed by the `.security` index is cleared automatically on state changes of the security index. The cache for tokens backed by the `service_tokens` file is cleared automatically on file changes. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-clear-service-token-caches.html | Elasticsearch API documentation} */ async clearCachedServiceTokens (this: That, params: T.SecurityClearCachedServiceTokensRequest | TB.SecurityClearCachedServiceTokensRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -453,7 +453,7 @@ export default class Security { } /** - * Create an API key. Create an API key for access without requiring basic authentication. A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys. + * Create an API key. Create an API key for access without requiring basic authentication. IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error. A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys. The API keys are created by the Elasticsearch API key service, which is automatically enabled. To configure or turn off the API key service, refer to API key service setting documentation. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-create-api-key.html | Elasticsearch API documentation} */ async createApiKey (this: That, params?: T.SecurityCreateApiKeyRequest | TB.SecurityCreateApiKeyRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -536,7 +536,7 @@ export default class Security { } /** - * Create a service account token. Create a service accounts token for access without requiring basic authentication. + * Create a service account token. Create a service accounts token for access without requiring basic authentication. NOTE: Service account tokens never expire. You must actively delete them if they are no longer needed. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-create-service-token.html | Elasticsearch API documentation} */ async createServiceToken (this: That, params: T.SecurityCreateServiceTokenRequest | TB.SecurityCreateServiceTokenRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -618,7 +618,7 @@ export default class Security { } /** - * Delete application privileges. + * Delete application privileges. To use this API, you must have one of the following privileges: * The `manage_security` cluster privilege (or a greater privilege such as `all`). * The "Manage Application Privileges" global privilege for the application being referenced in the request. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-delete-privilege.html | Elasticsearch API documentation} */ async deletePrivileges (this: That, params: T.SecurityDeletePrivilegesRequest | TB.SecurityDeletePrivilegesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -651,7 +651,7 @@ export default class Security { } /** - * Delete roles. Delete roles in the native realm. + * Delete roles. Delete roles in the native realm. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The delete roles API cannot remove roles that are defined in roles files. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-delete-role.html | Elasticsearch API documentation} */ async deleteRole (this: That, params: T.SecurityDeleteRoleRequest | TB.SecurityDeleteRoleRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -683,7 +683,7 @@ export default class Security { } /** - * Delete role mappings. + * Delete role mappings. Role mappings define which roles are assigned to each user. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The delete role mappings API cannot remove role mappings that are defined in role mapping files. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-delete-role-mapping.html | Elasticsearch API documentation} */ async deleteRoleMapping (this: That, params: T.SecurityDeleteRoleMappingRequest | TB.SecurityDeleteRoleMappingRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -781,7 +781,7 @@ export default class Security { } /** - * Disable users. Disable users in the native realm. + * Disable users. Disable users in the native realm. By default, when you create users, they are enabled. You can use this API to revoke a user's access to Elasticsearch. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-disable-user.html | Elasticsearch API documentation} */ async disableUser (this: That, params: T.SecurityDisableUserRequest | TB.SecurityDisableUserRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -813,7 +813,7 @@ export default class Security { } /** - * Disable a user profile. Disable user profiles so that they are not visible in user profile searches. + * Disable a user profile. Disable user profiles so that they are not visible in user profile searches. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. When you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches. To re-enable a disabled user profile, use the enable user profile API . * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-disable-user-profile.html | Elasticsearch API documentation} */ async disableUserProfile (this: That, params: T.SecurityDisableUserProfileRequest | TB.SecurityDisableUserProfileRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -845,7 +845,7 @@ export default class Security { } /** - * Enable users. Enable users in the native realm. + * Enable users. Enable users in the native realm. By default, when you create users, they are enabled. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-enable-user.html | Elasticsearch API documentation} */ async enableUser (this: That, params: T.SecurityEnableUserRequest | TB.SecurityEnableUserRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -877,7 +877,7 @@ export default class Security { } /** - * Enable a user profile. Enable user profiles to make them visible in user profile searches. + * Enable a user profile. Enable user profiles to make them visible in user profile searches. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. When you activate a user profile, it's automatically enabled and visible in user profile searches. If you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-enable-user-profile.html | Elasticsearch API documentation} */ async enableUserProfile (this: That, params: T.SecurityEnableUserProfileRequest | TB.SecurityEnableUserProfileRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -909,7 +909,7 @@ export default class Security { } /** - * Enroll Kibana. Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster. + * Enroll Kibana. Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster. NOTE: This API is currently intended for internal use only by Kibana. Kibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-kibana-enrollment.html | Elasticsearch API documentation} */ async enrollKibana (this: That, params?: T.SecurityEnrollKibanaRequest | TB.SecurityEnrollKibanaRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -939,7 +939,7 @@ export default class Security { } /** - * Enroll a node. Enroll a new node to allow it to join an existing cluster with security features enabled. + * Enroll a node. Enroll a new node to allow it to join an existing cluster with security features enabled. The response contains all the necessary information for the joining node to bootstrap discovery and security related settings so that it can successfully join the cluster. The response contains key and certificate material that allows the caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-node-enrollment.html | Elasticsearch API documentation} */ async enrollNode (this: That, params?: T.SecurityEnrollNodeRequest | TB.SecurityEnrollNodeRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1029,7 +1029,7 @@ export default class Security { } /** - * Get application privileges. + * Get application privileges. To use this API, you must have one of the following privileges: * The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`). * The "Manage Application Privileges" global privilege for the application being referenced in the request. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-privileges.html | Elasticsearch API documentation} */ async getPrivileges (this: That, params?: T.SecurityGetPrivilegesRequest | TB.SecurityGetPrivilegesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1153,7 +1153,7 @@ export default class Security { } /** - * Get service accounts. Get a list of service accounts that match the provided path parameters. + * Get service accounts. Get a list of service accounts that match the provided path parameters. NOTE: Currently, only the `elastic/fleet-server` service account is available. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-service-accounts.html | Elasticsearch API documentation} */ async getServiceAccounts (this: That, params?: T.SecurityGetServiceAccountsRequest | TB.SecurityGetServiceAccountsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1197,7 +1197,7 @@ export default class Security { } /** - * Get service account credentials. + * Get service account credentials. To use this API, you must have at least the `read_security` cluster privilege (or a greater privilege such as `manage_service_account` or `manage_security`). The response includes service account tokens that were created with the create service account tokens API as well as file-backed tokens from all nodes of the cluster. NOTE: For tokens backed by the `service_tokens` file, the API collects them from all nodes of the cluster. Tokens with the same name from different nodes are assumed to be the same token and are only counted once towards the total number of service tokens. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-service-credentials.html | Elasticsearch API documentation} */ async getServiceCredentials (this: That, params: T.SecurityGetServiceCredentialsRequest | TB.SecurityGetServiceCredentialsRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1230,13 +1230,13 @@ export default class Security { } /** - * Retrieve settings for the security system indices + * Get security index settings. Get the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of the index settings — those that are user-configurable—will be shown. This includes: * `index.auto_expand_replicas` * `index.number_of_replicas` * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-settings.html | Elasticsearch API documentation} */ - async getSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithOutMeta): Promise - async getSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithMeta): Promise> - async getSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise - async getSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise { + async getSettings (this: That, params?: T.SecurityGetSettingsRequest | TB.SecurityGetSettingsRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async getSettings (this: That, params?: T.SecurityGetSettingsRequest | TB.SecurityGetSettingsRequest, options?: TransportRequestOptionsWithMeta): Promise> + async getSettings (this: That, params?: T.SecurityGetSettingsRequest | TB.SecurityGetSettingsRequest, options?: TransportRequestOptions): Promise + async getSettings (this: That, params?: T.SecurityGetSettingsRequest | TB.SecurityGetSettingsRequest, options?: TransportRequestOptions): Promise { const acceptedPath: string[] = [] const querystring: Record = {} const body = undefined @@ -1246,6 +1246,7 @@ export default class Security { if (acceptedPath.includes(key)) { continue } else if (key !== 'body') { + // @ts-expect-error querystring[key] = params[key] } } @@ -1259,7 +1260,7 @@ export default class Security { } /** - * Get a token. Create a bearer token for access without requiring basic authentication. + * Get a token. Create a bearer token for access without requiring basic authentication. The tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface. Alternatively, you can explicitly enable the `xpack.security.authc.token.enabled` setting. When you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface. The get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body. A successful get token API call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available. The tokens returned by the get token API have a finite period of time for which they are valid and after that time period, they can no longer be used. That time period is defined by the `xpack.security.authc.token.timeout` setting. If you want to invalidate a token immediately, you can do so by using the invalidate token API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-token.html | Elasticsearch API documentation} */ async getToken (this: That, params?: T.SecurityGetTokenRequest | TB.SecurityGetTokenRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1341,7 +1342,7 @@ export default class Security { } /** - * Get user privileges. + * Get user privileges. Get the security privileges for the logged in user. All users can use this API, but only to determine their own privileges. To check the privileges of other users, you must use the run as feature. To check whether a user has a specific list of privileges, use the has privileges API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-user-privileges.html | Elasticsearch API documentation} */ async getUserPrivileges (this: That, params?: T.SecurityGetUserPrivilegesRequest | TB.SecurityGetUserPrivilegesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1371,7 +1372,7 @@ export default class Security { } /** - * Get a user profile. Get a user's profile using the unique profile ID. + * Get a user profile. Get a user's profile using the unique profile ID. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-get-user-profile.html | Elasticsearch API documentation} */ async getUserProfile (this: That, params: T.SecurityGetUserProfileRequest | TB.SecurityGetUserProfileRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1403,7 +1404,7 @@ export default class Security { } /** - * Grant an API key. Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user’s credentials. The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user. This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. By default, API keys never expire. You can specify expiration information when you create the API keys. + * Grant an API key. Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication credentials for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user's credentials. The supported user authentication credential types are: * username and password * Elasticsearch access tokens * JWTs The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user. This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. The API keys are created by the Elasticsearch API key service, which is automatically enabled. A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds. By default, API keys never expire. You can specify expiration information when you create the API keys. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-grant-api-key.html | Elasticsearch API documentation} */ async grantApiKey (this: That, params: T.SecurityGrantApiKeyRequest | TB.SecurityGrantApiKeyRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1444,7 +1445,7 @@ export default class Security { } /** - * Check user privileges. Determine whether the specified user has a specified list of privileges. + * Check user privileges. Determine whether the specified user has a specified list of privileges. All users can use this API, but only to determine their own privileges. To check the privileges of other users, you must use the run as feature. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-has-privileges.html | Elasticsearch API documentation} */ async hasPrivileges (this: That, params?: T.SecurityHasPrivilegesRequest | TB.SecurityHasPrivilegesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1496,7 +1497,7 @@ export default class Security { } /** - * Check user profile privileges. Determine whether the users associated with the specified user profile IDs have all the requested privileges. + * Check user profile privileges. Determine whether the users associated with the specified user profile IDs have all the requested privileges. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-has-privileges-user-profile.html | Elasticsearch API documentation} */ async hasPrivilegesUserProfile (this: That, params: T.SecurityHasPrivilegesUserProfileRequest | TB.SecurityHasPrivilegesUserProfileRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1537,7 +1538,7 @@ export default class Security { } /** - * Invalidate API keys. This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted. The `manage_api_key` privilege allows deleting any API keys. The `manage_own_api_key` only allows deleting API keys that are owned by the user. In addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats: - Set the parameter `owner=true`. - Or, set both `username` and `realm_name` to match the user’s identity. - Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field. + * Invalidate API keys. This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted. To use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges. The `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys. The `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys. The `manage_own_api_key` only allows deleting REST API keys that are owned by the user. In addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats: - Set the parameter `owner=true`. - Or, set both `username` and `realm_name` to match the user's identity. - Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-invalidate-api-key.html | Elasticsearch API documentation} */ async invalidateApiKey (this: That, params?: T.SecurityInvalidateApiKeyRequest | TB.SecurityInvalidateApiKeyRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1579,7 +1580,7 @@ export default class Security { } /** - * Invalidate a token. The access tokens returned by the get token API have a finite period of time for which they are valid. After that time period, they can no longer be used. The time period is defined by the `xpack.security.authc.token.timeout` setting. The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API. + * Invalidate a token. The access tokens returned by the get token API have a finite period of time for which they are valid. After that time period, they can no longer be used. The time period is defined by the `xpack.security.authc.token.timeout` setting. The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API. NOTE: While all parameters are optional, at least one of them is required. More specifically, either one of `token` or `refresh_token` parameters is required. If none of these two are specified, then `realm_name` and/or `username` need to be specified. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-invalidate-token.html | Elasticsearch API documentation} */ async invalidateToken (this: That, params?: T.SecurityInvalidateTokenRequest | TB.SecurityInvalidateTokenRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1745,7 +1746,7 @@ export default class Security { } /** - * Create or update application privileges. + * Create or update application privileges. To use this API, you must have one of the following privileges: * The `manage_security` cluster privilege (or a greater privilege such as `all`). * The "Manage Application Privileges" global privilege for the application being referenced in the request. Application names are formed from a prefix, with an optional suffix that conform to the following rules: * The prefix must begin with a lowercase ASCII letter. * The prefix must contain only ASCII letters or digits. * The prefix must be at least 3 characters long. * If the suffix exists, it must begin with either a dash `-` or `_`. * The suffix cannot contain any of the following characters: `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*`. * No part of the name can contain whitespace. Privilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`. Action names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-put-privileges.html | Elasticsearch API documentation} */ async putPrivileges (this: That, params: T.SecurityPutPrivilegesRequest | TB.SecurityPutPrivilegesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1823,7 +1824,7 @@ export default class Security { } /** - * Create or update role mappings. Role mappings define which roles are assigned to each user. Each mapping has rules that identify users and a list of roles that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files. This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using the create or update roles API or roles files. + * Create or update role mappings. Role mappings define which roles are assigned to each user. Each mapping has rules that identify users and a list of roles that are granted to those users. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files. NOTE: This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using the create or update roles API or roles files. **Role templates** The most common use for role mappings is to create a mapping from a known value on the user to a fixed role name. For example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch. The `roles` field is used for this purpose. For more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user. The `role_templates` field is used for this purpose. NOTE: To use role templates successfully, the relevant scripting feature must be enabled. Otherwise, all attempts to create a role mapping with role templates fail. All of the user fields that are available in the role mapping rules are also available in the role templates. Thus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated. By default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user. If the format of the template is set to "json" then the template is expected to produce a JSON string or an array of JSON strings for the role names. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-put-role-mapping.html | Elasticsearch API documentation} */ async putRoleMapping (this: That, params: T.SecurityPutRoleMappingRequest | TB.SecurityPutRoleMappingRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1867,7 +1868,7 @@ export default class Security { } /** - * Create or update users. A password is required for adding a new user but is optional when updating an existing user. To change a user’s password without updating any other fields, use the change password API. + * Create or update users. Add and update users in the native realm. A password is required for adding a new user but is optional when updating an existing user. To change a user's password without updating any other fields, use the change password API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-put-user.html | Elasticsearch API documentation} */ async putUser (this: That, params: T.SecurityPutUserRequest | TB.SecurityPutUserRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1911,7 +1912,7 @@ export default class Security { } /** - * Find API keys with a query. Get a paginated list of API keys and their information. You can optionally filter the results with a query. + * Find API keys with a query. Get a paginated list of API keys and their information. You can optionally filter the results with a query. To use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges. If you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own. If you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-query-api-key.html | Elasticsearch API documentation} */ async queryApiKeys (this: That, params?: T.SecurityQueryApiKeysRequest | TB.SecurityQueryApiKeysRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1953,7 +1954,7 @@ export default class Security { } /** - * Find roles with a query. Get roles in a paginated manner. You can optionally filter the results with a query. + * Find roles with a query. Get roles in a paginated manner. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. You can optionally filter the results with a query. Also, the results can be paginated and sorted. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-query-role.html | Elasticsearch API documentation} */ async queryRole (this: That, params?: T.SecurityQueryRoleRequest | TB.SecurityQueryRoleRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -1995,7 +1996,7 @@ export default class Security { } /** - * Find users with a query. Get information for users in a paginated manner. You can optionally filter the results with a query. + * Find users with a query. Get information for users in a paginated manner. You can optionally filter the results with a query. NOTE: As opposed to the get user API, built-in users are excluded from the result. This API is only for native users. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-query-user.html | Elasticsearch API documentation} */ async queryUser (this: That, params?: T.SecurityQueryUserRequest | TB.SecurityQueryUserRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2037,7 +2038,7 @@ export default class Security { } /** - * Authenticate SAML. Submits a SAML response message to Elasticsearch for consumption. + * Authenticate SAML. Submit a SAML response message to Elasticsearch for consumption. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. The SAML message that is submitted can be: * A response to a SAML authentication request that was previously created using the SAML prepare authentication API. * An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow. In either case, the SAML message needs to be a base64 encoded XML document with a root element of ``. After successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. This API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-saml-authenticate.html | Elasticsearch API documentation} */ async samlAuthenticate (this: That, params: T.SecuritySamlAuthenticateRequest | TB.SecuritySamlAuthenticateRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2078,7 +2079,7 @@ export default class Security { } /** - * Logout of SAML completely. Verifies the logout response sent from the SAML IdP. + * Logout of SAML completely. Verifies the logout response sent from the SAML IdP. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. The SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout. This API verifies the response by ensuring the content is relevant and validating its signature. An empty response is returned if the verification process is successful. The response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding. The caller of this API must prepare the request accordingly so that this API can handle either of them. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-saml-complete-logout.html | Elasticsearch API documentation} */ async samlCompleteLogout (this: That, params: T.SecuritySamlCompleteLogoutRequest | TB.SecuritySamlCompleteLogoutRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2119,7 +2120,7 @@ export default class Security { } /** - * Invalidate SAML. Submits a SAML LogoutRequest message to Elasticsearch for consumption. + * Invalidate SAML. Submit a SAML LogoutRequest message to Elasticsearch for consumption. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. The logout request comes from the SAML IdP during an IdP initiated Single Logout. The custom web application can use this API to have Elasticsearch process the `LogoutRequest`. After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message. Thus the user can be redirected back to their IdP. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-saml-invalidate.html | Elasticsearch API documentation} */ async samlInvalidate (this: That, params: T.SecuritySamlInvalidateRequest | TB.SecuritySamlInvalidateRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2160,7 +2161,7 @@ export default class Security { } /** - * Logout of SAML. Submits a request to invalidate an access token and refresh token. + * Logout of SAML. Submits a request to invalidate an access token and refresh token. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. This API invalidates the tokens that were generated for a user by the SAML authenticate API. If the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout). * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-saml-logout.html | Elasticsearch API documentation} */ async samlLogout (this: That, params: T.SecuritySamlLogoutRequest | TB.SecuritySamlLogoutRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2201,7 +2202,7 @@ export default class Security { } /** - * Prepare SAML authentication. Creates a SAML authentication request (``) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch. + * Prepare SAML authentication. Create a SAML authentication request (``) as a URL string based on the configuration of the respective SAML realm in Elasticsearch. NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack. This API returns a URL pointing to the SAML Identity Provider. You can use the URL to redirect the browser of the user in order to continue the authentication process. The URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded. If the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`. These parameters contain the algorithm used for the signature and the signature value itself. It also returns a random string that uniquely identifies this SAML Authentication request. The caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-saml-prepare-authentication.html | Elasticsearch API documentation} */ async samlPrepareAuthentication (this: That, params?: T.SecuritySamlPrepareAuthenticationRequest | TB.SecuritySamlPrepareAuthenticationRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2243,7 +2244,7 @@ export default class Security { } /** - * Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 Service Provider. + * Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 Service Provider. The SAML 2.0 specification provides a mechanism for Service Providers to describe their capabilities and configuration using a metadata file. This API generates Service Provider metadata based on the configuration of a SAML realm in Elasticsearch. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-saml-sp-metadata.html | Elasticsearch API documentation} */ async samlServiceProviderMetadata (this: That, params: T.SecuritySamlServiceProviderMetadataRequest | TB.SecuritySamlServiceProviderMetadataRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2275,7 +2276,7 @@ export default class Security { } /** - * Suggest a user profile. Get suggestions for user profiles that match specified search criteria. + * Suggest a user profile. Get suggestions for user profiles that match specified search criteria. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-suggest-user-profile.html | Elasticsearch API documentation} */ async suggestUserProfiles (this: That, params?: T.SecuritySuggestUserProfilesRequest | TB.SecuritySuggestUserProfilesRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2317,7 +2318,7 @@ export default class Security { } /** - * Update an API key. Updates attributes of an existing API key. Users can only update API keys that they created or that were granted to them. Use this API to update API keys created by the create API Key or grant API Key APIs. If you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead. It’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key. This API supports updates to an API key’s access scope and metadata. The access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request. The snapshot of the owner’s permissions is updated automatically on every call. If you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope. This change can occur if the owner user’s permissions have changed since the API key was created or last modified. To update another user’s API key, use the `run_as` feature to submit a request on behalf of another user. IMPORTANT: It’s not possible to use an API key as the authentication credential for this API. To update an API key, the owner user’s credentials are required. + * Update an API key. Update attributes of an existing API key. This API supports updates to an API key's access scope, expiration, and metadata. To use this API, you must have at least the `manage_own_api_key` cluster privilege. Users can only update API keys that they created or that were granted to them. To update another user’s API key, use the `run_as` feature to submit a request on behalf of another user. IMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required. Use this API to update API keys created by the create API key or grant API Key APIs. If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead. It's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API. The access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request. The snapshot of the owner's permissions is updated automatically on every call. IMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope. This change can occur if the owner user's permissions have changed since the API key was created or last modified. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-update-api-key.html | Elasticsearch API documentation} */ async updateApiKey (this: That, params: T.SecurityUpdateApiKeyRequest | TB.SecurityUpdateApiKeyRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2361,7 +2362,7 @@ export default class Security { } /** - * Update a cross-cluster API key. Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. + * Update a cross-cluster API key. Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. To use this API, you must have at least the `manage_security` cluster privilege. Users can only update API keys that they created. To update another user's API key, use the `run_as` feature to submit a request on behalf of another user. IMPORTANT: It's not possible to use an API key as the authentication credential for this API. To update an API key, the owner user's credentials are required. It's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API. This API supports updates to an API key's access scope, metadata, and expiration. The owner user's information, such as the `username` and `realm`, is also updated automatically on every call. NOTE: This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-update-cross-cluster-api-key.html | Elasticsearch API documentation} */ async updateCrossClusterApiKey (this: That, params: T.SecurityUpdateCrossClusterApiKeyRequest | TB.SecurityUpdateCrossClusterApiKeyRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -2405,22 +2406,35 @@ export default class Security { } /** - * Update settings for the security system index + * Update security index settings. Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified. This includes `index.auto_expand_replicas` and `index.number_of_replicas`. NOTE: If `index.auto_expand_replicas` is set, `index.number_of_replicas` will be ignored during updates. If a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-update-settings.html | Elasticsearch API documentation} */ - async updateSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithOutMeta): Promise - async updateSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithMeta): Promise> - async updateSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise - async updateSettings (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise { + async updateSettings (this: That, params?: T.SecurityUpdateSettingsRequest | TB.SecurityUpdateSettingsRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async updateSettings (this: That, params?: T.SecurityUpdateSettingsRequest | TB.SecurityUpdateSettingsRequest, options?: TransportRequestOptionsWithMeta): Promise> + async updateSettings (this: That, params?: T.SecurityUpdateSettingsRequest | TB.SecurityUpdateSettingsRequest, options?: TransportRequestOptions): Promise + async updateSettings (this: That, params?: T.SecurityUpdateSettingsRequest | TB.SecurityUpdateSettingsRequest, options?: TransportRequestOptions): Promise { const acceptedPath: string[] = [] + const acceptedBody: string[] = ['security', 'security-profile', 'security-tokens'] const querystring: Record = {} - const body = undefined + // @ts-expect-error + const userBody: any = params?.body + let body: Record | string + if (typeof userBody === 'string') { + body = userBody + } else { + body = userBody != null ? { ...userBody } : undefined + } params = params ?? {} for (const key in params) { - if (acceptedPath.includes(key)) { + if (acceptedBody.includes(key)) { + body = body ?? {} + // @ts-expect-error + body[key] = params[key] + } else if (acceptedPath.includes(key)) { continue } else if (key !== 'body') { + // @ts-expect-error querystring[key] = params[key] } } @@ -2434,7 +2448,7 @@ export default class Security { } /** - * Update user profile data. Update specific data for the user profile that is associated with a unique ID. + * Update user profile data. Update specific data for the user profile that is associated with a unique ID. NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice. To use this API, you must have one of the following privileges: * The `manage_user_profile` cluster privilege. * The `update_profile_data` global privilege for the namespaces that are referenced in the request. This API updates the `labels` and `data` fields of an existing user profile document with JSON objects. New keys and their values are added to the profile document and conflicting keys are replaced by data that's included in the request. For both labels and data, content is namespaced by the top-level fields. The `update_profile_data` global privilege grants privileges for updating only the allowed namespaces. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/security-api-update-user-profile-data.html | Elasticsearch API documentation} */ async updateUserProfileData (this: That, params: T.SecurityUpdateUserProfileDataRequest | TB.SecurityUpdateUserProfileDataRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/snapshot.ts b/src/api/api/snapshot.ts index 8bd20dbf9..01aafa170 100644 --- a/src/api/api/snapshot.ts +++ b/src/api/api/snapshot.ts @@ -343,32 +343,32 @@ export default class Snapshot { } /** - * Analyzes a repository for correctness and performance - * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/modules-snapshots.html | Elasticsearch API documentation} + * Analyze a snapshot repository. Analyze the performance characteristics and any incorrect behaviour found in a repository. The response exposes implementation details of the analysis which may change from version to version. The response body format is therefore not considered stable and may be different in newer versions. There are a large number of third-party storage systems available, not all of which are suitable for use as a snapshot repository by Elasticsearch. Some storage systems behave incorrectly, or perform poorly, especially when accessed concurrently by multiple clients as the nodes of an Elasticsearch cluster do. This API performs a collection of read and write operations on your repository which are designed to detect incorrect behaviour and to measure the performance characteristics of your storage system. The default values for the parameters are deliberately low to reduce the impact of running an analysis inadvertently and to provide a sensible starting point for your investigations. Run your first analysis with the default parameter values to check for simple problems. If successful, run a sequence of increasingly large analyses until you encounter a failure or you reach a `blob_count` of at least `2000`, a `max_blob_size` of at least `2gb`, a `max_total_data_size` of at least `1tb`, and a `register_operation_count` of at least `100`. Always specify a generous timeout, possibly `1h` or longer, to allow time for each analysis to run to completion. Perform the analyses using a multi-node cluster of a similar size to your production cluster so that it can detect any problems that only arise when the repository is accessed by many nodes at once. If the analysis fails, Elasticsearch detected that your repository behaved unexpectedly. This usually means you are using a third-party storage system with an incorrect or incompatible implementation of the API it claims to support. If so, this storage system is not suitable for use as a snapshot repository. You will need to work with the supplier of your storage system to address the incompatibilities that Elasticsearch detects. If the analysis is successful, the API returns details of the testing process, optionally including how long each operation took. You can use this information to determine the performance of your storage system. If any operation fails or returns an incorrect result, the API returns an error. If the API returns an error, it may not have removed all the data it wrote to the repository. The error will indicate the location of any leftover data and this path is also recorded in the Elasticsearch logs. You should verify that this location has been cleaned up correctly. If there is still leftover data at the specified location, you should manually remove it. If the connection from your client to Elasticsearch is closed while the client is waiting for the result of the analysis, the test is cancelled. Some clients are configured to close their connection if no response is received within a certain timeout. An analysis takes a long time to complete so you might need to relax any such client-side timeouts. On cancellation the analysis attempts to clean up the data it was writing, but it may not be able to remove it all. The path to the leftover data is recorded in the Elasticsearch logs. You should verify that this location has been cleaned up correctly. If there is still leftover data at the specified location, you should manually remove it. If the analysis is successful then it detected no incorrect behaviour, but this does not mean that correct behaviour is guaranteed. The analysis attempts to detect common bugs but it does not offer 100% coverage. Additionally, it does not test the following: * Your repository must perform durable writes. Once a blob has been written it must remain in place until it is deleted, even after a power loss or similar disaster. * Your repository must not suffer from silent data corruption. Once a blob has been written, its contents must remain unchanged until it is deliberately modified or deleted. * Your repository must behave correctly even if connectivity from the cluster is disrupted. Reads and writes may fail in this case, but they must not return incorrect results. IMPORTANT: An analysis writes a substantial amount of data to your repository and then reads it back again. This consumes bandwidth on the network between the cluster and the repository, and storage space and I/O bandwidth on the repository itself. You must ensure this load does not affect other users of these systems. Analyses respect the repository settings `max_snapshot_bytes_per_sec` and `max_restore_bytes_per_sec` if available and the cluster setting `indices.recovery.max_bytes_per_sec` which you can use to limit the bandwidth they consume. NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. NOTE: Different versions of Elasticsearch may perform different checks for repository compatibility, with newer versions typically being stricter than older ones. A storage system that passes repository analysis with one version of Elasticsearch may fail with a different version. This indicates it behaves incorrectly in ways that the former version did not detect. You must work with the supplier of your storage system to address the incompatibilities detected by the repository analysis API in any version of Elasticsearch. NOTE: This API may not work correctly in a mixed-version cluster. *Implementation details* NOTE: This section of documentation describes how the repository analysis API works in this version of Elasticsearch, but you should expect the implementation to vary between versions. The request parameters and response format depend on details of the implementation so may also be different in newer versions. The analysis comprises a number of blob-level tasks, as set by the `blob_count` parameter and a number of compare-and-exchange operations on linearizable registers, as set by the `register_operation_count` parameter. These tasks are distributed over the data and master-eligible nodes in the cluster for execution. For most blob-level tasks, the executing node first writes a blob to the repository and then instructs some of the other nodes in the cluster to attempt to read the data it just wrote. The size of the blob is chosen randomly, according to the `max_blob_size` and `max_total_data_size` parameters. If any of these reads fails then the repository does not implement the necessary read-after-write semantics that Elasticsearch requires. For some blob-level tasks, the executing node will instruct some of its peers to attempt to read the data before the writing process completes. These reads are permitted to fail, but must not return partial data. If any read returns partial data then the repository does not implement the necessary atomicity semantics that Elasticsearch requires. For some blob-level tasks, the executing node will overwrite the blob while its peers are reading it. In this case the data read may come from either the original or the overwritten blob, but the read operation must not return partial data or a mix of data from the two blobs. If any of these reads returns partial data or a mix of the two blobs then the repository does not implement the necessary atomicity semantics that Elasticsearch requires for overwrites. The executing node will use a variety of different methods to write the blob. For instance, where applicable, it will use both single-part and multi-part uploads. Similarly, the reading nodes will use a variety of different methods to read the data back again. For instance they may read the entire blob from start to end or may read only a subset of the data. For some blob-level tasks, the executing node will cancel the write before it is complete. In this case, it still instructs some of the other nodes in the cluster to attempt to read the blob but all of these reads must fail to find the blob. Linearizable registers are special blobs that Elasticsearch manipulates using an atomic compare-and-exchange operation. This operation ensures correct and strongly-consistent behavior even when the blob is accessed by multiple nodes at the same time. The detailed implementation of the compare-and-exchange operation on linearizable registers varies by repository type. Repository analysis verifies that that uncontended compare-and-exchange operations on a linearizable register blob always succeed. Repository analysis also verifies that contended operations either succeed or report the contention but do not return incorrect results. If an operation fails due to contention, Elasticsearch retries the operation until it succeeds. Most of the compare-and-exchange operations performed by repository analysis atomically increment a counter which is represented as an 8-byte blob. Some operations also verify the behavior on small blobs with sizes other than 8 bytes. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/repo-analysis-api.html | Elasticsearch API documentation} */ - async repositoryAnalyze (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithOutMeta): Promise - async repositoryAnalyze (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptionsWithMeta): Promise> - async repositoryAnalyze (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise - async repositoryAnalyze (this: That, params?: T.TODO | TB.TODO, options?: TransportRequestOptions): Promise { - const acceptedPath: string[] = ['repository'] + async repositoryAnalyze (this: That, params: T.SnapshotRepositoryAnalyzeRequest | TB.SnapshotRepositoryAnalyzeRequest, options?: TransportRequestOptionsWithOutMeta): Promise + async repositoryAnalyze (this: That, params: T.SnapshotRepositoryAnalyzeRequest | TB.SnapshotRepositoryAnalyzeRequest, options?: TransportRequestOptionsWithMeta): Promise> + async repositoryAnalyze (this: That, params: T.SnapshotRepositoryAnalyzeRequest | TB.SnapshotRepositoryAnalyzeRequest, options?: TransportRequestOptions): Promise + async repositoryAnalyze (this: That, params: T.SnapshotRepositoryAnalyzeRequest | TB.SnapshotRepositoryAnalyzeRequest, options?: TransportRequestOptions): Promise { + const acceptedPath: string[] = ['name'] const querystring: Record = {} const body = undefined - params = params ?? {} for (const key in params) { if (acceptedPath.includes(key)) { continue } else if (key !== 'body') { + // @ts-expect-error querystring[key] = params[key] } } const method = 'POST' - const path = `/_snapshot/${encodeURIComponent(params.repository.toString())}/_analyze` + const path = `/_snapshot/${encodeURIComponent(params.name.toString())}/_analyze` const meta: TransportRequestMetadata = { name: 'snapshot.repository_analyze', pathParts: { - repository: params.repository + name: params.name } } return await this.transport.request({ path, method, querystring, body, meta }, options) diff --git a/src/api/api/tasks.ts b/src/api/api/tasks.ts index c97c723bf..cadf8780b 100644 --- a/src/api/api/tasks.ts +++ b/src/api/api/tasks.ts @@ -45,7 +45,7 @@ export default class Tasks { } /** - * Cancel a task. A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away. It is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation. The get task information API will continue to list these cancelled tasks until they complete. The cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible. To troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running. You can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task. + * Cancel a task. WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible. A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away. It is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation. The get task information API will continue to list these cancelled tasks until they complete. The cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible. To troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running. You can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/tasks.html | Elasticsearch API documentation} */ async cancel (this: That, params?: T.TasksCancelRequest | TB.TasksCancelRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -85,7 +85,7 @@ export default class Tasks { } /** - * Get task information. Get information about a task currently running in the cluster. + * Get task information. Get information about a task currently running in the cluster. WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible. If the task identifier is not found, a 404 response code indicates that there are no resources that match the request. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/tasks.html | Elasticsearch API documentation} */ async get (this: That, params: T.TasksGetRequest | TB.TasksGetRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -117,7 +117,7 @@ export default class Tasks { } /** - * Get all tasks. Get information about the tasks currently running on one or more nodes in the cluster. + * Get all tasks. Get information about the tasks currently running on one or more nodes in the cluster. WARNING: The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible. **Identifying running tasks** The `X-Opaque-Id header`, when provided on the HTTP request header, is going to be returned as a header in the response as well as in the headers field for in the task information. This enables you to track certain calls or associate certain tasks with the client that started them. For example: ``` curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents" ``` The API returns the following result: ``` HTTP/1.1 200 OK X-Opaque-Id: 123456 content-type: application/json; charset=UTF-8 content-length: 831 { "tasks" : { "u5lcZHqcQhu-rUoFaqDphA:45" : { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 45, "type" : "transport", "action" : "cluster:monitor/tasks/lists", "start_time_in_millis" : 1513823752749, "running_time_in_nanos" : 293139, "cancellable" : false, "headers" : { "X-Opaque-Id" : "123456" }, "children" : [ { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 46, "type" : "direct", "action" : "cluster:monitor/tasks/lists[n]", "start_time_in_millis" : 1513823752750, "running_time_in_nanos" : 92133, "cancellable" : false, "parent_task_id" : "u5lcZHqcQhu-rUoFaqDphA:45", "headers" : { "X-Opaque-Id" : "123456" } } ] } } } ``` In this example, `X-Opaque-Id: 123456` is the ID as a part of the response header. The `X-Opaque-Id` in the task `headers` is the ID for the task that was initiated by the REST request. The `X-Opaque-Id` in the children `headers` is the child task of the task that was initiated by the REST request. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/tasks.html | Elasticsearch API documentation} */ async list (this: That, params?: T.TasksListRequest | TB.TasksListRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/update.ts b/src/api/api/update.ts index 1e0a23370..bcb95275d 100644 --- a/src/api/api/update.ts +++ b/src/api/api/update.ts @@ -39,7 +39,7 @@ import * as TB from '../typesWithBodyKey' interface That { transport: Transport } /** - * Update a document. Updates a document by running a script or passing a partial document. + * Update a document. Update a document by running a script or passing a partial document. If the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias. The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation: * Gets the document (collocated with the shard) from the index. * Runs the specified script. * Indexes the result. The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation. The `_source` field must be enabled to use this API. In addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp). * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.x/docs-update.html | Elasticsearch API documentation} */ export default async function UpdateApi (this: That, params: T.UpdateRequest | TB.UpdateRequest, options?: TransportRequestOptionsWithOutMeta): Promise> diff --git a/src/api/types.ts b/src/api/types.ts index bda3d448f..50e060835 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -1836,6 +1836,7 @@ export interface SearchShardsRequest extends RequestBase { expand_wildcards?: ExpandWildcards ignore_unavailable?: boolean local?: boolean + master_timeout?: Duration preference?: string routing?: Routing } @@ -2421,6 +2422,7 @@ export interface KnnQuery extends QueryDslQueryBase { k?: integer filter?: QueryDslQueryContainer | QueryDslQueryContainer[] similarity?: float + rescore_vector?: RescoreVector } export interface KnnRetriever extends RetrieverBase { @@ -2430,6 +2432,7 @@ export interface KnnRetriever extends RetrieverBase { k: integer num_candidates: integer similarity?: float + rescore_vector?: RescoreVector } export interface KnnSearch { @@ -2442,6 +2445,7 @@ export interface KnnSearch { filter?: QueryDslQueryContainer | QueryDslQueryContainer[] similarity?: float inner_hits?: SearchInnerHits + rescore_vector?: RescoreVector } export interface LatLonGeoLocation { @@ -2622,6 +2626,10 @@ export interface RequestCacheStats { miss_count: long } +export interface RescoreVector { + oversample: float +} + export type Result = 'created' | 'updated' | 'deleted' | 'not_found' | 'noop' export interface Retries { @@ -2829,6 +2837,8 @@ export interface StoredScript { source: string } +export type StreamResult = ArrayBuffer + export type SuggestMode = 'missing' | 'popular' | 'always' export type SuggestionName = string @@ -5325,6 +5335,11 @@ export interface MappingCorePropertyBase extends MappingPropertyBase { store?: boolean } +export interface MappingCountedKeywordProperty extends MappingPropertyBase { + type: 'counted_keyword' + index?: boolean +} + export interface MappingDataStreamTimestamp { enabled: boolean } @@ -5445,7 +5460,7 @@ export interface MappingFieldNamesField { enabled: boolean } -export type MappingFieldType = 'none' | 'geo_point' | 'geo_shape' | 'ip' | 'binary' | 'keyword' | 'text' | 'search_as_you_type' | 'date' | 'date_nanos' | 'boolean' | 'completion' | 'nested' | 'object' | 'passthrough' | 'version' | 'murmur3' | 'token_count' | 'percolator' | 'integer' | 'long' | 'short' | 'byte' | 'float' | 'half_float' | 'scaled_float' | 'double' | 'integer_range' | 'float_range' | 'long_range' | 'double_range' | 'date_range' | 'ip_range' | 'alias' | 'join' | 'rank_feature' | 'rank_features' | 'flattened' | 'shape' | 'histogram' | 'constant_keyword' | 'aggregate_metric_double' | 'dense_vector' | 'semantic_text' | 'sparse_vector' | 'match_only_text' | 'icu_collation_keyword' +export type MappingFieldType = 'none' | 'geo_point' | 'geo_shape' | 'ip' | 'binary' | 'keyword' | 'text' | 'search_as_you_type' | 'date' | 'date_nanos' | 'boolean' | 'completion' | 'nested' | 'object' | 'passthrough' | 'version' | 'murmur3' | 'token_count' | 'percolator' | 'integer' | 'long' | 'short' | 'byte' | 'float' | 'half_float' | 'scaled_float' | 'double' | 'integer_range' | 'float_range' | 'long_range' | 'double_range' | 'date_range' | 'ip_range' | 'alias' | 'join' | 'rank_feature' | 'rank_features' | 'flattened' | 'shape' | 'histogram' | 'constant_keyword' | 'counted_keyword' | 'aggregate_metric_double' | 'dense_vector' | 'semantic_text' | 'sparse_vector' | 'match_only_text' | 'icu_collation_keyword' export interface MappingFlattenedProperty extends MappingPropertyBase { boost?: double @@ -5640,7 +5655,7 @@ export interface MappingPointProperty extends MappingDocValuesPropertyBase { type: 'point' } -export type MappingProperty = MappingBinaryProperty | MappingBooleanProperty | MappingDynamicProperty | MappingJoinProperty | MappingKeywordProperty | MappingMatchOnlyTextProperty | MappingPercolatorProperty | MappingRankFeatureProperty | MappingRankFeaturesProperty | MappingSearchAsYouTypeProperty | MappingTextProperty | MappingVersionProperty | MappingWildcardProperty | MappingDateNanosProperty | MappingDateProperty | MappingAggregateMetricDoubleProperty | MappingDenseVectorProperty | MappingFlattenedProperty | MappingNestedProperty | MappingObjectProperty | MappingPassthroughObjectProperty | MappingSemanticTextProperty | MappingSparseVectorProperty | MappingCompletionProperty | MappingConstantKeywordProperty | MappingFieldAliasProperty | MappingHistogramProperty | MappingIpProperty | MappingMurmur3HashProperty | MappingTokenCountProperty | MappingGeoPointProperty | MappingGeoShapeProperty | MappingPointProperty | MappingShapeProperty | MappingByteNumberProperty | MappingDoubleNumberProperty | MappingFloatNumberProperty | MappingHalfFloatNumberProperty | MappingIntegerNumberProperty | MappingLongNumberProperty | MappingScaledFloatNumberProperty | MappingShortNumberProperty | MappingUnsignedLongNumberProperty | MappingDateRangeProperty | MappingDoubleRangeProperty | MappingFloatRangeProperty | MappingIntegerRangeProperty | MappingIpRangeProperty | MappingLongRangeProperty | MappingIcuCollationProperty +export type MappingProperty = MappingBinaryProperty | MappingBooleanProperty | MappingDynamicProperty | MappingJoinProperty | MappingKeywordProperty | MappingMatchOnlyTextProperty | MappingPercolatorProperty | MappingRankFeatureProperty | MappingRankFeaturesProperty | MappingSearchAsYouTypeProperty | MappingTextProperty | MappingVersionProperty | MappingWildcardProperty | MappingDateNanosProperty | MappingDateProperty | MappingAggregateMetricDoubleProperty | MappingDenseVectorProperty | MappingFlattenedProperty | MappingNestedProperty | MappingObjectProperty | MappingPassthroughObjectProperty | MappingSemanticTextProperty | MappingSparseVectorProperty | MappingCompletionProperty | MappingConstantKeywordProperty | MappingCountedKeywordProperty | MappingFieldAliasProperty | MappingHistogramProperty | MappingIpProperty | MappingMurmur3HashProperty | MappingTokenCountProperty | MappingGeoPointProperty | MappingGeoShapeProperty | MappingPointProperty | MappingShapeProperty | MappingByteNumberProperty | MappingDoubleNumberProperty | MappingFloatNumberProperty | MappingHalfFloatNumberProperty | MappingIntegerNumberProperty | MappingLongNumberProperty | MappingScaledFloatNumberProperty | MappingShortNumberProperty | MappingUnsignedLongNumberProperty | MappingDateRangeProperty | MappingDoubleRangeProperty | MappingFloatRangeProperty | MappingIntegerRangeProperty | MappingIpRangeProperty | MappingLongRangeProperty | MappingIcuCollationProperty export interface MappingPropertyBase { meta?: Record @@ -6917,7 +6932,7 @@ export type CatAllocationResponse = CatAllocationAllocationRecord[] export interface CatComponentTemplatesComponentTemplate { name: string - version: string + version: string | null alias_count: string mapping_count: string settings_count: string @@ -8706,12 +8721,14 @@ export interface CcrShardStats { export interface CcrDeleteAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration } export type CcrDeleteAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrFollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration wait_for_active_shards?: WaitForActiveShards data_stream_name?: string leader_index: IndexName @@ -8760,6 +8777,7 @@ export type CcrFollowInfoFollowerIndexStatus = 'active' | 'paused' export interface CcrFollowInfoRequest extends RequestBase { index: Indices + master_timeout?: Duration } export interface CcrFollowInfoResponse { @@ -8768,6 +8786,7 @@ export interface CcrFollowInfoResponse { export interface CcrFollowStatsRequest extends RequestBase { index: Indices + timeout?: Duration } export interface CcrFollowStatsResponse { @@ -8776,6 +8795,7 @@ export interface CcrFollowStatsResponse { export interface CcrForgetFollowerRequest extends RequestBase { index: IndexName + timeout?: Duration follower_cluster?: string follower_index?: IndexName follower_index_uuid?: Uuid @@ -8802,6 +8822,7 @@ export interface CcrGetAutoFollowPatternAutoFollowPatternSummary { export interface CcrGetAutoFollowPatternRequest extends RequestBase { name?: Name + master_timeout?: Duration } export interface CcrGetAutoFollowPatternResponse { @@ -8810,18 +8831,21 @@ export interface CcrGetAutoFollowPatternResponse { export interface CcrPauseAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration } export type CcrPauseAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrPauseFollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration } export type CcrPauseFollowResponse = AcknowledgedResponseBase export interface CcrPutAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration remote_cluster: string follow_index_pattern?: IndexPattern leader_index_patterns?: IndexPatterns @@ -8843,12 +8867,14 @@ export type CcrPutAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrResumeAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration } export type CcrResumeAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrResumeFollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration max_outstanding_read_requests?: long max_outstanding_write_requests?: long max_read_request_operation_count?: long @@ -8882,6 +8908,8 @@ export interface CcrStatsFollowStats { } export interface CcrStatsRequest extends RequestBase { + master_timeout?: Duration + timeout?: Duration } export interface CcrStatsResponse { @@ -8891,6 +8919,7 @@ export interface CcrStatsResponse { export interface CcrUnfollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration } export type CcrUnfollowResponse = AcknowledgedResponseBase @@ -8981,6 +9010,7 @@ export interface ClusterAllocationExplainNodeDiskUsage { export interface ClusterAllocationExplainRequest extends RequestBase { include_disk_info?: boolean include_yes_decisions?: boolean + master_timeout?: Duration current_node?: string index?: IndexName primary?: boolean @@ -9043,6 +9073,7 @@ export interface ClusterDeleteComponentTemplateRequest extends RequestBase { export type ClusterDeleteComponentTemplateResponse = AcknowledgedResponseBase export interface ClusterDeleteVotingConfigExclusionsRequest extends RequestBase { + master_timeout?: Duration wait_for_removal?: boolean } @@ -9175,6 +9206,7 @@ export interface ClusterPendingTasksResponse { export interface ClusterPostVotingConfigExclusionsRequest extends RequestBase { node_names?: Names node_ids?: Ids + master_timeout?: Duration timeout?: Duration } @@ -10152,6 +10184,7 @@ export interface EnrichSummary { export interface EnrichDeletePolicyRequest extends RequestBase { name: Name + master_timeout?: Duration } export type EnrichDeletePolicyResponse = AcknowledgedResponseBase @@ -10164,6 +10197,7 @@ export interface EnrichExecutePolicyExecuteEnrichPolicyStatus { export interface EnrichExecutePolicyRequest extends RequestBase { name: Name + master_timeout?: Duration wait_for_completion?: boolean } @@ -10174,6 +10208,7 @@ export interface EnrichExecutePolicyResponse { export interface EnrichGetPolicyRequest extends RequestBase { name?: Names + master_timeout?: Duration } export interface EnrichGetPolicyResponse { @@ -10182,6 +10217,7 @@ export interface EnrichGetPolicyResponse { export interface EnrichPutPolicyRequest extends RequestBase { name: Name + master_timeout?: Duration geo_match?: EnrichPolicy match?: EnrichPolicy range?: EnrichPolicy @@ -10214,6 +10250,7 @@ export interface EnrichStatsExecutingPolicy { } export interface EnrichStatsRequest extends RequestBase { + master_timeout?: Duration } export interface EnrichStatsResponse { @@ -10306,6 +10343,8 @@ export type EqlSearchResponse = EqlEqlSearchResponseBase> +} + +export interface EsqlAsyncQueryResponse { + columns?: EsqlColumns + id?: string + is_running: boolean +} + +export interface EsqlAsyncQueryDeleteRequest extends RequestBase { + id: Id +} + +export type EsqlAsyncQueryDeleteResponse = AcknowledgedResponseBase + +export interface EsqlAsyncQueryGetRequest extends RequestBase { + id: Id + drop_null_columns?: boolean + keep_alive?: Duration + wait_for_completion_timeout?: Duration +} + +export interface EsqlAsyncQueryGetResponse { + columns?: EsqlColumns + is_running: boolean +} export interface EsqlQueryRequest extends RequestBase { - format?: EsqlQueryEsqlFormat + format?: EsqlEsqlFormat delimiter?: string drop_null_columns?: boolean columnar?: boolean @@ -10344,6 +10421,7 @@ export interface FeaturesFeature { } export interface FeaturesGetFeaturesRequest extends RequestBase { + master_timeout?: Duration } export interface FeaturesGetFeaturesResponse { @@ -10351,6 +10429,7 @@ export interface FeaturesGetFeaturesResponse { } export interface FeaturesResetFeaturesRequest extends RequestBase { + master_timeout?: Duration } export interface FeaturesResetFeaturesResponse { @@ -10586,7 +10665,7 @@ export interface IlmMigrateAction { export interface IlmPhase { actions?: IlmActions - min_age?: Duration | long + min_age?: Duration } export interface IlmPhases { @@ -10686,7 +10765,6 @@ export interface IlmExplainLifecycleRequest extends RequestBase { only_errors?: boolean only_managed?: boolean master_timeout?: Duration - timeout?: Duration } export interface IlmExplainLifecycleResponse { @@ -11015,6 +11093,7 @@ export interface IndicesIndexSettingsLifecycle { parse_origination_date?: boolean step?: IndicesIndexSettingsLifecycleStep rollover_alias?: string + prefer_ilm?: boolean | string } export interface IndicesIndexSettingsLifecycleStep { @@ -11363,6 +11442,12 @@ export interface IndicesAnalyzeTokenDetail { tokens: IndicesAnalyzeExplainAnalyzeToken[] } +export interface IndicesCancelMigrateReindexRequest extends RequestBase { + index: Indices +} + +export type IndicesCancelMigrateReindexResponse = AcknowledgedResponseBase + export interface IndicesClearCacheRequest extends RequestBase { index?: Indices allow_no_indices?: boolean @@ -11441,6 +11526,24 @@ export interface IndicesCreateDataStreamRequest extends RequestBase { export type IndicesCreateDataStreamResponse = AcknowledgedResponseBase +export interface IndicesCreateFromCreateFrom { + mappings_override?: MappingTypeMapping + settings_override?: IndicesIndexSettings + remove_index_blocks?: boolean +} + +export interface IndicesCreateFromRequest extends RequestBase { + source: IndexName + dest: IndexName + create_from?: IndicesCreateFromCreateFrom +} + +export interface IndicesCreateFromResponse { + acknowledged: boolean + index: IndexName + shards_acknowledged: boolean +} + export interface IndicesDataStreamsStatsDataStreamsStatsItem { backing_indices: integer data_stream: Name @@ -11629,8 +11732,6 @@ export interface IndicesFieldUsageStatsRequest extends RequestBase { expand_wildcards?: ExpandWildcards ignore_unavailable?: boolean fields?: Fields - master_timeout?: Duration - timeout?: Duration wait_for_active_shards?: WaitForActiveShards } @@ -11806,6 +11907,34 @@ export interface IndicesGetMappingRequest extends RequestBase { export type IndicesGetMappingResponse = Record +export interface IndicesGetMigrateReindexStatusRequest extends RequestBase { + index: Indices +} + +export interface IndicesGetMigrateReindexStatusResponse { + start_time?: DateTime + start_time_millis: EpochTime + complete: boolean + total_indices_in_data_stream: integer + total_indices_requiring_upgrade: integer + successes: integer + in_progress: IndicesGetMigrateReindexStatusStatusInProgress[] + pending: integer + errors: IndicesGetMigrateReindexStatusStatusError[] + exception?: string +} + +export interface IndicesGetMigrateReindexStatusStatusError { + index: string + message: string +} + +export interface IndicesGetMigrateReindexStatusStatusInProgress { + index: string + total_doc_count: long + reindexed_doc_count: long +} + export interface IndicesGetSettingsRequest extends RequestBase { index?: Indices name?: Names @@ -11829,6 +11958,23 @@ export interface IndicesGetTemplateRequest extends RequestBase { export type IndicesGetTemplateResponse = Record +export interface IndicesMigrateReindexMigrateReindex { + mode: IndicesMigrateReindexModeEnum + source: IndicesMigrateReindexSourceIndex +} + +export type IndicesMigrateReindexModeEnum = 'upgrade' + +export interface IndicesMigrateReindexRequest extends RequestBase { + reindex?: IndicesMigrateReindexMigrateReindex +} + +export type IndicesMigrateReindexResponse = AcknowledgedResponseBase + +export interface IndicesMigrateReindexSourceIndex { + index: IndexName +} + export interface IndicesMigrateToDataStreamRequest extends RequestBase { name: IndexName master_timeout?: Duration @@ -12701,6 +12847,86 @@ export interface InferencePutRequest extends RequestBase { export type InferencePutResponse = InferenceInferenceEndpointInfo +export interface InferenceStreamInferenceRequest extends RequestBase { + inference_id: Id + task_type?: InferenceTaskType + input: string | string[] +} + +export type InferenceStreamInferenceResponse = StreamResult + +export interface InferenceUnifiedInferenceCompletionTool { + type: string + function: InferenceUnifiedInferenceCompletionToolFunction +} + +export interface InferenceUnifiedInferenceCompletionToolChoice { + type: string + function: InferenceUnifiedInferenceCompletionToolChoiceFunction +} + +export interface InferenceUnifiedInferenceCompletionToolChoiceFunction { + name: string +} + +export interface InferenceUnifiedInferenceCompletionToolFunction { + description?: string + name: string + parameters?: any + strict?: boolean +} + +export type InferenceUnifiedInferenceCompletionToolType = string | InferenceUnifiedInferenceCompletionToolChoice + +export interface InferenceUnifiedInferenceContentObject { + text: string + type: string +} + +export interface InferenceUnifiedInferenceMessage { + content?: InferenceUnifiedInferenceMessageContent + role: string + tool_call_id?: Id + tool_calls?: InferenceUnifiedInferenceToolCall[] +} + +export type InferenceUnifiedInferenceMessageContent = string | InferenceUnifiedInferenceContentObject[] + +export interface InferenceUnifiedInferenceRequest extends RequestBase { + task_type?: InferenceTaskType + inference_id: Id + timeout?: Duration + messages: InferenceUnifiedInferenceMessage[] + model?: string + max_completion_tokens?: long + stop?: string[] + temperature?: float + tool_choice?: InferenceUnifiedInferenceCompletionToolType + tools?: InferenceUnifiedInferenceCompletionTool[] + top_p?: float +} + +export type InferenceUnifiedInferenceResponse = StreamResult + +export interface InferenceUnifiedInferenceToolCall { + id: Id + function: InferenceUnifiedInferenceToolCallFunction + type: string +} + +export interface InferenceUnifiedInferenceToolCallFunction { + arguments: string + name: string +} + +export interface InferenceUpdateRequest extends RequestBase { + inference_id: Id + task_type?: InferenceTaskType + inference_config?: InferenceInferenceEndpoint +} + +export type InferenceUpdateResponse = InferenceInferenceEndpointInfo + export interface IngestAppendProcessor extends IngestProcessorBase { field: Field value: any | any[] @@ -13278,7 +13504,6 @@ export interface IngestGetGeoipDatabaseDatabaseConfigurationMetadata { export interface IngestGetGeoipDatabaseRequest extends RequestBase { id?: Ids - master_timeout?: Duration } export interface IngestGetGeoipDatabaseResponse { @@ -13380,6 +13605,8 @@ export type LicenseLicenseStatus = 'active' | 'valid' | 'invalid' | 'expired' export type LicenseLicenseType = 'missing' | 'trial' | 'basic' | 'standard' | 'dev' | 'silver' | 'gold' | 'platinum' | 'enterprise' export interface LicenseDeleteRequest extends RequestBase { + master_timeout?: Duration + timeout?: Duration } export type LicenseDeleteResponse = AcknowledgedResponseBase @@ -13429,6 +13656,8 @@ export interface LicensePostAcknowledgement { export interface LicensePostRequest extends RequestBase { acknowledge?: boolean + master_timeout?: Duration + timeout?: Duration license?: LicenseLicense licenses?: LicenseLicense[] } @@ -13441,6 +13670,8 @@ export interface LicensePostResponse { export interface LicensePostStartBasicRequest extends RequestBase { acknowledge?: boolean + master_timeout?: Duration + timeout?: Duration } export interface LicensePostStartBasicResponse { @@ -13454,6 +13685,7 @@ export interface LicensePostStartBasicResponse { export interface LicensePostStartTrialRequest extends RequestBase { acknowledge?: boolean type_query_string?: string + master_timeout?: Duration } export interface LicensePostStartTrialResponse { @@ -14958,6 +15190,7 @@ export type MlDeleteModelSnapshotResponse = AcknowledgedResponseBase export interface MlDeleteTrainedModelRequest extends RequestBase { model_id: Id force?: boolean + timeout?: Duration } export type MlDeleteTrainedModelResponse = AcknowledgedResponseBase @@ -15318,7 +15551,6 @@ export interface MlGetMemoryStatsMemory { export interface MlGetMemoryStatsRequest extends RequestBase { node_id?: Id - human?: boolean master_timeout?: Duration timeout?: Duration } @@ -16627,7 +16859,6 @@ export interface NodesHotThreadsRequest extends RequestBase { ignore_idle_threads?: boolean interval?: Duration snapshots?: long - master_timeout?: Duration threads?: long timeout?: Duration type?: ThreadType @@ -16989,7 +17220,6 @@ export interface NodesInfoRequest extends RequestBase { node_id?: NodeIds metric?: Metrics flat_settings?: boolean - master_timeout?: Duration timeout?: Duration } @@ -17023,7 +17253,6 @@ export interface NodesStatsRequest extends RequestBase { groups?: boolean include_segment_file_sizes?: boolean level?: Level - master_timeout?: Duration timeout?: Duration types?: string[] include_unloaded_segments?: boolean @@ -17490,8 +17719,6 @@ export interface SearchableSnapshotsClearCacheRequest extends RequestBase { expand_wildcards?: ExpandWildcards allow_no_indices?: boolean ignore_unavailable?: boolean - pretty?: boolean - human?: boolean } export type SearchableSnapshotsClearCacheResponse = any @@ -17715,6 +17942,10 @@ export interface SecuritySearchAccess { allow_restricted_indices?: boolean } +export interface SecuritySecuritySettings { + index?: IndicesIndexSettings +} + export type SecurityTemplateFormat = 'string' | 'json' export interface SecurityUser { @@ -18171,6 +18402,16 @@ export interface SecurityGetServiceCredentialsResponse { nodes_credentials: SecurityGetServiceCredentialsNodesCredentials } +export interface SecurityGetSettingsRequest extends RequestBase { + master_timeout?: Duration +} + +export interface SecurityGetSettingsResponse { + security: SecuritySecuritySettings + 'security-profile': SecuritySecuritySettings + 'security-tokens': SecuritySecuritySettings +} + export type SecurityGetTokenAccessTokenGrantType = 'password' | 'client_credentials' | '_kerberos' | 'refresh_token' export interface SecurityGetTokenAuthenticatedUser extends SecurityUser { @@ -18692,6 +18933,18 @@ export interface SecurityUpdateCrossClusterApiKeyResponse { updated: boolean } +export interface SecurityUpdateSettingsRequest extends RequestBase { + master_timeout?: Duration + timeout?: Duration + security?: SecuritySecuritySettings + 'security-profile'?: SecuritySecuritySettings + 'security-tokens'?: SecuritySecuritySettings +} + +export interface SecurityUpdateSettingsResponse { + acknowledged: boolean +} + export interface SecurityUpdateUserProfileDataRequest extends RequestBase { uid: SecurityUserProfileId if_seq_no?: SequenceNumber @@ -18735,7 +18988,6 @@ export interface ShutdownGetNodePluginsStatus { export interface ShutdownGetNodeRequest extends RequestBase { node_id?: NodeIds master_timeout?: TimeUnit - timeout?: TimeUnit } export interface ShutdownGetNodeResponse { @@ -19144,7 +19396,6 @@ export interface SnapshotCloneRequest extends RequestBase { snapshot: Name target_snapshot: Name master_timeout?: Duration - timeout?: Duration indices: string } @@ -19233,6 +19484,113 @@ export interface SnapshotGetRepositoryRequest extends RequestBase { export type SnapshotGetRepositoryResponse = Record +export interface SnapshotRepositoryAnalyzeBlobDetails { + name: string + overwritten: boolean + read_early: boolean + read_end: long + read_start: long + reads: SnapshotRepositoryAnalyzeReadBlobDetails + size: ByteSize + size_bytes: long +} + +export interface SnapshotRepositoryAnalyzeDetailsInfo { + blob: SnapshotRepositoryAnalyzeBlobDetails + overwrite_elapsed?: Duration + overwrite_elapsed_nanos?: DurationValue + write_elapsed: Duration + write_elapsed_nanos: DurationValue + write_throttled: Duration + write_throttled_nanos: DurationValue + writer_node: SnapshotRepositoryAnalyzeNodeInfo +} + +export interface SnapshotRepositoryAnalyzeNodeInfo { + id: Id + name: Name +} + +export interface SnapshotRepositoryAnalyzeReadBlobDetails { + before_write_complete?: boolean + elapsed?: Duration + elapsed_nanos?: DurationValue + first_byte_time?: Duration + first_byte_time_nanos: DurationValue + found: boolean + node: SnapshotRepositoryAnalyzeNodeInfo + throttled?: Duration + throttled_nanos?: DurationValue +} + +export interface SnapshotRepositoryAnalyzeReadSummaryInfo { + count: integer + max_wait: Duration + max_wait_nanos: DurationValue + total_elapsed: Duration + total_elapsed_nanos: DurationValue + total_size: ByteSize + total_size_bytes: long + total_throttled: Duration + total_throttled_nanos: DurationValue + total_wait: Duration + total_wait_nanos: DurationValue +} + +export interface SnapshotRepositoryAnalyzeRequest extends RequestBase { + name: Name + blob_count?: integer + concurrency?: integer + detailed?: boolean + early_read_node_count?: integer + max_blob_size?: ByteSize + max_total_data_size?: ByteSize + rare_action_probability?: double + rarely_abort_writes?: boolean + read_node_count?: integer + register_operation_count?: integer + seed?: integer + timeout?: Duration +} + +export interface SnapshotRepositoryAnalyzeResponse { + blob_count: integer + blob_path: string + concurrency: integer + coordinating_node: SnapshotRepositoryAnalyzeNodeInfo + delete_elapsed: Duration + delete_elapsed_nanos: DurationValue + details: SnapshotRepositoryAnalyzeDetailsInfo + early_read_node_count: integer + issues_detected: string[] + listing_elapsed: Duration + listing_elapsed_nanos: DurationValue + max_blob_size: ByteSize + max_blob_size_bytes: long + max_total_data_size: ByteSize + max_total_data_size_bytes: long + rare_action_probability: double + read_node_count: integer + repository: string + seed: long + summary: SnapshotRepositoryAnalyzeSummaryInfo +} + +export interface SnapshotRepositoryAnalyzeSummaryInfo { + read: SnapshotRepositoryAnalyzeReadSummaryInfo + write: SnapshotRepositoryAnalyzeWriteSummaryInfo +} + +export interface SnapshotRepositoryAnalyzeWriteSummaryInfo { + count: integer + total_elapsed: Duration + total_elapsed_nanos: DurationValue + total_size: ByteSize + total_size_bytes: long + total_throttled: Duration + total_throttled_nanos: long +} + export interface SnapshotRepositoryVerifyIntegrityRequest extends RequestBase { name: Names meta_thread_pool_concurrency?: integer @@ -19566,7 +19924,6 @@ export interface TasksListRequest extends RequestBase { group_by?: TasksGroupBy nodes?: NodeIds parent_task_id?: Id - master_timeout?: Duration timeout?: Duration wait_for_completion?: boolean } @@ -19935,6 +20292,7 @@ export type TransformPutTransformResponse = AcknowledgedResponseBase export interface TransformResetTransformRequest extends RequestBase { transform_id: Id force?: boolean + timeout?: Duration } export type TransformResetTransformResponse = AcknowledgedResponseBase @@ -20649,6 +21007,7 @@ export interface WatcherQueryWatchesResponse { } export interface WatcherStartRequest extends RequestBase { + master_timeout?: Duration } export type WatcherStartResponse = AcknowledgedResponseBase @@ -20915,7 +21274,7 @@ export interface XpackUsageIlm { export interface XpackUsageIlmPolicyStatistics { indices_managed: integer - phases: IlmPhases + phases: XpackUsagePhases } export interface XpackUsageInvocations { @@ -21027,6 +21386,19 @@ export interface XpackUsageMonitoring extends XpackUsageBase { enabled_exporters: Record } +export interface XpackUsagePhase { + actions: string[] + min_age: DurationValue +} + +export interface XpackUsagePhases { + cold?: XpackUsagePhase + delete?: XpackUsagePhase + frozen?: XpackUsagePhase + hot?: XpackUsagePhase + warm?: XpackUsagePhase +} + export interface XpackUsageQuery { count?: integer failed?: integer diff --git a/src/api/typesWithBodyKey.ts b/src/api/typesWithBodyKey.ts index 38ec3b81f..5f44fcb67 100644 --- a/src/api/typesWithBodyKey.ts +++ b/src/api/typesWithBodyKey.ts @@ -1897,6 +1897,7 @@ export interface SearchShardsRequest extends RequestBase { expand_wildcards?: ExpandWildcards ignore_unavailable?: boolean local?: boolean + master_timeout?: Duration preference?: string routing?: Routing } @@ -2497,6 +2498,7 @@ export interface KnnQuery extends QueryDslQueryBase { k?: integer filter?: QueryDslQueryContainer | QueryDslQueryContainer[] similarity?: float + rescore_vector?: RescoreVector } export interface KnnRetriever extends RetrieverBase { @@ -2506,6 +2508,7 @@ export interface KnnRetriever extends RetrieverBase { k: integer num_candidates: integer similarity?: float + rescore_vector?: RescoreVector } export interface KnnSearch { @@ -2518,6 +2521,7 @@ export interface KnnSearch { filter?: QueryDslQueryContainer | QueryDslQueryContainer[] similarity?: float inner_hits?: SearchInnerHits + rescore_vector?: RescoreVector } export interface LatLonGeoLocation { @@ -2698,6 +2702,10 @@ export interface RequestCacheStats { miss_count: long } +export interface RescoreVector { + oversample: float +} + export type Result = 'created' | 'updated' | 'deleted' | 'not_found' | 'noop' export interface Retries { @@ -2905,6 +2913,8 @@ export interface StoredScript { source: string } +export type StreamResult = ArrayBuffer + export type SuggestMode = 'missing' | 'popular' | 'always' export type SuggestionName = string @@ -5401,6 +5411,11 @@ export interface MappingCorePropertyBase extends MappingPropertyBase { store?: boolean } +export interface MappingCountedKeywordProperty extends MappingPropertyBase { + type: 'counted_keyword' + index?: boolean +} + export interface MappingDataStreamTimestamp { enabled: boolean } @@ -5521,7 +5536,7 @@ export interface MappingFieldNamesField { enabled: boolean } -export type MappingFieldType = 'none' | 'geo_point' | 'geo_shape' | 'ip' | 'binary' | 'keyword' | 'text' | 'search_as_you_type' | 'date' | 'date_nanos' | 'boolean' | 'completion' | 'nested' | 'object' | 'passthrough' | 'version' | 'murmur3' | 'token_count' | 'percolator' | 'integer' | 'long' | 'short' | 'byte' | 'float' | 'half_float' | 'scaled_float' | 'double' | 'integer_range' | 'float_range' | 'long_range' | 'double_range' | 'date_range' | 'ip_range' | 'alias' | 'join' | 'rank_feature' | 'rank_features' | 'flattened' | 'shape' | 'histogram' | 'constant_keyword' | 'aggregate_metric_double' | 'dense_vector' | 'semantic_text' | 'sparse_vector' | 'match_only_text' | 'icu_collation_keyword' +export type MappingFieldType = 'none' | 'geo_point' | 'geo_shape' | 'ip' | 'binary' | 'keyword' | 'text' | 'search_as_you_type' | 'date' | 'date_nanos' | 'boolean' | 'completion' | 'nested' | 'object' | 'passthrough' | 'version' | 'murmur3' | 'token_count' | 'percolator' | 'integer' | 'long' | 'short' | 'byte' | 'float' | 'half_float' | 'scaled_float' | 'double' | 'integer_range' | 'float_range' | 'long_range' | 'double_range' | 'date_range' | 'ip_range' | 'alias' | 'join' | 'rank_feature' | 'rank_features' | 'flattened' | 'shape' | 'histogram' | 'constant_keyword' | 'counted_keyword' | 'aggregate_metric_double' | 'dense_vector' | 'semantic_text' | 'sparse_vector' | 'match_only_text' | 'icu_collation_keyword' export interface MappingFlattenedProperty extends MappingPropertyBase { boost?: double @@ -5716,7 +5731,7 @@ export interface MappingPointProperty extends MappingDocValuesPropertyBase { type: 'point' } -export type MappingProperty = MappingBinaryProperty | MappingBooleanProperty | MappingDynamicProperty | MappingJoinProperty | MappingKeywordProperty | MappingMatchOnlyTextProperty | MappingPercolatorProperty | MappingRankFeatureProperty | MappingRankFeaturesProperty | MappingSearchAsYouTypeProperty | MappingTextProperty | MappingVersionProperty | MappingWildcardProperty | MappingDateNanosProperty | MappingDateProperty | MappingAggregateMetricDoubleProperty | MappingDenseVectorProperty | MappingFlattenedProperty | MappingNestedProperty | MappingObjectProperty | MappingPassthroughObjectProperty | MappingSemanticTextProperty | MappingSparseVectorProperty | MappingCompletionProperty | MappingConstantKeywordProperty | MappingFieldAliasProperty | MappingHistogramProperty | MappingIpProperty | MappingMurmur3HashProperty | MappingTokenCountProperty | MappingGeoPointProperty | MappingGeoShapeProperty | MappingPointProperty | MappingShapeProperty | MappingByteNumberProperty | MappingDoubleNumberProperty | MappingFloatNumberProperty | MappingHalfFloatNumberProperty | MappingIntegerNumberProperty | MappingLongNumberProperty | MappingScaledFloatNumberProperty | MappingShortNumberProperty | MappingUnsignedLongNumberProperty | MappingDateRangeProperty | MappingDoubleRangeProperty | MappingFloatRangeProperty | MappingIntegerRangeProperty | MappingIpRangeProperty | MappingLongRangeProperty | MappingIcuCollationProperty +export type MappingProperty = MappingBinaryProperty | MappingBooleanProperty | MappingDynamicProperty | MappingJoinProperty | MappingKeywordProperty | MappingMatchOnlyTextProperty | MappingPercolatorProperty | MappingRankFeatureProperty | MappingRankFeaturesProperty | MappingSearchAsYouTypeProperty | MappingTextProperty | MappingVersionProperty | MappingWildcardProperty | MappingDateNanosProperty | MappingDateProperty | MappingAggregateMetricDoubleProperty | MappingDenseVectorProperty | MappingFlattenedProperty | MappingNestedProperty | MappingObjectProperty | MappingPassthroughObjectProperty | MappingSemanticTextProperty | MappingSparseVectorProperty | MappingCompletionProperty | MappingConstantKeywordProperty | MappingCountedKeywordProperty | MappingFieldAliasProperty | MappingHistogramProperty | MappingIpProperty | MappingMurmur3HashProperty | MappingTokenCountProperty | MappingGeoPointProperty | MappingGeoShapeProperty | MappingPointProperty | MappingShapeProperty | MappingByteNumberProperty | MappingDoubleNumberProperty | MappingFloatNumberProperty | MappingHalfFloatNumberProperty | MappingIntegerNumberProperty | MappingLongNumberProperty | MappingScaledFloatNumberProperty | MappingShortNumberProperty | MappingUnsignedLongNumberProperty | MappingDateRangeProperty | MappingDoubleRangeProperty | MappingFloatRangeProperty | MappingIntegerRangeProperty | MappingIpRangeProperty | MappingLongRangeProperty | MappingIcuCollationProperty export interface MappingPropertyBase { meta?: Record @@ -6997,7 +7012,7 @@ export type CatAllocationResponse = CatAllocationAllocationRecord[] export interface CatComponentTemplatesComponentTemplate { name: string - version: string + version: string | null alias_count: string mapping_count: string settings_count: string @@ -8786,12 +8801,14 @@ export interface CcrShardStats { export interface CcrDeleteAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration } export type CcrDeleteAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrFollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration wait_for_active_shards?: WaitForActiveShards /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { @@ -8843,6 +8860,7 @@ export type CcrFollowInfoFollowerIndexStatus = 'active' | 'paused' export interface CcrFollowInfoRequest extends RequestBase { index: Indices + master_timeout?: Duration } export interface CcrFollowInfoResponse { @@ -8851,6 +8869,7 @@ export interface CcrFollowInfoResponse { export interface CcrFollowStatsRequest extends RequestBase { index: Indices + timeout?: Duration } export interface CcrFollowStatsResponse { @@ -8859,6 +8878,7 @@ export interface CcrFollowStatsResponse { export interface CcrForgetFollowerRequest extends RequestBase { index: IndexName + timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { follower_cluster?: string @@ -8888,6 +8908,7 @@ export interface CcrGetAutoFollowPatternAutoFollowPatternSummary { export interface CcrGetAutoFollowPatternRequest extends RequestBase { name?: Name + master_timeout?: Duration } export interface CcrGetAutoFollowPatternResponse { @@ -8896,18 +8917,21 @@ export interface CcrGetAutoFollowPatternResponse { export interface CcrPauseAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration } export type CcrPauseAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrPauseFollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration } export type CcrPauseFollowResponse = AcknowledgedResponseBase export interface CcrPutAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { remote_cluster: string @@ -8932,12 +8956,14 @@ export type CcrPutAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrResumeAutoFollowPatternRequest extends RequestBase { name: Name + master_timeout?: Duration } export type CcrResumeAutoFollowPatternResponse = AcknowledgedResponseBase export interface CcrResumeFollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { max_outstanding_read_requests?: long @@ -8974,6 +9000,8 @@ export interface CcrStatsFollowStats { } export interface CcrStatsRequest extends RequestBase { + master_timeout?: Duration + timeout?: Duration } export interface CcrStatsResponse { @@ -8983,6 +9011,7 @@ export interface CcrStatsResponse { export interface CcrUnfollowRequest extends RequestBase { index: IndexName + master_timeout?: Duration } export type CcrUnfollowResponse = AcknowledgedResponseBase @@ -9073,6 +9102,7 @@ export interface ClusterAllocationExplainNodeDiskUsage { export interface ClusterAllocationExplainRequest extends RequestBase { include_disk_info?: boolean include_yes_decisions?: boolean + master_timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { current_node?: string @@ -9138,6 +9168,7 @@ export interface ClusterDeleteComponentTemplateRequest extends RequestBase { export type ClusterDeleteComponentTemplateResponse = AcknowledgedResponseBase export interface ClusterDeleteVotingConfigExclusionsRequest extends RequestBase { + master_timeout?: Duration wait_for_removal?: boolean } @@ -9270,6 +9301,7 @@ export interface ClusterPendingTasksResponse { export interface ClusterPostVotingConfigExclusionsRequest extends RequestBase { node_names?: Names node_ids?: Ids + master_timeout?: Duration timeout?: Duration } @@ -10316,6 +10348,7 @@ export interface EnrichSummary { export interface EnrichDeletePolicyRequest extends RequestBase { name: Name + master_timeout?: Duration } export type EnrichDeletePolicyResponse = AcknowledgedResponseBase @@ -10328,6 +10361,7 @@ export interface EnrichExecutePolicyExecuteEnrichPolicyStatus { export interface EnrichExecutePolicyRequest extends RequestBase { name: Name + master_timeout?: Duration wait_for_completion?: boolean } @@ -10338,6 +10372,7 @@ export interface EnrichExecutePolicyResponse { export interface EnrichGetPolicyRequest extends RequestBase { name?: Names + master_timeout?: Duration } export interface EnrichGetPolicyResponse { @@ -10346,6 +10381,7 @@ export interface EnrichGetPolicyResponse { export interface EnrichPutPolicyRequest extends RequestBase { name: Name + master_timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { geo_match?: EnrichPolicy @@ -10381,6 +10417,7 @@ export interface EnrichStatsExecutingPolicy { } export interface EnrichStatsRequest extends RequestBase { + master_timeout?: Duration } export interface EnrichStatsResponse { @@ -10476,6 +10513,8 @@ export type EqlSearchResponse = EqlEqlSearchResponseBase> + } +} + +export interface EsqlAsyncQueryResponse { + columns?: EsqlColumns + id?: string + is_running: boolean +} + +export interface EsqlAsyncQueryDeleteRequest extends RequestBase { + id: Id +} + +export type EsqlAsyncQueryDeleteResponse = AcknowledgedResponseBase + +export interface EsqlAsyncQueryGetRequest extends RequestBase { + id: Id + drop_null_columns?: boolean + keep_alive?: Duration + wait_for_completion_timeout?: Duration +} + +export interface EsqlAsyncQueryGetResponse { + columns?: EsqlColumns + is_running: boolean +} export interface EsqlQueryRequest extends RequestBase { - format?: EsqlQueryEsqlFormat + format?: EsqlEsqlFormat delimiter?: string drop_null_columns?: boolean /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ @@ -10517,6 +10597,7 @@ export interface FeaturesFeature { } export interface FeaturesGetFeaturesRequest extends RequestBase { + master_timeout?: Duration } export interface FeaturesGetFeaturesResponse { @@ -10524,6 +10605,7 @@ export interface FeaturesGetFeaturesResponse { } export interface FeaturesResetFeaturesRequest extends RequestBase { + master_timeout?: Duration } export interface FeaturesResetFeaturesResponse { @@ -10766,7 +10848,7 @@ export interface IlmMigrateAction { export interface IlmPhase { actions?: IlmActions - min_age?: Duration | long + min_age?: Duration } export interface IlmPhases { @@ -10866,7 +10948,6 @@ export interface IlmExplainLifecycleRequest extends RequestBase { only_errors?: boolean only_managed?: boolean master_timeout?: Duration - timeout?: Duration } export interface IlmExplainLifecycleResponse { @@ -11204,6 +11285,7 @@ export interface IndicesIndexSettingsLifecycle { parse_origination_date?: boolean step?: IndicesIndexSettingsLifecycleStep rollover_alias?: string + prefer_ilm?: boolean | string } export interface IndicesIndexSettingsLifecycleStep { @@ -11555,6 +11637,12 @@ export interface IndicesAnalyzeTokenDetail { tokens: IndicesAnalyzeExplainAnalyzeToken[] } +export interface IndicesCancelMigrateReindexRequest extends RequestBase { + index: Indices +} + +export type IndicesCancelMigrateReindexResponse = AcknowledgedResponseBase + export interface IndicesClearCacheRequest extends RequestBase { index?: Indices allow_no_indices?: boolean @@ -11639,6 +11727,25 @@ export interface IndicesCreateDataStreamRequest extends RequestBase { export type IndicesCreateDataStreamResponse = AcknowledgedResponseBase +export interface IndicesCreateFromCreateFrom { + mappings_override?: MappingTypeMapping + settings_override?: IndicesIndexSettings + remove_index_blocks?: boolean +} + +export interface IndicesCreateFromRequest extends RequestBase { + source: IndexName + dest: IndexName + /** @deprecated The use of the 'body' key has been deprecated, use 'create_from' instead. */ + body?: IndicesCreateFromCreateFrom +} + +export interface IndicesCreateFromResponse { + acknowledged: boolean + index: IndexName + shards_acknowledged: boolean +} + export interface IndicesDataStreamsStatsDataStreamsStatsItem { backing_indices: integer data_stream: Name @@ -11828,8 +11935,6 @@ export interface IndicesFieldUsageStatsRequest extends RequestBase { expand_wildcards?: ExpandWildcards ignore_unavailable?: boolean fields?: Fields - master_timeout?: Duration - timeout?: Duration wait_for_active_shards?: WaitForActiveShards } @@ -12005,6 +12110,34 @@ export interface IndicesGetMappingRequest extends RequestBase { export type IndicesGetMappingResponse = Record +export interface IndicesGetMigrateReindexStatusRequest extends RequestBase { + index: Indices +} + +export interface IndicesGetMigrateReindexStatusResponse { + start_time?: DateTime + start_time_millis: EpochTime + complete: boolean + total_indices_in_data_stream: integer + total_indices_requiring_upgrade: integer + successes: integer + in_progress: IndicesGetMigrateReindexStatusStatusInProgress[] + pending: integer + errors: IndicesGetMigrateReindexStatusStatusError[] + exception?: string +} + +export interface IndicesGetMigrateReindexStatusStatusError { + index: string + message: string +} + +export interface IndicesGetMigrateReindexStatusStatusInProgress { + index: string + total_doc_count: long + reindexed_doc_count: long +} + export interface IndicesGetSettingsRequest extends RequestBase { index?: Indices name?: Names @@ -12028,6 +12161,24 @@ export interface IndicesGetTemplateRequest extends RequestBase { export type IndicesGetTemplateResponse = Record +export interface IndicesMigrateReindexMigrateReindex { + mode: IndicesMigrateReindexModeEnum + source: IndicesMigrateReindexSourceIndex +} + +export type IndicesMigrateReindexModeEnum = 'upgrade' + +export interface IndicesMigrateReindexRequest extends RequestBase { + /** @deprecated The use of the 'body' key has been deprecated, use 'reindex' instead. */ + body?: IndicesMigrateReindexMigrateReindex +} + +export type IndicesMigrateReindexResponse = AcknowledgedResponseBase + +export interface IndicesMigrateReindexSourceIndex { + index: IndexName +} + export interface IndicesMigrateToDataStreamRequest extends RequestBase { name: IndexName master_timeout?: Duration @@ -12939,6 +13090,93 @@ export interface InferencePutRequest extends RequestBase { export type InferencePutResponse = InferenceInferenceEndpointInfo +export interface InferenceStreamInferenceRequest extends RequestBase { + inference_id: Id + task_type?: InferenceTaskType + /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ + body?: { + input: string | string[] + } +} + +export type InferenceStreamInferenceResponse = StreamResult + +export interface InferenceUnifiedInferenceCompletionTool { + type: string + function: InferenceUnifiedInferenceCompletionToolFunction +} + +export interface InferenceUnifiedInferenceCompletionToolChoice { + type: string + function: InferenceUnifiedInferenceCompletionToolChoiceFunction +} + +export interface InferenceUnifiedInferenceCompletionToolChoiceFunction { + name: string +} + +export interface InferenceUnifiedInferenceCompletionToolFunction { + description?: string + name: string + parameters?: any + strict?: boolean +} + +export type InferenceUnifiedInferenceCompletionToolType = string | InferenceUnifiedInferenceCompletionToolChoice + +export interface InferenceUnifiedInferenceContentObject { + text: string + type: string +} + +export interface InferenceUnifiedInferenceMessage { + content?: InferenceUnifiedInferenceMessageContent + role: string + tool_call_id?: Id + tool_calls?: InferenceUnifiedInferenceToolCall[] +} + +export type InferenceUnifiedInferenceMessageContent = string | InferenceUnifiedInferenceContentObject[] + +export interface InferenceUnifiedInferenceRequest extends RequestBase { + task_type?: InferenceTaskType + inference_id: Id + timeout?: Duration + /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ + body?: { + messages: InferenceUnifiedInferenceMessage[] + model?: string + max_completion_tokens?: long + stop?: string[] + temperature?: float + tool_choice?: InferenceUnifiedInferenceCompletionToolType + tools?: InferenceUnifiedInferenceCompletionTool[] + top_p?: float + } +} + +export type InferenceUnifiedInferenceResponse = StreamResult + +export interface InferenceUnifiedInferenceToolCall { + id: Id + function: InferenceUnifiedInferenceToolCallFunction + type: string +} + +export interface InferenceUnifiedInferenceToolCallFunction { + arguments: string + name: string +} + +export interface InferenceUpdateRequest extends RequestBase { + inference_id: Id + task_type?: InferenceTaskType + /** @deprecated The use of the 'body' key has been deprecated, use 'inference_config' instead. */ + body?: InferenceInferenceEndpoint +} + +export type InferenceUpdateResponse = InferenceInferenceEndpointInfo + export interface IngestAppendProcessor extends IngestProcessorBase { field: Field value: any | any[] @@ -13516,7 +13754,6 @@ export interface IngestGetGeoipDatabaseDatabaseConfigurationMetadata { export interface IngestGetGeoipDatabaseRequest extends RequestBase { id?: Ids - master_timeout?: Duration } export interface IngestGetGeoipDatabaseResponse { @@ -13628,6 +13865,8 @@ export type LicenseLicenseStatus = 'active' | 'valid' | 'invalid' | 'expired' export type LicenseLicenseType = 'missing' | 'trial' | 'basic' | 'standard' | 'dev' | 'silver' | 'gold' | 'platinum' | 'enterprise' export interface LicenseDeleteRequest extends RequestBase { + master_timeout?: Duration + timeout?: Duration } export type LicenseDeleteResponse = AcknowledgedResponseBase @@ -13677,6 +13916,8 @@ export interface LicensePostAcknowledgement { export interface LicensePostRequest extends RequestBase { acknowledge?: boolean + master_timeout?: Duration + timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { license?: LicenseLicense @@ -13692,6 +13933,8 @@ export interface LicensePostResponse { export interface LicensePostStartBasicRequest extends RequestBase { acknowledge?: boolean + master_timeout?: Duration + timeout?: Duration } export interface LicensePostStartBasicResponse { @@ -13705,6 +13948,7 @@ export interface LicensePostStartBasicResponse { export interface LicensePostStartTrialRequest extends RequestBase { acknowledge?: boolean type_query_string?: string + master_timeout?: Duration } export interface LicensePostStartTrialResponse { @@ -15216,6 +15460,7 @@ export type MlDeleteModelSnapshotResponse = AcknowledgedResponseBase export interface MlDeleteTrainedModelRequest extends RequestBase { model_id: Id force?: boolean + timeout?: Duration } export type MlDeleteTrainedModelResponse = AcknowledgedResponseBase @@ -15603,7 +15848,6 @@ export interface MlGetMemoryStatsMemory { export interface MlGetMemoryStatsRequest extends RequestBase { node_id?: Id - human?: boolean master_timeout?: Duration timeout?: Duration } @@ -16994,7 +17238,6 @@ export interface NodesHotThreadsRequest extends RequestBase { ignore_idle_threads?: boolean interval?: Duration snapshots?: long - master_timeout?: Duration threads?: long timeout?: Duration type?: ThreadType @@ -17356,7 +17599,6 @@ export interface NodesInfoRequest extends RequestBase { node_id?: NodeIds metric?: Metrics flat_settings?: boolean - master_timeout?: Duration timeout?: Duration } @@ -17393,7 +17635,6 @@ export interface NodesStatsRequest extends RequestBase { groups?: boolean include_segment_file_sizes?: boolean level?: Level - master_timeout?: Duration timeout?: Duration types?: string[] include_unloaded_segments?: boolean @@ -17883,8 +18124,6 @@ export interface SearchableSnapshotsClearCacheRequest extends RequestBase { expand_wildcards?: ExpandWildcards allow_no_indices?: boolean ignore_unavailable?: boolean - pretty?: boolean - human?: boolean } export type SearchableSnapshotsClearCacheResponse = any @@ -18111,6 +18350,10 @@ export interface SecuritySearchAccess { allow_restricted_indices?: boolean } +export interface SecuritySecuritySettings { + index?: IndicesIndexSettings +} + export type SecurityTemplateFormat = 'string' | 'json' export interface SecurityUser { @@ -18591,6 +18834,16 @@ export interface SecurityGetServiceCredentialsResponse { nodes_credentials: SecurityGetServiceCredentialsNodesCredentials } +export interface SecurityGetSettingsRequest extends RequestBase { + master_timeout?: Duration +} + +export interface SecurityGetSettingsResponse { + security: SecuritySecuritySettings + 'security-profile': SecuritySecuritySettings + 'security-tokens': SecuritySecuritySettings +} + export type SecurityGetTokenAccessTokenGrantType = 'password' | 'client_credentials' | '_kerberos' | 'refresh_token' export interface SecurityGetTokenAuthenticatedUser extends SecurityUser { @@ -19183,6 +19436,21 @@ export interface SecurityUpdateCrossClusterApiKeyResponse { updated: boolean } +export interface SecurityUpdateSettingsRequest extends RequestBase { + master_timeout?: Duration + timeout?: Duration + /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ + body?: { + security?: SecuritySecuritySettings + 'security-profile'?: SecuritySecuritySettings + 'security-tokens'?: SecuritySecuritySettings + } +} + +export interface SecurityUpdateSettingsResponse { + acknowledged: boolean +} + export interface SecurityUpdateUserProfileDataRequest extends RequestBase { uid: SecurityUserProfileId if_seq_no?: SequenceNumber @@ -19229,7 +19497,6 @@ export interface ShutdownGetNodePluginsStatus { export interface ShutdownGetNodeRequest extends RequestBase { node_id?: NodeIds master_timeout?: TimeUnit - timeout?: TimeUnit } export interface ShutdownGetNodeResponse { @@ -19647,7 +19914,6 @@ export interface SnapshotCloneRequest extends RequestBase { snapshot: Name target_snapshot: Name master_timeout?: Duration - timeout?: Duration /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { indices: string @@ -19743,6 +20009,113 @@ export interface SnapshotGetRepositoryRequest extends RequestBase { export type SnapshotGetRepositoryResponse = Record +export interface SnapshotRepositoryAnalyzeBlobDetails { + name: string + overwritten: boolean + read_early: boolean + read_end: long + read_start: long + reads: SnapshotRepositoryAnalyzeReadBlobDetails + size: ByteSize + size_bytes: long +} + +export interface SnapshotRepositoryAnalyzeDetailsInfo { + blob: SnapshotRepositoryAnalyzeBlobDetails + overwrite_elapsed?: Duration + overwrite_elapsed_nanos?: DurationValue + write_elapsed: Duration + write_elapsed_nanos: DurationValue + write_throttled: Duration + write_throttled_nanos: DurationValue + writer_node: SnapshotRepositoryAnalyzeNodeInfo +} + +export interface SnapshotRepositoryAnalyzeNodeInfo { + id: Id + name: Name +} + +export interface SnapshotRepositoryAnalyzeReadBlobDetails { + before_write_complete?: boolean + elapsed?: Duration + elapsed_nanos?: DurationValue + first_byte_time?: Duration + first_byte_time_nanos: DurationValue + found: boolean + node: SnapshotRepositoryAnalyzeNodeInfo + throttled?: Duration + throttled_nanos?: DurationValue +} + +export interface SnapshotRepositoryAnalyzeReadSummaryInfo { + count: integer + max_wait: Duration + max_wait_nanos: DurationValue + total_elapsed: Duration + total_elapsed_nanos: DurationValue + total_size: ByteSize + total_size_bytes: long + total_throttled: Duration + total_throttled_nanos: DurationValue + total_wait: Duration + total_wait_nanos: DurationValue +} + +export interface SnapshotRepositoryAnalyzeRequest extends RequestBase { + name: Name + blob_count?: integer + concurrency?: integer + detailed?: boolean + early_read_node_count?: integer + max_blob_size?: ByteSize + max_total_data_size?: ByteSize + rare_action_probability?: double + rarely_abort_writes?: boolean + read_node_count?: integer + register_operation_count?: integer + seed?: integer + timeout?: Duration +} + +export interface SnapshotRepositoryAnalyzeResponse { + blob_count: integer + blob_path: string + concurrency: integer + coordinating_node: SnapshotRepositoryAnalyzeNodeInfo + delete_elapsed: Duration + delete_elapsed_nanos: DurationValue + details: SnapshotRepositoryAnalyzeDetailsInfo + early_read_node_count: integer + issues_detected: string[] + listing_elapsed: Duration + listing_elapsed_nanos: DurationValue + max_blob_size: ByteSize + max_blob_size_bytes: long + max_total_data_size: ByteSize + max_total_data_size_bytes: long + rare_action_probability: double + read_node_count: integer + repository: string + seed: long + summary: SnapshotRepositoryAnalyzeSummaryInfo +} + +export interface SnapshotRepositoryAnalyzeSummaryInfo { + read: SnapshotRepositoryAnalyzeReadSummaryInfo + write: SnapshotRepositoryAnalyzeWriteSummaryInfo +} + +export interface SnapshotRepositoryAnalyzeWriteSummaryInfo { + count: integer + total_elapsed: Duration + total_elapsed_nanos: DurationValue + total_size: ByteSize + total_size_bytes: long + total_throttled: Duration + total_throttled_nanos: long +} + export interface SnapshotRepositoryVerifyIntegrityRequest extends RequestBase { name: Names meta_thread_pool_concurrency?: integer @@ -20094,7 +20467,6 @@ export interface TasksListRequest extends RequestBase { group_by?: TasksGroupBy nodes?: NodeIds parent_task_id?: Id - master_timeout?: Duration timeout?: Duration wait_for_completion?: boolean } @@ -20476,6 +20848,7 @@ export type TransformPutTransformResponse = AcknowledgedResponseBase export interface TransformResetTransformRequest extends RequestBase { transform_id: Id force?: boolean + timeout?: Duration } export type TransformResetTransformResponse = AcknowledgedResponseBase @@ -21202,6 +21575,7 @@ export interface WatcherQueryWatchesResponse { } export interface WatcherStartRequest extends RequestBase { + master_timeout?: Duration } export type WatcherStartResponse = AcknowledgedResponseBase @@ -21471,7 +21845,7 @@ export interface XpackUsageIlm { export interface XpackUsageIlmPolicyStatistics { indices_managed: integer - phases: IlmPhases + phases: XpackUsagePhases } export interface XpackUsageInvocations { @@ -21583,6 +21957,19 @@ export interface XpackUsageMonitoring extends XpackUsageBase { enabled_exporters: Record } +export interface XpackUsagePhase { + actions: string[] + min_age: DurationValue +} + +export interface XpackUsagePhases { + cold?: XpackUsagePhase + delete?: XpackUsagePhase + frozen?: XpackUsagePhase + hot?: XpackUsagePhase + warm?: XpackUsagePhase +} + export interface XpackUsageQuery { count?: integer failed?: integer