Get master node information

GET /_cat/master

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.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local 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 string

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
  
  node id
- host string
  
  host name
- ip string
  
  ip address
- node string
  
  node name

GET /_cat/master

curl \
 --request GET 'http://api.example.com/_cat/master' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_cat/master?v=true&format=json`.

[
  {
    "id": "YzWoH_2BT-6UjVGDyPdqYg",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "node": "YzWoH_2"
  }
]

Get transform information Added in 7.7.0

GET /_cat/transforms/{transform_id}

Api key auth Basic auth Bearer auth

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.

Path parameters

transform_id string Required

A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.

Query parameters

allow_no_match boolean

Specifies what to do when the request: 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 true, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. If false, the request returns a 404 status code when there are no matches or only partial matches.
from number

Skips the specified number of transforms.
h string | array[string]
Comma-separated list of column names to display.

Supported values include:
- changes_last_detection_time (or cldt): The timestamp when changes were last detected in the source indices.
- checkpoint (or cp): The sequence number for the checkpoint.
- checkpoint_duration_time_exp_avg (or cdtea, checkpointTimeExpAvg): Exponential moving average of the duration of the checkpoint, in milliseconds.
- checkpoint_progress (or c, checkpointProgress): The progress of the next checkpoint that is currently in progress.
- create_time (or ct, createTime): The time the transform was created.
- delete_time (or dtime): The amount of time spent deleting, in milliseconds.
- description (or d): The description of the transform.
- dest_index (or di, destIndex): The destination index for the transform. The mappings of the destination index are deduced based on the source fields when possible. If alternate mappings are required, use the Create index API prior to starting the transform.
- documents_deleted (or docd): The number of documents that have been deleted from the destination index due to the retention policy for this transform.
- documents_indexed (or doci): The number of documents that have been indexed into the destination index for the transform.
- docs_per_second (or dps): Specifies a limit on the number of input documents per second. This setting throttles the transform by adding a wait time between search requests. The default value is null, which disables throttling.
- documents_processed (or docp): The number of documents that have been processed from the source index of the transform.
- frequency (or f): The interval between checks for changes in the source indices when the transform is running continuously. Also determines the retry interval in the event of transient failures while the transform is searching or indexing. The minimum value is 1s and the maximum is 1h. The default value is 1m.
- id: Identifier for the transform.
- index_failure (or if): The number of indexing failures.
- index_time (or itime): The amount of time spent indexing, in milliseconds.
- index_total (or it): The number of index operations.
- indexed_documents_exp_avg (or idea): Exponential moving average of the number of new documents that have been indexed.
- last_search_time (or lst, lastSearchTime): The timestamp of the last search in the source indices. This field is only shown if the transform is running.
- max_page_search_size (or mpsz): Defines the initial page size to use for the composite aggregation for each checkpoint. If circuit breaker exceptions occur, the page size is dynamically adjusted to a lower value. The minimum value is 10 and the maximum is 65,536. The default value is 500.
- pages_processed (or pp): The number of search or bulk index operations processed. Documents are processed in batches instead of individually.
- pipeline (or p): The unique identifier for an ingest pipeline.
- processed_documents_exp_avg (or pdea): Exponential moving average of the number of documents that have been processed.
- processing_time (or pt): The amount of time spent processing results, in milliseconds.
- reason (or r): If a transform has a failed state, this property provides details about the reason for the failure.
- search_failure (or sf): The number of search failures.
- search_time (or stime): The amount of time spent searching, in milliseconds.
- search_total (or st): The number of search operations on the source index for the transform.
- source_index (or si, sourceIndex): The source indices for the transform. It can be a single index, an index pattern (for example, "my-index-*"), an array of indices (for example, ["my-index-000001", "my-index-000002"]), or an array of index patterns (for example, ["my-index-*", "my-other-index-*"]. For remote indices use the syntax "remote_name:index_name". If any indices are in remote clusters then the master node and at least one transform node must have the remote_cluster_client node role.
- state (or s): The status of the transform, which can be one of the following values:
  - aborting: The transform is aborting.
  - failed: The transform failed. For more information about the failure, check the reason field.
  - indexing: The transform is actively processing data and creating new documents.
  - started: The transform is running but not actively indexing data.
  - stopped: The transform is stopped.
  - stopping: The transform is stopping.
- transform_type (or tt): Indicates the type of transform: batch or continuous.
- trigger_count (or tc): The number of times the transform has been triggered by the scheduler. For example, the scheduler triggers the transform indexer to check for updates or ingest new data at an interval specified in the frequency property.
- version (or v): The version of Elasticsearch that existed on the node when the transform was created.
s string | array[string]
Comma-separated list of column names or column aliases used to sort the response.

Supported values include:
- changes_last_detection_time (or cldt): The timestamp when changes were last detected in the source indices.
- checkpoint (or cp): The sequence number for the checkpoint.
- checkpoint_duration_time_exp_avg (or cdtea, checkpointTimeExpAvg): Exponential moving average of the duration of the checkpoint, in milliseconds.
- checkpoint_progress (or c, checkpointProgress): The progress of the next checkpoint that is currently in progress.
- create_time (or ct, createTime): The time the transform was created.
- delete_time (or dtime): The amount of time spent deleting, in milliseconds.
- description (or d): The description of the transform.
- dest_index (or di, destIndex): The destination index for the transform. The mappings of the destination index are deduced based on the source fields when possible. If alternate mappings are required, use the Create index API prior to starting the transform.
- documents_deleted (or docd): The number of documents that have been deleted from the destination index due to the retention policy for this transform.
- documents_indexed (or doci): The number of documents that have been indexed into the destination index for the transform.
- docs_per_second (or dps): Specifies a limit on the number of input documents per second. This setting throttles the transform by adding a wait time between search requests. The default value is null, which disables throttling.
- documents_processed (or docp): The number of documents that have been processed from the source index of the transform.
- frequency (or f): The interval between checks for changes in the source indices when the transform is running continuously. Also determines the retry interval in the event of transient failures while the transform is searching or indexing. The minimum value is 1s and the maximum is 1h. The default value is 1m.
- id: Identifier for the transform.
- index_failure (or if): The number of indexing failures.
- index_time (or itime): The amount of time spent indexing, in milliseconds.
- index_total (or it): The number of index operations.
- indexed_documents_exp_avg (or idea): Exponential moving average of the number of new documents that have been indexed.
- last_search_time (or lst, lastSearchTime): The timestamp of the last search in the source indices. This field is only shown if the transform is running.
- max_page_search_size (or mpsz): Defines the initial page size to use for the composite aggregation for each checkpoint. If circuit breaker exceptions occur, the page size is dynamically adjusted to a lower value. The minimum value is 10 and the maximum is 65,536. The default value is 500.
- pages_processed (or pp): The number of search or bulk index operations processed. Documents are processed in batches instead of individually.
- pipeline (or p): The unique identifier for an ingest pipeline.
- processed_documents_exp_avg (or pdea): Exponential moving average of the number of documents that have been processed.
- processing_time (or pt): The amount of time spent processing results, in milliseconds.
- reason (or r): If a transform has a failed state, this property provides details about the reason for the failure.
- search_failure (or sf): The number of search failures.
- search_time (or stime): The amount of time spent searching, in milliseconds.
- search_total (or st): The number of search operations on the source index for the transform.
- source_index (or si, sourceIndex): The source indices for the transform. It can be a single index, an index pattern (for example, "my-index-*"), an array of indices (for example, ["my-index-000001", "my-index-000002"]), or an array of index patterns (for example, ["my-index-*", "my-other-index-*"]. For remote indices use the syntax "remote_name:index_name". If any indices are in remote clusters then the master node and at least one transform node must have the remote_cluster_client node role.
- state (or s): The status of the transform, which can be one of the following values:
  - aborting: The transform is aborting.
  - failed: The transform failed. For more information about the failure, check the reason field.
  - indexing: The transform is actively processing data and creating new documents.
  - started: The transform is running but not actively indexing data.
  - stopped: The transform is stopped.
  - stopping: The transform is stopping.
- transform_type (or tt): Indicates the type of transform: batch or continuous.
- trigger_count (or tc): The number of times the transform has been triggered by the scheduler. For example, the scheduler triggers the transform indexer to check for updates or ingest new data at an interval specified in the frequency property.
- version (or v): The version of Elasticsearch that existed on the node when the transform was created.
time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.
size number

The maximum number of transforms to obtain.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- state string
  
  The status of the transform. Returned values include: aborting: The transform is aborting. failed: The transform failed. For more information about the failure, check thereasonfield.indexing: The transform is actively processing data and creating new documents.started: The transform is running but not actively indexing data.stopped: The transform is stopped.stopping`: The transform is stopping.
- checkpoint string
  
  The sequence number for the checkpoint.
- documents_processed string
  
  The number of documents that have been processed from the source index of the transform.
- checkpoint_progress string | null
  
  The progress of the next checkpoint that is currently in progress.
  
  One of:
  string-1 string string-2 string | null
- last_search_time string | null
  
  The timestamp of the last search in the source indices. This field is shown only if the transform is running.
  
  One of:
  string-1 string string-2 string | null
- changes_last_detection_time string | null
  
  The timestamp when changes were last detected in the source indices.
  
  One of:
  string-1 string string-2 string | null
- create_time string
  
  The time the transform was created.
- version string
- source_index string
  
  The source indices for the transform.
- dest_index string
  
  The destination index for the transform.
- pipeline string
  
  The unique identifier for the ingest pipeline.
- description string
  
  The description of the transform.
- transform_type string
  
  The type of transform: batch or continuous.
- frequency string
  
  The interval between checks for changes in the source indices when the transform is running continuously.
- max_page_search_size string
  
  The initial page size that is used for the composite aggregation for each checkpoint.
- docs_per_second string
  
  The number of input documents per second.
- reason string
  
  If a transform has a failed state, these details describe the reason for failure.
- search_total string
  
  The total number of search operations on the source index for the transform.
- search_failure string
  
  The total number of search failures.
- search_time string
  
  The total amount of search time, in milliseconds.
- index_total string
  
  The total number of index operations done by the transform.
- index_failure string
  
  The total number of indexing failures.
- index_time string
  
  The total time spent indexing documents, in milliseconds.
- documents_indexed string
  
  The number of documents that have been indexed into the destination index for the transform.
- delete_time string
  
  The total time spent deleting documents, in milliseconds.
- documents_deleted string
  
  The number of documents deleted from the destination index due to the retention policy for the transform.
- trigger_count string
  
  The number of times the transform has been triggered by the scheduler. For example, the scheduler triggers the transform indexer to check for updates or ingest new data at an interval specified in the frequency property.
- pages_processed string
  
  The number of search or bulk index operations processed. Documents are processed in batches instead of individually.
- processing_time string
  
  The total time spent processing results, in milliseconds.
- checkpoint_duration_time_exp_avg string
  
  The exponential moving average of the duration of the checkpoint, in milliseconds.
- indexed_documents_exp_avg string
  
  The exponential moving average of the number of new documents that have been indexed.
- processed_documents_exp_avg string
  
  The exponential moving average of the number of documents that have been processed.

GET /_cat/transforms/{transform_id}

curl \
 --request GET 'http://api.example.com/_cat/transforms/{transform_id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_cat/transforms?v=true&format=json`.

[
  {
    "id" : "ecommerce_transform",
    "state" : "started",
    "checkpoint" : "1",
    "documents_processed" : "705",
    "checkpoint_progress" : "100.00",
    "changes_last_detection_time" : null
  }
]

Update the connector error field Technical preview

PUT /_connector/{connector_id}/_error

Api key auth Basic auth Bearer auth

Set the error field for the connector. If the error provided in the request body is non-null, the connector’s status is updated to error. Otherwise, if the error is reset to null, the connector status is updated to connected.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

error string | null

One of:
string-1 string NullValue string | null

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_error

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_error' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"error\": \"Houston, we have a problem!\"\n}"'

Request example

{
    "error": "Houston, we have a problem!"
}

Response examples (200)

{
  "result": "updated"
}

Update the connector pipeline Beta

PUT /_connector/{connector_id}/_pipeline

Api key auth Basic auth Bearer auth

When you create a new connector, the configuration of an ingest pipeline is populated with default settings.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

pipeline object Required
Hide pipeline attributes Show pipeline attributes object
- extract_binary_content boolean Required
- name string Required
- reduce_whitespace boolean Required
- run_ml_inference boolean Required

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_pipeline

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_pipeline' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"pipeline\": {\n        \"extract_binary_content\": true,\n        \"name\": \"my-connector-pipeline\",\n        \"reduce_whitespace\": true,\n        \"run_ml_inference\": true\n    }\n}"'

Request example

{
    "pipeline": {
        "extract_binary_content": true,
        "name": "my-connector-pipeline",
        "reduce_whitespace": true,
        "run_ml_inference": true
    }
}

Response examples (200)

{
  "result": "updated"
}

Get follower information Added in 6.7.0

GET /{index}/_ccr/info

Api key auth Basic auth Bearer auth

Get information about all cross-cluster replication follower indices. For example, the results include follower index names, leader index names, replication options, and whether the follower indices are active or paused.

External documentation

Path parameters

index string | array[string] Required

A comma-delimited list of follower index patterns.

Query parameters

master_timeout string

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. It can also be set to -1 to indicate that the request should never timeout.

Responses

200 application/json
Hide response attribute Show response attribute object
- follower_indices array[object] Required
  
  Hide follower_indices attributes Show follower_indices attributes object
  
  follower_index string Required
  
  leader_index string Required
  
  parameters object
  
  Hide parameters attributes Show parameters attributes object
  
  max_outstanding_read_requests number
  
  The maximum number of outstanding reads requests from the remote cluster.
  
  max_outstanding_write_requests number
  
  The maximum number of outstanding write requests on the follower.
  
  max_read_request_operation_count number
  
  The maximum number of operations to pull per read from the remote cluster.
  
  max_read_request_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_retry_delay string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_write_buffer_count number
  
  The maximum number of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the number of queued operations goes below the limit.
  
  max_write_buffer_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_write_request_operation_count number
  
  The maximum number of operations per bulk write request executed on the follower.
  
  max_write_request_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  read_poll_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  remote_cluster string Required
  
  status string Required
  
  Values are active or paused.

GET /{index}/_ccr/info

curl \
 --request GET 'http://api.example.com/{index}/_ccr/info' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /follower_index/_ccr/info` when the follower index is active.

{
  "follower_indices": [
    {
      "follower_index": "follower_index",
      "remote_cluster": "remote_cluster",
      "leader_index": "leader_index",
      "status": "active",
      "parameters": {
        "max_read_request_operation_count": 5120,
        "max_read_request_size": "32mb",
        "max_outstanding_read_requests": 12,
        "max_write_request_operation_count": 5120,
        "max_write_request_size": "9223372036854775807b",
        "max_outstanding_write_requests": 9,
        "max_write_buffer_count": 2147483647,
        "max_write_buffer_size": "512mb",
        "max_retry_delay": "500ms",
        "read_poll_timeout": "1m"
      }
    }
  ]
}

A successful response from `GET /follower_index/_ccr/info` when the follower index is paused.

{
  "follower_indices": [
    {
      "follower_index": "follower_index",
      "remote_cluster": "remote_cluster",
      "leader_index": "leader_index",
      "status": "paused"
    }
  ]
}

Get data stream stats Added in 7.9.0

GET /_data_stream/{name}/_stats

Api key auth Basic auth Bearer auth

Get statistics for one or more data streams.

Path parameters

name string Required

Comma-separated list of data streams used to limit the request. Wildcard expressions (*) are supported. To target all data streams in a cluster, omit this parameter or use *.

Query parameters

expand_wildcards string | array[string]
Type of data stream that wildcard patterns can match. Supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.

Responses

200 application/json
Hide response attributes Show response attributes object
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- backing_indices number Required
  
  Total number of backing indices for the selected data streams.
- data_stream_count number Required
  
  Total number of selected data streams.
- data_streams array[object] Required
  
  Contains statistics for the selected data streams.
  
  Hide data_streams attributes Show data_streams attributes object
  
  backing_indices number Required
  
  Current number of backing indices for the data stream.
  
  data_stream string Required
  
  maximum_timestamp number
  
  Time unit for milliseconds
  
  store_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  store_size_bytes number Required
  
  Total size, in bytes, of all shards for the data stream’s backing indices.
- total_store_sizes number | string
  
  One of:
  ByteSize number ByteSize string
- total_store_size_bytes number Required
  
  Total size, in bytes, of all shards for the selected data streams.

GET /_data_stream/{name}/_stats

curl \
 --request GET 'http://api.example.com/_data_stream/{name}/_stats' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response for retrieving statistics for a data stream.

{
  "_shards": {
    "total": 10,
    "successful": 5,
    "failed": 0
  },
  "data_stream_count": 2,
  "backing_indices": 5,
  "total_store_size": "7kb",
  "total_store_size_bytes": 7268,
  "data_streams": [
    {
      "data_stream": "my-data-stream",
      "backing_indices": 3,
      "store_size": "3.7kb",
      "store_size_bytes": 3772,
      "maximum_timestamp": 1607512028000
    },
    {
      "data_stream": "my-data-stream-two",
      "backing_indices": 2,
      "store_size": "3.4kb",
      "store_size_bytes": 3496,
      "maximum_timestamp": 1607425567000
    }
  ]
}

Update data streams Added in 7.16.0

POST /_data_stream/_modify

Api key auth Basic auth Bearer auth

Performs one or more data stream modification actions in a single atomic operation.

application/json

Body Required

actions array[object] Required

Actions to perform.
Hide actions attributes Show actions attributes object
- add_backing_index object
  Hide add_backing_index attributes Show add_backing_index attributes object
  
  data_stream string Required
  
  index string Required
- remove_backing_index object
  Hide remove_backing_index attributes Show remove_backing_index attributes object
  
  data_stream string Required
  
  index string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_data_stream/_modify

curl \
 --request POST 'http://api.example.com/_data_stream/_modify' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"actions":[{"add_backing_index":{"data_stream":"string","index":"string"},"remove_backing_index":{"data_stream":"string","index":"string"}}]}'

Delete documents Added in 5.0.0

POST /{index}/_delete_by_query

Api key auth Basic auth Bearer auth

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.

Path parameters

index string | array[string] Required

A comma-separated 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.

Query parameters

allow_no_indices 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 string

Analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.
analyze_wildcard boolean

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
conflicts string
What to do if delete by query hits version conflicts: abort or proceed.

Supported values include:
- abort: Stop reindexing if there are conflicts.
- proceed: Continue reindexing even if there are conflicts.
Values are abort or proceed.
default_operator string

The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

Values are and, AND, or, or OR.
df 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 string | array[string]
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 comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
from number

Skips the specified number of documents.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
lenient 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_docs number

The maximum number of documents to process. Defaults to all documents. When set to a value less then or equal to scroll_size, a scroll will not be used to retrieve the results for the operation.
preference string

The node or shard the operation should be performed on. It is random by default.
refresh 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 boolean

If true, the request cache is used for this request. Defaults to the index-level setting.
requests_per_second number

The throttle for this request in sub-requests per second.
routing string

A custom value used to route operations to a specific shard.
q string

A query in the Lucene query string syntax.
scroll string

The period to retain the search context for scrolling.
scroll_size number

The size of the scroll request that powers the operation.
search_timeout string

The explicit timeout for each search request. It defaults to no timeout.
search_type string
The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
slices number | string

The number of slices this task should be divided into.
sort array[string]

A comma-separated list of <field>:<direction> pairs.
stats array[string]

The specific tag of the request for logging and statistical purposes.
terminate_after 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 string

The period each deletion request waits for active shards.
version boolean

If true, returns the document version as part of a hit.
wait_for_active_shards number | string

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 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.

application/json

Body Required

max_docs number

The maximum number of documents to delete.
query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required

Responses

200 application/json
Hide response attributes Show response attributes object
- batches number
  
  The number of scroll responses pulled back by the delete by query.
- deleted number
  
  The number of documents that were successfully deleted.
- failures array[object]
  
  An array of failures if there were any unrecoverable errors during the process. If this array is not empty, the request ended abnormally because of those failures. Delete by query is implemented using batches and any failures cause the entire process to end but all failures in the current batch are collected into the array. You can use the conflicts option to prevent reindex from ending on version conflicts.
  
  Hide failures attributes Show failures attributes object
  
  cause object Required
  
  Hide cause attributes Show cause attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  id string Required
  
  index string Required
  
  status number Required
- noops number
  
  This field is always equal to zero for delete by query. It exists only so that delete by query, update by query, and reindex APIs return responses with the same structure.
- requests_per_second number
  
  The number of requests per second effectively run during the delete by query.
- retries object
  
  Hide retries attributes Show retries attributes object
  
  bulk number Required
  
  The number of bulk actions retried.
  
  search number Required
  
  The number of search actions retried.
- slice_id number
- task string | number
  
  One of:
  TaskId string TaskId number
- throttled string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- throttled_millis number
  
  Time unit for milliseconds
- throttled_until string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- throttled_until_millis number
  
  Time unit for milliseconds
- timed_out boolean
  
  If true, some requests run during the delete by query operation timed out.
- took number
  
  Time unit for milliseconds
- total number
  
  The number of documents that were successfully processed.
- version_conflicts number
  
  The number of version conflicts that the delete by query hit.

POST /{index}/_delete_by_query

curl \
 --request POST 'http://api.example.com/{index}/_delete_by_query' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"match_all\": {}\n  }\n}"'

Request examples

Run `POST /my-index-000001,my-index-000002/_delete_by_query` to delete all documents from multiple data streams or indices.

{
  "query": {
    "match_all": {}
  }
}

Run `POST my-index-000001/_delete_by_query` to delete a document by using a unique attribute.

{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  },
  "max_docs": 1
}

Run `POST my-index-000001/_delete_by_query` to slice a delete by query manually. Provide a slice ID and total number of slices.

{
  "slice": {
    "id": 0,
    "max": 2
  },
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}

Run `POST my-index-000001/_delete_by_query?refresh&slices=5` to let delete by query automatically parallelize using sliced scroll to slice on `_id`. The `slices` query parameter value specifies the number of slices to use.

{
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}

Response examples (200)

A successful response from `POST /my-index-000001/_delete_by_query`.

{
  "took" : 147,
  "timed_out": false,
  "total": 119,
  "deleted": 119,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1.0,
  "throttled_until_millis": 0,
  "failures" : [ ]
}

Delete a dangling index Added in 7.9.0

DELETE /_dangling/{index_uuid}

Api key auth Basic auth Bearer auth

If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

Path parameters

index_uuid string Required

The UUID of the index to delete. Use the get dangling indices API to find the UUID.

Query parameters

accept_data_loss boolean Required

This parameter must be set to true to acknowledge that it will no longer be possible to recove data from the dangling index.
master_timeout string

Specify timeout for connection to master
timeout string

Explicit operation timeout

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_dangling/{index_uuid}

curl \
 --request DELETE 'http://api.example.com/_dangling/{index_uuid}?accept_data_loss=true' \
 --header "Authorization: $API_KEY"

Add an index block Added in 7.9.0

PUT /{index}/_block/{block}

Api key auth Basic auth Bearer auth

Add an index block to an index. Index blocks limit the operations allowed on an index by blocking specific operation types.

Path parameters

index string Required

A comma-separated list or wildcard expression of index names used to limit the request. By default, you must explicitly name the indices you are adding blocks to. To allow the adding of blocks to indices with _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. You can update this setting in the elasticsearch.yml file or by using the cluster update settings API.
block string Required
The block type to add to the index.

Supported values include:
- metadata: Disable metadata changes, such as closing the index.
- read: Disable read operations.
- read_only: Disable write operations and metadata changes.
- write: Disable write operations. However, metadata changes are still allowed.
Values are metadata, read, read_only, or write.

Query parameters

allow_no_indices 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 string | array[string]
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 comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. It can also be set to -1 to indicate that the request should never timeout.
timeout string

The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. It can also be set to -1 to indicate that the request should never timeout.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- shards_acknowledged boolean Required
- indices array[object] Required
  
  Hide indices attributes Show indices attributes object
  
  name string Required
  
  blocked boolean Required

PUT /{index}/_block/{block}

curl \
 --request PUT 'http://api.example.com/{index}/_block/{block}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `PUT /my-index-000001/_block/write`, which adds an index block to an index.'

{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "indices" : [ {
    "name" : "my-index-000001",
    "blocked" : true
  } ]
}

Delete an alias

DELETE /{index}/_alias/{name}

Api key auth Basic auth Bearer auth

Removes a data stream or index from an alias.

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*).
name string | array[string] Required

Comma-separated list of aliases to remove. Supports wildcards (*). To remove all aliases, use * or _all.

Query parameters

master_timeout string

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 string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /{index}/_alias/{name}

curl \
 --request DELETE 'http://api.example.com/{index}/_alias/{name}' \
 --header "Authorization: $API_KEY"

Get field usage stats Technical preview

GET /{index}/_field_usage_stats

Api key auth Basic auth Bearer auth

Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.

The response body reports the per-shard usage count of the data structures that back the fields in the index. A given request will increment each count by a maximum value of 1, even if the request accesses the same field multiple times.

Path parameters

index string | array[string] Required

Comma-separated list or wildcard expression of index names used to limit the request.

Query parameters

allow_no_indices 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 string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
fields string | array[string]

Comma-separated list or wildcard expressions of fields to include in the statistics.

Responses

200 application/json
Hide response attribute Show response attribute object
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

GET /{index}/_field_usage_stats

curl \
 --request GET 'http://api.example.com/{index}/_field_usage_stats' \
 --header "Authorization: $API_KEY"

Response examples (200)

An abbreviated response from `GET /my-index-000001/_field_usage_stats`. The `all_fields` object reports the sums of the usage counts for all fields in the index (on the listed shard).

{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "my-index-000001": {
    "shards": [
      {
        "tracking_id": "MpOl0QlTQ4SYYhEe6KgJoQ",
        "tracking_started_at_millis": 1625558985010,
        "routing": {
          "state": "STARTED",
          "primary": true,
          "node": "gA6KeeVzQkGURFCUyV-e8Q",
          "relocating_node": null
        },
        "stats": {
          "all_fields": {
            "any": "6",
            "inverted_index": {
              "terms": 1,
              "postings": 1,
              "proximity": 1,
              "positions": 0,
              "term_frequencies": 1,
              "offsets": 0,
              "payloads": 0
            },
            "stored_fields": 2,
            "doc_values": 1,
            "points": 0,
            "norms": 1,
            "term_vectors": 0,
            "knn_vectors": 0
          },
          "fields": {
            "_id": {
              "any": 1,
              "inverted_index": {
                "terms": 1,
                "postings": 1,
                "proximity": 1,
                "positions": 0,
                "term_frequencies": 1,
                "offsets": 0,
                "payloads": 0
              },
              "stored_fields": 1,
              "doc_values": 0,
              "points": 0,
              "norms": 0,
              "term_vectors": 0,
              "knn_vectors": 0
            },
            "_source": {},
            "context": {},
            "message.keyword": {}
          }
        }
      }
    ]
  }
}

Get index settings

GET /{index}/_settings

Api key auth Basic auth Bearer auth

Get setting information for one or more indices. For data streams, it returns setting information for the stream's backing indices.

Path parameters

index string | array[string] Required

Comma-separated 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.

Query parameters

allow_no_indices 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 string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
flat_settings boolean

If true, returns settings in flat format.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
include_defaults boolean

If true, return all default settings in the response.
local boolean

If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.
master_timeout string

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.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object
  
  Hide * attributes Show * attributes object
  
  aliases object
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  search_routing string
  
  mappings object
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
  
  settings object
  
  Hide settings attributes Show settings attributes object
  
  index object
  
  mode string
  
  routing_path string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  soft_deletes object
  
  Hide soft_deletes attributes Show soft_deletes attributes object
  
  enabled boolean
  
  Indicates whether soft deletes are enabled on the index.
  
  retention_lease object
  
  Hide retention_lease attribute Show retention_lease attribute object
  
  period string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  sort object
  
  Hide sort attributes Show sort attributes object
  
  field string | array[string]
  
  order string | array[string]
  
  Supported values include: asc (or ASC), desc (or DESC)
  
  One of:
  SegmentSortOrder string array-2 array[string]
  
  Values are asc, ASC, desc, or DESC.
  
  mode string | array[string]
  
  Supported values include: min (or MIN), max (or MAX)
  
  One of:
  SegmentSortMode string array-2 array[string]
  
  Values are min, MIN, max, or MAX.
  
  missing string | array[string]
  
  Supported values include: _last, _first
  
  One of:
  SegmentSortMissing string array-2 array[string]
  
  Values are _last or _first.
  
  number_of_shards number | string
  
  One of:
  number-1 number string-2 string
  
  number_of_replicas number | string
  
  One of:
  number-1 number string-2 string
  
  number_of_routing_shards number
  
  check_on_startup string
  
  Values are true, false, or checksum.
  
  codec string
  
  routing_partition_size number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  load_fixed_bitset_filters_eagerly boolean
  
  hidden boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  auto_expand_replicas string | null
  
  One of:
  string-1 string NullValue string | null
  
  merge object
  
  Hide merge attribute Show merge attribute object
  
  scheduler object
  
  Hide scheduler attributes Show scheduler attributes object
  
  max_thread_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  max_merge_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  search object
  
  Hide search attributes Show search attributes object
  
  idle object
  
  Hide idle attribute Show idle attribute object
  
  after string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  slowlog object
  
  Hide slowlog attributes Show slowlog attributes object
  
  level string
  
  source number
  
  reformat boolean
  
  threshold object
  
  Hide threshold attributes Show threshold attributes object
  
  query object
  
  fetch object
  
  refresh_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_result_window number
  
  max_inner_result_window number
  
  max_rescore_window number
  
  max_docvalue_fields_search number
  
  max_script_fields number
  
  max_ngram_diff number
  
  max_shingle_diff number
  
  blocks object
  
  Hide blocks attributes Show blocks attributes object
  
  read_only boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  read_only_allow_delete boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  read boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  write boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  metadata boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  max_refresh_listeners number
  
  analyze object
  
  Hide analyze attribute Show analyze attribute object
  
  max_token_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  max_analyzed_offset number
  
  max_terms_count number
  
  max_regex_length number
  
  routing object
  
  Hide routing attributes Show routing attributes object
  
  allocation object
  
  Hide allocation attributes Show allocation attributes object
  
  enable string
  
  Values are all, primaries, new_primaries, or none.
  
  include object
  
  Hide include attributes Show include attributes object
  
  _tier_preference string
  
  _id string
  
  initial_recovery object
  
  Hide initial_recovery attribute Show initial_recovery attribute object
  
  _id string
  
  disk object
  
  Hide disk attribute Show disk attribute object
  
  threshold_enabled
  
  rebalance object
  
  Hide rebalance attribute Show rebalance attribute object
  
  enable string Required
  
  Values are all, primaries, replicas, or none.
  
  gc_deletes string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  default_pipeline string
  
  final_pipeline string
  
  lifecycle object
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  name string
  
  indexing_complete boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  origination_date number
  
  If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds.
  
  parse_origination_date boolean
  
  Set to true to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern ^{.*-{date_format}-\d+,} where the date_format is yyyy.MM.dd and the trailing digits are optional. An index that was rolled over would normally match the full format, for example logs-2016.10.31-000002). If the index name doesn’t match the pattern, index creation fails.
  
  step object
  
  Hide step attribute Show step attribute object
  
  wait_time_threshold string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  rollover_alias string
  
  The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see Rollover.
  
  prefer_ilm boolean | string
  
  Preference for the system that manages a data stream backing index (preferring ILM when both ILM and DLM are applicable for an index).
  
  One of:
  boolean-1 boolean string-2 string
  
  provided_name string
  
  creation_date number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  UnitMillis number StringifiedEpochTimeUnitMillis string
  
  Time unit for milliseconds
  
  creation_date_string string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  uuid string
  
  version object
  
  Hide version attributes Show version attributes object
  
  created string
  
  created_string string
  
  verified_before_close boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  format string | number
  
  One of:
  string-1 string number-2 number
  
  max_slices_per_scroll number
  
  translog object
  
  Hide translog attributes Show translog attributes object
  
  sync_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  durability string
  
  Values are request, REQUEST, async, or ASYNC.
  
  flush_threshold_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  retention object
  
  Hide retention attributes Show retention attributes object
  
  size number | string
  
  One of:
  ByteSize number ByteSize string
  
  age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  query_string object
  
  Hide query_string attribute Show query_string attribute object
  
  lenient boolean | string Required
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  priority number | string
  
  One of:
  number-1 number string-2 string
  
  top_metrics_max_size number
  
  analysis object
  
  Hide analysis attributes Show analysis attributes object
  
  analyzer object
  
  char_filter object
  
  filter object
  
  normalizer object
  
  tokenizer object
  
  settings object
  
  time_series object
  
  Hide time_series attributes Show time_series attributes object
  
  end_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  start_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  queries object
  
  Hide queries attribute Show queries attribute object
  
  cache object
  
  Hide cache attribute Show cache attribute object
  
  enabled boolean Required
  
  similarity object
  
  Configure custom similarity settings to customize how search results are scored.
  
  mapping object
  
  Hide mapping attributes Show mapping attributes object
  
  coerce boolean
  
  total_fields object
  
  Hide total_fields attributes Show total_fields attributes object
  
  limit number | string
  
  The maximum number of fields in an index. Field and object mappings, as well as field aliases count towards this limit. The limit is in place to prevent mappings and searches from becoming too large. Higher values can lead to performance degradations and memory issues, especially in clusters with a high load or few resources.
  
  One of:
  number-1 number string-2 string
  
  ignore_dynamic_beyond_limit boolean | string
  
  This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Limit of total fields [X] has been exceeded. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field.
  
  One of:
  boolean-1 boolean string-2 string
  
  depth object
  
  Hide depth attribute Show depth attribute object
  
  limit number
  
  The maximum depth for a field, which is measured as the number of inner objects. For instance, if all fields are defined at the root object level, then the depth is 1. If there is one object mapping, then the depth is 2, etc.
  
  nested_fields object
  
  Hide nested_fields attribute Show nested_fields attribute object
  
  limit number
  
  The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index.
  
  nested_objects object
  
  Hide nested_objects attribute Show nested_objects attribute object
  
  limit number
  
  The maximum number of nested JSON objects that a single document can contain across all nested types. This limit helps to prevent out of memory errors when a document contains too many nested objects.
  
  field_name_length object
  
  Hide field_name_length attribute Show field_name_length attribute object
  
  limit number
  
  Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is Long.MAX_VALUE (no limit).
  
  dimension_fields object
  
  Hide dimension_fields attribute Show dimension_fields attribute object
  
  limit number
  
  [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
  
  source object
  
  Hide source attribute Show source attribute object
  
  mode string Required
  
  Values are disabled, stored, or synthetic.
  
  ignore_malformed boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  indexing.slowlog object
  
  Hide indexing.slowlog attributes Show indexing.slowlog attributes object
  
  level string
  
  source number
  
  reformat boolean
  
  threshold object
  
  Hide threshold attribute Show threshold attribute object
  
  index object
  
  Hide index attributes Show index attributes object
  
  warn string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  info string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  debug string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  trace string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  indexing_pressure object
  
  Hide indexing_pressure attribute Show indexing_pressure attribute object
  
  memory object Required
  
  Hide memory attribute Show memory attribute object
  
  limit number
  
  Number of outstanding bytes that may be consumed by indexing requests. When this limit is reached or exceeded, the node will reject new coordinating and primary operations. When replica operations consume 1.5x this limit, the node will reject new replica operations. Defaults to 10% of the heap.
  
  store object
  
  Hide store attributes Show store attributes object
  
  type string Required
  
  Any of:
  StorageType string StorageType string
  
  Values are fs, niofs, mmapfs, or hybridfs.
  
  allow_mmap boolean
  
  You can restrict the use of the mmapfs and the related hybridfs store type via the setting node.store.allow_mmap. This is a boolean setting indicating whether or not memory-mapping is allowed. The default is to allow it. This setting is useful, for example, if you are in an environment where you can not control the ability to create a lot of memory maps so you need disable the ability to use memory-mapping.
  
  defaults object
  
  Hide defaults attributes Show defaults attributes object
  
  index object
  
  mode string
  
  routing_path string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  soft_deletes object
  
  Hide soft_deletes attributes Show soft_deletes attributes object
  
  enabled boolean
  
  Indicates whether soft deletes are enabled on the index.
  
  retention_lease object
  
  Hide retention_lease attribute Show retention_lease attribute object
  
  period string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  sort object
  
  Hide sort attributes Show sort attributes object
  
  field string | array[string]
  
  order string | array[string]
  
  Supported values include: asc (or ASC), desc (or DESC)
  
  One of:
  SegmentSortOrder string array-2 array[string]
  
  Values are asc, ASC, desc, or DESC.
  
  mode string | array[string]
  
  Supported values include: min (or MIN), max (or MAX)
  
  One of:
  SegmentSortMode string array-2 array[string]
  
  Values are min, MIN, max, or MAX.
  
  missing string | array[string]
  
  Supported values include: _last, _first
  
  One of:
  SegmentSortMissing string array-2 array[string]
  
  Values are _last or _first.
  
  number_of_shards number | string
  
  One of:
  number-1 number string-2 string
  
  number_of_replicas number | string
  
  One of:
  number-1 number string-2 string
  
  number_of_routing_shards number
  
  check_on_startup string
  
  Values are true, false, or checksum.
  
  codec string
  
  routing_partition_size number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  load_fixed_bitset_filters_eagerly boolean
  
  hidden boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  auto_expand_replicas string | null
  
  One of:
  string-1 string NullValue string | null
  
  merge object
  
  Hide merge attribute Show merge attribute object
  
  scheduler object
  
  Hide scheduler attributes Show scheduler attributes object
  
  max_thread_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  max_merge_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  search object
  
  Hide search attributes Show search attributes object
  
  idle object
  
  Hide idle attribute Show idle attribute object
  
  after string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  slowlog object
  
  Hide slowlog attributes Show slowlog attributes object
  
  level string
  
  source number
  
  reformat boolean
  
  threshold object
  
  Hide threshold attributes Show threshold attributes object
  
  query object
  
  fetch object
  
  refresh_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_result_window number
  
  max_inner_result_window number
  
  max_rescore_window number
  
  max_docvalue_fields_search number
  
  max_script_fields number
  
  max_ngram_diff number
  
  max_shingle_diff number
  
  blocks object
  
  Hide blocks attributes Show blocks attributes object
  
  read_only boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  read_only_allow_delete boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  read boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  write boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  metadata boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  max_refresh_listeners number
  
  analyze object
  
  Hide analyze attribute Show analyze attribute object
  
  max_token_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  max_analyzed_offset number
  
  max_terms_count number
  
  max_regex_length number
  
  routing object
  
  Hide routing attributes Show routing attributes object
  
  allocation object
  
  Hide allocation attributes Show allocation attributes object
  
  enable string
  
  Values are all, primaries, new_primaries, or none.
  
  include object
  
  Hide include attributes Show include attributes object
  
  _tier_preference string
  
  _id string
  
  initial_recovery object
  
  Hide initial_recovery attribute Show initial_recovery attribute object
  
  _id string
  
  disk object
  
  Hide disk attribute Show disk attribute object
  
  threshold_enabled
  
  rebalance object
  
  Hide rebalance attribute Show rebalance attribute object
  
  enable string Required
  
  Values are all, primaries, replicas, or none.
  
  gc_deletes string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  default_pipeline string
  
  final_pipeline string
  
  lifecycle object
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  name string
  
  indexing_complete boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  origination_date number
  
  If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds.
  
  parse_origination_date boolean
  
  Set to true to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern ^{.*-{date_format}-\d+,} where the date_format is yyyy.MM.dd and the trailing digits are optional. An index that was rolled over would normally match the full format, for example logs-2016.10.31-000002). If the index name doesn’t match the pattern, index creation fails.
  
  step object
  
  Hide step attribute Show step attribute object
  
  wait_time_threshold string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  rollover_alias string
  
  The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see Rollover.
  
  prefer_ilm boolean | string
  
  Preference for the system that manages a data stream backing index (preferring ILM when both ILM and DLM are applicable for an index).
  
  One of:
  boolean-1 boolean string-2 string
  
  provided_name string
  
  creation_date number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  UnitMillis number StringifiedEpochTimeUnitMillis string
  
  Time unit for milliseconds
  
  creation_date_string string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  uuid string
  
  version object
  
  Hide version attributes Show version attributes object
  
  created string
  
  created_string string
  
  verified_before_close boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  format string | number
  
  One of:
  string-1 string number-2 number
  
  max_slices_per_scroll number
  
  translog object
  
  Hide translog attributes Show translog attributes object
  
  sync_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  durability string
  
  Values are request, REQUEST, async, or ASYNC.
  
  flush_threshold_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  retention object
  
  Hide retention attributes Show retention attributes object
  
  size number | string
  
  One of:
  ByteSize number ByteSize string
  
  age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  query_string object
  
  Hide query_string attribute Show query_string attribute object
  
  lenient boolean | string Required
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  priority number | string
  
  One of:
  number-1 number string-2 string
  
  top_metrics_max_size number
  
  analysis object
  
  Hide analysis attributes Show analysis attributes object
  
  analyzer object
  
  char_filter object
  
  filter object
  
  normalizer object
  
  tokenizer object
  
  settings object
  
  time_series object
  
  Hide time_series attributes Show time_series attributes object
  
  end_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  start_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  queries object
  
  Hide queries attribute Show queries attribute object
  
  cache object
  
  Hide cache attribute Show cache attribute object
  
  enabled boolean Required
  
  similarity object
  
  Configure custom similarity settings to customize how search results are scored.
  
  mapping object
  
  Hide mapping attributes Show mapping attributes object
  
  coerce boolean
  
  total_fields object
  
  Hide total_fields attributes Show total_fields attributes object
  
  limit number | string
  
  The maximum number of fields in an index. Field and object mappings, as well as field aliases count towards this limit. The limit is in place to prevent mappings and searches from becoming too large. Higher values can lead to performance degradations and memory issues, especially in clusters with a high load or few resources.
  
  One of:
  number-1 number string-2 string
  
  ignore_dynamic_beyond_limit boolean | string
  
  This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Limit of total fields [X] has been exceeded. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field.
  
  One of:
  boolean-1 boolean string-2 string
  
  depth object
  
  Hide depth attribute Show depth attribute object
  
  limit number
  
  The maximum depth for a field, which is measured as the number of inner objects. For instance, if all fields are defined at the root object level, then the depth is 1. If there is one object mapping, then the depth is 2, etc.
  
  nested_fields object
  
  Hide nested_fields attribute Show nested_fields attribute object
  
  limit number
  
  The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index.
  
  nested_objects object
  
  Hide nested_objects attribute Show nested_objects attribute object
  
  limit number
  
  The maximum number of nested JSON objects that a single document can contain across all nested types. This limit helps to prevent out of memory errors when a document contains too many nested objects.
  
  field_name_length object
  
  Hide field_name_length attribute Show field_name_length attribute object
  
  limit number
  
  Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is Long.MAX_VALUE (no limit).
  
  dimension_fields object
  
  Hide dimension_fields attribute Show dimension_fields attribute object
  
  limit number
  
  [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
  
  source object
  
  Hide source attribute Show source attribute object
  
  mode string Required
  
  Values are disabled, stored, or synthetic.
  
  ignore_malformed boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  indexing.slowlog object
  
  Hide indexing.slowlog attributes Show indexing.slowlog attributes object
  
  level string
  
  source number
  
  reformat boolean
  
  threshold object
  
  Hide threshold attribute Show threshold attribute object
  
  index object
  
  Hide index attributes Show index attributes object
  
  warn string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  info string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  debug string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  trace string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  indexing_pressure object
  
  Hide indexing_pressure attribute Show indexing_pressure attribute object
  
  memory object Required
  
  Hide memory attribute Show memory attribute object
  
  limit number
  
  Number of outstanding bytes that may be consumed by indexing requests. When this limit is reached or exceeded, the node will reject new coordinating and primary operations. When replica operations consume 1.5x this limit, the node will reject new replica operations. Defaults to 10% of the heap.
  
  store object
  
  Hide store attributes Show store attributes object
  
  type string Required
  
  Any of:
  StorageType string StorageType string
  
  Values are fs, niofs, mmapfs, or hybridfs.
  
  allow_mmap boolean
  
  You can restrict the use of the mmapfs and the related hybridfs store type via the setting node.store.allow_mmap. This is a boolean setting indicating whether or not memory-mapping is allowed. The default is to allow it. This setting is useful, for example, if you are in an environment where you can not control the ability to create a lot of memory maps so you need disable the ability to use memory-mapping.
  
  data_stream string
  
  lifecycle object
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  downsampling object
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  config object Required
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

GET /{index}/_settings

curl \
 --request GET 'http://api.example.com/{index}/_settings' \
 --header "Authorization: $API_KEY"

Refresh an index

GET /_refresh

Api key auth Basic auth Bearer auth

A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.

By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. You can change this default interval with the index.refresh_interval setting.

Refresh requests are synchronous and do not return a response until the refresh operation completes.

Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option. This option ensures the indexing operation waits for a periodic refresh before running the search.

Query parameters

allow_no_indices 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.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.

Responses

200 application/json
Hide response attribute Show response attribute object
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

GET /_refresh

curl \
 --request GET 'http://api.example.com/_refresh' \
 --header "Authorization: $API_KEY"

Refresh an index

POST /{index}/_refresh

Api key auth Basic auth Bearer auth

A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.

By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. You can change this default interval with the index.refresh_interval setting.

Refresh requests are synchronous and do not return a response until the refresh operation completes.

Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option. This option ensures the indexing operation waits for a periodic refresh before running the search.

Path parameters

index string | array[string] Required

Comma-separated 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.

Query parameters

allow_no_indices 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.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.

Responses

200 application/json
Hide response attribute Show response attribute object
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

POST /{index}/_refresh

curl \
 --request POST 'http://api.example.com/{index}/_refresh' \
 --header "Authorization: $API_KEY"

Resolve the cluster Added in 8.13.0

GET /_resolve/cluster/{name}

Api key auth Basic auth Bearer auth

Resolve the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. If no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.

This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.

You use the same index expression with this endpoint as you would for cross-cluster search. Index and cluster exclusions are also supported with this endpoint.

For each cluster in the index expression, information is returned about:

Whether the querying ("local") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the remote/info endpoint.
Whether each remote cluster is configured with skip_unavailable as true or false.
Whether there are any indices, aliases, or data streams on that cluster that match the index expression.
Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).
Cluster version information, including the Elasticsearch server version.

For example, GET /_resolve/cluster/my-index-*,cluster*:my-index-* returns information about the local cluster and all remotely configured clusters that start with the alias cluster*. Each cluster returns information about whether it has any indices, aliases or data streams that match my-index-*.

Note on backwards compatibility

The ability to query without an index expression was added in version 8.18, so when querying remote clusters older than that, the local cluster will send the index expression dummy* to those remote clusters. Thus, if an errors occur, you may see a reference to that index expression even though you didn't request it. If it causes a problem, you can instead include an index expression like *:* to bypass the issue.

Advantages of using this endpoint before a cross-cluster search

You may want to exclude a cluster or index from a search when:

A remote cluster is not currently connected and is configured with skip_unavailable=false. Running a cross-cluster search under those conditions will cause the entire search to fail.
A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is logs*,remote1:logs* and the remote1 cluster has no indices, aliases or data streams that match logs*. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.
The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the _resolve/cluster response will be present. (This is also where security/permission errors will be shown.)
A remote cluster is an older version that does not support the feature you want to use in your search.

Test availability of remote clusters

The remote/info endpoint is commonly used to test whether the "local" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not. The remote cluster may be available, while the local cluster is not currently connected to it.

You can use the _resolve/cluster API to attempt to reconnect to remote clusters. For example with GET _resolve/cluster or GET _resolve/cluster/*:*. The connected field in the response will indicate whether it was successful. If a connection was (re-)established, this will also cause the remote/info endpoint to now indicate a connected status.

Path parameters

name string | array[string] Required

A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve. Resources on remote clusters can be specified using the <cluster>:<name> syntax. Index and cluster exclusions (e.g., -cluster1:*) are also supported. If no index expression is specified, information about all remote clusters configured on the local cluster is returned without doing any index matching

Query parameters

allow_no_indices 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. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_throttled boolean Deprecated

If true, concrete, expanded, or aliased indices are ignored when frozen. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
timeout string

The maximum time to wait for remote clusters to respond. If a remote cluster does not respond within this timeout period, the API response will show the cluster as not connected and include an error message that the request timed out.

The default timeout is unset and the query can take as long as the networking layer is configured to wait for remote clusters that are not responding (typically 30 seconds).

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attributes Show * attributes object
  
  connected boolean Required
  
  Whether the remote cluster is connected to the local (querying) cluster.
  
  skip_unavailable boolean Required
  
  The skip_unavailable setting for a remote cluster.
  
  matching_indices boolean
  
  Whether the index expression provided in the request matches any indices, aliases or data streams on the cluster.
  
  error string
  
  Provides error messages that are likely to occur if you do a search with this index expression on the specified cluster (for example, lack of security privileges to query an index).
  
  version object
  
  Hide version attributes Show version attributes object
  
  build_flavor string Required
  
  minimum_index_compatibility_version string Required
  
  minimum_wire_compatibility_version string Required
  
  number string Required

GET /_resolve/cluster/{name}

curl \
 --request GET 'http://api.example.com/_resolve/cluster/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_resolve/cluster/my-index*,clust*:my-index*`. Each cluster has its own response section. The cluster you sent the request to is labelled as "(local)".

{
  "(local)": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_one": {
    "connected": true,
    "skip_unavailable": true,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_two": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  }
}

A successful response from `GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false&timeout=5s`. This type of request can be used to identify potential problems with your cross-cluster search. Note also that a `timeout` of 5 seconds is sent, which sets the maximum time the query will wait for remote clusters to respond. The local cluster has no index called `not_present`. Searching with `ignore_unavailable=false` would return a "no such index" error. The `cluster_one` remote cluster has no indices that match the pattern `my-index*`. There may be no indices that match the pattern or the index could be closed. The `cluster_two` remote cluster is not connected (the attempt to connect failed). Since this cluster is marked as `skip_unavailable=false`, you should probably exclude this cluster from the search by adding `-cluster_two:*` to the search index expression. For `cluster_three`, the error message indicates that this remote cluster did not respond within the 5-second timeout window specified, so it is also marked as not connected. The `oldcluster` remote cluster shows that it has matching indices, but no version information is included. This indicates that the cluster version predates the introduction of the `_resolve/cluster` API, so you may want to exclude it from your cross-cluster search.

{
  "(local)": {
    "connected": true,
    "skip_unavailable": false,
    "error": "no such index [not_present]"
  },
  "cluster_one": {
    "connected": true,
    "skip_unavailable": true,
    "matching_indices": false,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_two": {
    "connected": false,
    "skip_unavailable": false
  },
  "cluster_three": {
    "connected": false,
    "skip_unavailable": false,
    "error": "Request timed out before receiving a response from the remote cluster"
  },
  "oldcluster": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true
  }
}

Validate a query Added in 1.3.0

POST /_validate/query

Api key auth Basic auth Bearer auth

Validates a query without running it.

Query parameters

allow_no_indices 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.
all_shards boolean

If true, the validation is executed on all shards instead of one random shard per index.
analyzer string

Analyzer to use for the query string. This parameter can only be used when the q query string parameter is specified.
analyze_wildcard boolean

If true, wildcard and prefix queries are analyzed.
default_operator string

The default operator for query string query: AND or OR.

Values are and, AND, or, or OR.
df 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 string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
explain boolean

If true, the response returns detailed information if an error has occurred.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
lenient boolean

If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
rewrite boolean

If true, returns a more detailed explanation showing the actual Lucene query that will be executed.
q string

Query in the Lucene query string syntax.

application/json

Body

query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- explanations array[object]
  
  Hide explanations attributes Show explanations attributes object
  
  error string
  
  explanation string
  
  index string Required
  
  valid boolean Required
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- valid boolean Required
- error string

POST /_validate/query

curl \
 --request POST 'http://api.example.com/_validate/query' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":{}}'

Get lifecycle policies Added in 6.6.0

GET /_ilm/policy/{policy}

Api key auth Basic auth Bearer auth

Path parameters

policy string Required

Identifier for the policy.

Query parameters

master_timeout string

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 string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attributes Show * attributes object
  
  modified_date string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  policy object Required
  
  Hide policy attributes Show policy attributes object
  
  phases object Required
  
  Hide phases attributes Show phases attributes object
  
  cold object
  
  Hide cold attributes Show cold attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  delete object
  
  downsample object
  
  freeze object
  
  forcemerge object
  
  migrate object
  
  readonly object
  
  rollover object
  
  set_priority object
  
  searchable_snapshot object
  
  shrink object
  
  unfollow object
  
  wait_for_snapshot object
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  delete object
  
  Hide delete attributes Show delete attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  delete object
  
  downsample object
  
  freeze object
  
  forcemerge object
  
  migrate object
  
  readonly object
  
  rollover object
  
  set_priority object
  
  searchable_snapshot object
  
  shrink object
  
  unfollow object
  
  wait_for_snapshot object
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  frozen object
  
  Hide frozen attributes Show frozen attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  delete object
  
  downsample object
  
  freeze object
  
  forcemerge object
  
  migrate object
  
  readonly object
  
  rollover object
  
  set_priority object
  
  searchable_snapshot object
  
  shrink object
  
  unfollow object
  
  wait_for_snapshot object
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  hot object
  
  Hide hot attributes Show hot attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  delete object
  
  downsample object
  
  freeze object
  
  forcemerge object
  
  migrate object
  
  readonly object
  
  rollover object
  
  set_priority object
  
  searchable_snapshot object
  
  shrink object
  
  unfollow object
  
  wait_for_snapshot object
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  warm object
  
  Hide warm attributes Show warm attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  delete object
  
  downsample object
  
  freeze object
  
  forcemerge object
  
  migrate object
  
  readonly object
  
  rollover object
  
  set_priority object
  
  searchable_snapshot object
  
  shrink object
  
  unfollow object
  
  wait_for_snapshot object
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  version number Required

GET /_ilm/policy/{policy}

curl \
 --request GET 'http://api.example.com/_ilm/policy/{policy}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response when retrieving a lifecycle policy.

{
  "my_policy": {
    "version": 1,
    "modified_date": 82392349,
    "policy": {
      "phases": {
        "warm": {
          "min_age": "10d",
          "actions": {
            "forcemerge": {
              "max_num_segments": 1
            }
          }
        },
        "delete": {
          "min_age": "30d",
          "actions": {
            "delete": {
              "delete_searchable_snapshot": true
            }
          }
        }
      }
    },
    "in_use_by" : {
      "indices" : [],
      "data_streams" : [],
      "composable_templates" : []
    }
  }
}

Create or update a lifecycle policy Added in 6.6.0

PUT /_ilm/policy/{policy}

Api key auth Basic auth Bearer auth

If the specified policy exists, it is replaced and the policy version is incremented.

NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

External documentation

Path parameters

policy string Required

Identifier for the policy.

Query parameters

master_timeout string

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 string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

application/json

Body

policy object
Hide policy attributes Show policy attributes object
- phases object Required
  Hide phases attributes Show phases attributes object
  
  cold object
  
  Hide cold attributes Show cold attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  delete object
  
  Hide delete attributes Show delete attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  frozen object
  
  Hide frozen attributes Show frozen attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  hot object
  
  Hide hot attributes Show hot attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  warm object
  
  Hide warm attributes Show warm attributes object
  
  actions object
  
  Hide actions attributes Show actions attributes object
  
  allocate object
  
  Hide allocate attributes Show allocate attributes object
  
  number_of_replicas number
  
  total_shards_per_node number
  
  include object
  
  Hide include attribute Show include attribute object
  
  * string Additional properties
  
  exclude object
  
  Hide exclude attribute Show exclude attribute object
  
  * string Additional properties
  
  require object
  
  Hide require attribute Show require attribute object
  
  * string Additional properties
  
  delete object
  
  Hide delete attribute Show delete attribute object
  
  delete_searchable_snapshot boolean
  
  downsample object
  
  Hide downsample attributes Show downsample attributes object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  wait_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  freeze object
  
  forcemerge object
  
  Hide forcemerge attributes Show forcemerge attributes object
  
  max_num_segments number Required
  
  index_codec string
  
  migrate object
  
  Hide migrate attribute Show migrate attribute object
  
  enabled boolean
  
  readonly object
  
  rollover object
  
  Hide rollover attributes Show rollover attributes object
  
  max_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  max_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_docs number
  
  max_primary_shard_docs number
  
  min_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  min_docs number
  
  min_primary_shard_docs number
  
  set_priority object
  
  Hide set_priority attribute Show set_priority attribute object
  
  priority number
  
  searchable_snapshot object
  
  Hide searchable_snapshot attributes Show searchable_snapshot attributes object
  
  snapshot_repository string Required
  
  force_merge_index boolean
  
  shrink object
  
  Hide shrink attributes Show shrink attributes object
  
  number_of_shards number
  
  max_primary_shard_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  allow_write_after_shrink boolean
  
  unfollow object
  
  wait_for_snapshot object
  
  Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
  
  policy string Required
  
  min_age string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- _meta object
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_ilm/policy/{policy}

curl \
 --request PUT 'http://api.example.com/_ilm/policy/{policy}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"policy\": {\n    \"_meta\": {\n      \"description\": \"used for nginx log\",\n      \"project\": {\n        \"name\": \"myProject\",\n        \"department\": \"myDepartment\"\n      }\n    },\n    \"phases\": {\n      \"warm\": {\n        \"min_age\": \"10d\",\n        \"actions\": {\n          \"forcemerge\": {\n            \"max_num_segments\": 1\n          }\n        }\n      },\n      \"delete\": {\n        \"min_age\": \"30d\",\n        \"actions\": {\n          \"delete\": {}\n        }\n      }\n    }\n  }\n}"'

Request example

Run `PUT _ilm/policy/my_policy` to create a new policy with arbitrary metadata.

{
  "policy": {
    "_meta": {
      "description": "used for nginx log",
      "project": {
        "name": "myProject",
        "department": "myDepartment"
      }
    },
    "phases": {
      "warm": {
        "min_age": "10d",
        "actions": {
          "forcemerge": {
            "max_num_segments": 1
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

Response examples (200)

A successful response when creating a new lifecycle policy.

{
  "acknowledged": true
}

Inference

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 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.

Perform inference on the service Added in 8.11.0

POST /_inference/{inference_id}

Api key auth Basic auth Bearer auth

This API enables you to use machine learning models to perform specific tasks on data that you provide as an input. It returns a response with the results of the tasks. The inference endpoint you use can perform one specific task that has been defined when the endpoint was created with the create inference API.

For details about using this API with a service, such as Amazon Bedrock, Anthropic, or HuggingFace, refer to the service-specific documentation.

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.

Path parameters

inference_id string Required

The unique identifier for the inference endpoint.

Query parameters

timeout string

The amount of time to wait for the inference request to complete.

application/json

Body

query string

The query input, which is required only for the rerank task. It is not required for other tasks.
input string | array[string] Required

The text on which you want to perform the inference task. It can be a single string or an array.

Inference endpoints for the completion task type currently only support a single string as input.

One of:
string-1 string array-2 array[string]
task_settings object

Responses

200 application/json
Hide response attributes Show response attributes object
- text_embedding_bytes array[object]
  
  Hide text_embedding_bytes attribute Show text_embedding_bytes attribute object
  
  embedding array[number] Required
  
  Text Embedding results containing bytes are represented as Dense Vectors of bytes.
- text_embedding_bits array[object]
  
  Hide text_embedding_bits attribute Show text_embedding_bits attribute object
  
  embedding array[number] Required
  
  Text Embedding results containing bytes are represented as Dense Vectors of bytes.
- text_embedding array[object]
  
  Hide text_embedding attribute Show text_embedding attribute object
  
  embedding array[number] Required
  
  Text Embedding results are represented as Dense Vectors of floats.
- sparse_embedding array[object]
  
  Hide sparse_embedding attribute Show sparse_embedding attribute object
  
  embedding object Required
  
  Sparse Embedding tokens are represented as a dictionary of string to double.
  
  Hide embedding attribute Show embedding attribute object
  
  * number Additional properties
- completion array[object]
  
  Hide completion attribute Show completion attribute object
  
  result string Required
- rerank array[object]
  
  Hide rerank attributes Show rerank attributes object
  
  index number Required
  
  relevance_score number Required
  
  text string

POST /_inference/{inference_id}

curl \
 --request POST 'http://api.example.com/_inference/{inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":"string","input":"string","task_settings":{}}'

Delete GeoIP database configurations Added in 8.15.0

DELETE /_ingest/geoip/database/{id}

Api key auth Basic auth Bearer auth

Delete one or more IP geolocation database configurations.

Path parameters

id string | array[string] Required

A comma-separated list of geoip database configurations to delete

Query parameters

master_timeout string

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 string

The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_ingest/geoip/database/{id}

curl \
 --request DELETE 'http://api.example.com/_ingest/geoip/database/{id}' \
 --header "Authorization: $API_KEY"

Get GeoIP statistics Added in 7.13.0

GET /_ingest/geoip/stats

Api key auth Basic auth Bearer auth

Get download statistics for GeoIP2 databases that are used with the GeoIP processor.

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- stats object Required
  
  Hide stats attributes Show stats attributes object
  
  successful_downloads number Required
  
  Total number of successful database downloads.
  
  failed_downloads number Required
  
  Total number of failed database downloads.
  
  total_download_time number
  
  Time unit for milliseconds
  
  databases_count number Required
  
  Current number of databases available for use.
  
  skipped_updates number Required
  
  Total number of database updates skipped.
  
  expired_databases number Required
  
  Total number of databases not updated after 30 days
- nodes object Required
  
  Downloaded GeoIP2 databases for each node.
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  databases array[object] Required
  
  Downloaded databases for the node.
  
  Hide databases attribute Show databases attribute object
  
  name string Required
  
  files_in_temp array[string] Required
  
  Downloaded database files, including related license files. Elasticsearch stores these files in the node’s temporary directory: $ES_TMPDIR/geoip-databases/.

GET /_ingest/geoip/stats

curl \
 --request GET 'http://api.example.com/_ingest/geoip/stats' \
 --header "Authorization: $API_KEY"

Get calendar configuration info Added in 6.2.0

POST /_ml/calendars/{calendar_id}

Api key auth Basic auth Bearer auth

Path parameters

calendar_id string Required

A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using _all or * or by omitting the calendar identifier.

Query parameters

from number

Skips the specified number of calendars. This parameter is supported only when you omit the calendar identifier.
size number

Specifies the maximum number of calendars to obtain. This parameter is supported only when you omit the calendar identifier.

application/json

Body

page object
Hide page attributes Show page attributes object
- from number
  
  Skips the specified number of items.
- size number
  
  Specifies the maximum number of items to obtain.

Responses

200 application/json
Hide response attributes Show response attributes object
- calendars array[object] Required
  
  Hide calendars attributes Show calendars attributes object
  
  calendar_id string Required
  
  description string
  
  A description of the calendar.
  
  job_ids array[string] Required
  
  An array of anomaly detection job identifiers.
- count number Required

POST /_ml/calendars/{calendar_id}

curl \
 --request POST 'http://api.example.com/_ml/calendars/{calendar_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"page":{"from":42.0,"size":42.0}}'

Get model snapshots info Added in 5.4.0

GET /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}

Api key auth Basic auth Bearer auth

Path parameters

job_id string Required

Identifier for the anomaly detection job.
snapshot_id string Required

A numerical character string that uniquely identifies the model snapshot. You can get information for multiple snapshots by using a comma-separated list or a wildcard expression. You can get all snapshots by using _all, by specifying * as the snapshot ID, or by omitting the snapshot ID.

Query parameters

desc boolean

If true, the results are sorted in descending order.
end string | number

Returns snapshots with timestamps earlier than this time.
from number

Skips the specified number of snapshots.
size number

Specifies the maximum number of snapshots to obtain.
sort string

Specifies the sort field for the requested snapshots. By default, the snapshots are sorted by their timestamp.
start string | number

Returns snapshots with timestamps after this time.

application/json

Body

desc boolean

Refer to the description for the desc query parameter.
end string | number

A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

One of:
DateTime string UnitMillis number
page object
Hide page attributes Show page attributes object
- from number
  
  Skips the specified number of items.
- size number
  
  Specifies the maximum number of items to obtain.
sort string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
start string | number

A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.

One of:
DateTime string UnitMillis number

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- model_snapshots array[object] Required
  
  Hide model_snapshots attributes Show model_snapshots attributes object
  
  description string
  
  An optional description of the job.
  
  job_id string Required
  
  latest_record_time_stamp number
  
  The timestamp of the latest processed record.
  
  latest_result_time_stamp number
  
  The timestamp of the latest bucket result.
  
  min_version string Required
  
  model_size_stats object
  
  Hide model_size_stats attributes Show model_size_stats attributes object
  
  bucket_allocation_failures_count number Required
  
  job_id string Required
  
  log_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  memory_status string Required
  
  Values are ok, soft_limit, or hard_limit.
  
  model_bytes number | string Required
  
  One of:
  ByteSize number ByteSize string
  
  model_bytes_exceeded number | string
  
  One of:
  ByteSize number ByteSize string
  
  model_bytes_memory_limit number | string
  
  One of:
  ByteSize number ByteSize string
  
  output_memory_allocator_bytes number | string
  
  One of:
  ByteSize number ByteSize string
  
  peak_model_bytes number | string
  
  One of:
  ByteSize number ByteSize string
  
  assignment_memory_basis string
  
  result_type string Required
  
  total_by_field_count number Required
  
  total_over_field_count number Required
  
  total_partition_field_count number Required
  
  categorization_status string Required
  
  Values are ok or warn.
  
  categorized_doc_count number Required
  
  dead_category_count number Required
  
  failed_category_count number Required
  
  frequent_category_count number Required
  
  rare_category_count number Required
  
  total_category_count number Required
  
  timestamp number
  
  retain boolean Required
  
  If true, this snapshot will not be deleted during automatic cleanup of snapshots older than model_snapshot_retention_days. However, this snapshot will be deleted when the job is deleted. The default value is false.
  
  snapshot_doc_count number Required
  
  For internal use only.
  
  snapshot_id string Required
  
  timestamp number Required
  
  The creation timestamp for the snapshot.

GET /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}

curl \
 --request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"desc":true,"":"string","page":{"from":42.0,"size":42.0},"sort":"string"}'

Get anomaly detection job stats Added in 5.5.0

GET /_ml/anomaly_detectors/{job_id}/_stats

Api key auth Basic auth Bearer auth

Path parameters

job_id string Required

Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs, or a wildcard expression. If you do not specify one of these options, the API returns information for all anomaly detection jobs.

Query parameters

allow_no_match 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.
If true, the API returns an empty jobs array when there are no matches and the subset of results when there are partial matches. If false, the API returns a 404 status code when there are no matches or only partial matches.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- jobs array[object] Required
  
  Hide jobs attributes Show jobs attributes object
  
  assignment_explanation string
  
  For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.
  
  data_counts object Required
  
  Hide data_counts attributes Show data_counts attributes object
  
  bucket_count number Required
  
  earliest_record_timestamp number
  
  empty_bucket_count number Required
  
  input_bytes number Required
  
  input_field_count number Required
  
  input_record_count number Required
  
  invalid_date_count number Required
  
  job_id string Required
  
  last_data_time number
  
  latest_empty_bucket_timestamp number
  
  latest_record_timestamp number
  
  latest_sparse_bucket_timestamp number
  
  latest_bucket_timestamp number
  
  log_time number
  
  missing_field_count number Required
  
  out_of_order_timestamp_count number Required
  
  processed_field_count number Required
  
  processed_record_count number Required
  
  sparse_bucket_count number Required
  
  forecasts_stats object Required
  
  Hide forecasts_stats attributes Show forecasts_stats attributes object
  
  memory_bytes object
  
  Hide memory_bytes attributes Show memory_bytes attributes object
  
  avg number Required
  
  max number Required
  
  min number Required
  
  total number Required
  
  processing_time_ms object
  
  Hide processing_time_ms attributes Show processing_time_ms attributes object
  
  avg number Required
  
  max number Required
  
  min number Required
  
  total number Required
  
  records object
  
  Hide records attributes Show records attributes object
  
  avg number Required
  
  max number Required
  
  min number Required
  
  total number Required
  
  status object
  
  Hide status attribute Show status attribute object
  
  * number Additional properties
  
  total number Required
  
  forecasted_jobs number Required
  
  job_id string Required
  
  Identifier for the anomaly detection job.
  
  model_size_stats object Required
  
  Hide model_size_stats attributes Show model_size_stats attributes object
  
  bucket_allocation_failures_count number Required
  
  job_id string Required
  
  log_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  memory_status string Required
  
  Values are ok, soft_limit, or hard_limit.
  
  model_bytes number | string Required
  
  One of:
  ByteSize number ByteSize string
  
  model_bytes_exceeded number | string
  
  One of:
  ByteSize number ByteSize string
  
  model_bytes_memory_limit number | string
  
  One of:
  ByteSize number ByteSize string
  
  output_memory_allocator_bytes number | string
  
  One of:
  ByteSize number ByteSize string
  
  peak_model_bytes number | string
  
  One of:
  ByteSize number ByteSize string
  
  assignment_memory_basis string
  
  result_type string Required
  
  total_by_field_count number Required
  
  total_over_field_count number Required
  
  total_partition_field_count number Required
  
  categorization_status string Required
  
  Values are ok or warn.
  
  categorized_doc_count number Required
  
  dead_category_count number Required
  
  failed_category_count number Required
  
  frequent_category_count number Required
  
  rare_category_count number Required
  
  total_category_count number Required
  
  timestamp number
  
  node object
  
  Hide node attributes Show node attributes object
  
  name string Required
  
  ephemeral_id string Required
  
  id string Required
  
  transport_address string Required
  
  attributes object Required
  
  Hide attributes attribute Show attributes attribute object
  
  * string Additional properties
  
  open_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  state string Required
  
  Values are closing, closed, opened, failed, or opening.
  
  timing_stats object Required
  
  Hide timing_stats attributes Show timing_stats attributes object
  
  average_bucket_processing_time_ms number
  
  Time unit for fractional milliseconds
  
  bucket_count number Required
  
  exponential_average_bucket_processing_time_ms number
  
  Time unit for fractional milliseconds
  
  exponential_average_bucket_processing_time_per_hour_ms number
  
  Time unit for fractional milliseconds
  
  job_id string Required
  
  total_bucket_processing_time_ms number
  
  Time unit for fractional milliseconds
  
  maximum_bucket_processing_time_ms number
  
  Time unit for fractional milliseconds
  
  minimum_bucket_processing_time_ms number
  
  Time unit for fractional milliseconds
  
  deleting boolean
  
  Indicates that the process of deleting the job is in progress but not yet completed. It is only reported when true.

GET /_ml/anomaly_detectors/{job_id}/_stats

curl \
 --request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/_stats' \
 --header "Authorization: $API_KEY"

Explain data frame analytics config Added in 7.3.0

GET /_ml/data_frame/analytics/_explain

Api key auth Basic auth Bearer auth

This API provides explanations for a data frame analytics config that either exists already or one that has not been created yet. The following explanations are provided:

which fields are included or not in the analysis and why,
how much memory is estimated to be required. The estimate can be used when deciding the appropriate value for model_memory_limit setting later on. If you have object fields or fields that are excluded via source filtering, they are not included in the explanation.

application/json

Body

source object
Hide source attributes Show source attributes object
- index string | array[string] Required
- runtime_mappings object
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  collapse object
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  from 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
  
  track_total_hits 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. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  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 array[object]
  
  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
  
  rank object
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  profile 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 object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  rescore
  
  retriever object
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size 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 object
  
  sort
  
  _source
  
  fields array[object]
  
  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 object
  
  terminate_after 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 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 boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  stored_fields string | array[string]
  
  pit object
  
  runtime_mappings object
  
  stats array[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.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- _source object
  Hide _source attributes Show _source attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
- query object
  
  The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.
  
  Query DSL
dest object
Hide dest attributes Show dest attributes object
- index string Required
- results_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
analysis object
Hide analysis attributes Show analysis attributes object
- classification object
  Hide classification attributes Show classification attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  Hide frequency_encoding attributes Show frequency_encoding attributes object
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  frequency_map object Required
  
  The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.
  
  multi_encoding object
  
  Hide multi_encoding attribute Show multi_encoding attribute object
  
  processors array[number] Required
  
  The ordered array of custom processors to execute. Must be more than 1.
  
  n_gram_encoding object
  
  Hide n_gram_encoding attributes Show n_gram_encoding attributes object
  
  feature_prefix string
  
  The feature name prefix. Defaults to ngram__.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  length number
  
  Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.
  
  n_grams array[number] Required
  
  Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.
  
  start number
  
  Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.
  
  custom boolean
  
  one_hot_encoding object
  
  Hide one_hot_encoding attributes Show one_hot_encoding attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  hot_map string Required
  
  The one hot map mapping the field value with the column name.
  
  target_mean_encoding object
  
  Hide target_mean_encoding attributes Show target_mean_encoding attributes object
  
  default_value number Required
  
  The default value if field value is not found in the target_map.
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_map object Required
  
  The field value to target mean transition map.
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  class_assignment_objective string
  
  num_top_classes number
  
  Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.
- outlier_detection object
  Hide outlier_detection attributes Show outlier_detection attributes object
  
  compute_feature_influence boolean
  
  Specifies whether the feature influence calculation is enabled.
  
  feature_influence_threshold number
  
  The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.
  
  method string
  
  The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.
  
  n_neighbors number
  
  Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.
  
  outlier_fraction number
  
  The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.
  
  standardization_enabled boolean
  
  If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).
- regression object
  Hide regression attributes Show regression attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  Hide frequency_encoding attributes Show frequency_encoding attributes object
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  frequency_map object Required
  
  The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.
  
  multi_encoding object
  
  Hide multi_encoding attribute Show multi_encoding attribute object
  
  processors array[number] Required
  
  The ordered array of custom processors to execute. Must be more than 1.
  
  n_gram_encoding object
  
  Hide n_gram_encoding attributes Show n_gram_encoding attributes object
  
  feature_prefix string
  
  The feature name prefix. Defaults to ngram__.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  length number
  
  Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.
  
  n_grams array[number] Required
  
  Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.
  
  start number
  
  Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.
  
  custom boolean
  
  one_hot_encoding object
  
  Hide one_hot_encoding attributes Show one_hot_encoding attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  hot_map string Required
  
  The one hot map mapping the field value with the column name.
  
  target_mean_encoding object
  
  Hide target_mean_encoding attributes Show target_mean_encoding attributes object
  
  default_value number Required
  
  The default value if field value is not found in the target_map.
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_map object Required
  
  The field value to target mean transition map.
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  loss_function string
  
  The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).
  
  loss_function_parameter number
  
  A positive number that is used as a parameter to the loss_function.
description string

A description of the job.
model_memory_limit string

The approximate maximum amount of memory resources that are permitted for analytical processing. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting.
max_num_threads number

The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.
analyzed_fields object
Hide analyzed_fields attributes Show analyzed_fields attributes object
- includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
- excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
allow_lazy_start boolean

Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

Responses

200 application/json
Hide response attributes Show response attributes object
- field_selection array[object] Required
  
  An array of objects that explain selection for each field, sorted by the field names.
  
  Hide field_selection attributes Show field_selection attributes object
  
  is_included boolean Required
  
  Whether the field is selected to be included in the analysis.
  
  is_required boolean Required
  
  Whether the field is required.
  
  feature_type string
  
  The feature type of this field for the analysis. May be categorical or numerical.
  
  mapping_types array[string] Required
  
  The mapping types of the field.
  
  name string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  reason string
  
  The reason a field is not selected to be included in the analysis.
- memory_estimation object Required
  
  Hide memory_estimation attributes Show memory_estimation attributes object
  
  expected_memory_with_disk string Required
  
  Estimated memory usage under the assumption that overflowing to disk is allowed during data frame analytics. expected_memory_with_disk is usually smaller than expected_memory_without_disk as using disk allows to limit the main memory needed to perform data frame analytics.
  
  expected_memory_without_disk string Required
  
  Estimated memory usage under the assumption that the whole data frame analytics should happen in memory (i.e. without overflowing to disk).

GET /_ml/data_frame/analytics/_explain

curl \
 --request GET 'http://api.example.com/_ml/data_frame/analytics/_explain' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"source\": {\n    \"index\": \"houses_sold_last_10_yrs\"\n  },\n  \"analysis\": {\n    \"regression\": {\n      \"dependent_variable\": \"price\"\n    }\n  }\n}"'

Request example

Run `POST _ml/data_frame/analytics/_explain` to explain a data frame analytics job configuration.

{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "price"
    }
  }
}

Response examples (200)

A succesful response for explaining a data frame analytics job configuration.

{
  "field_selection": [
    {
      "field": "number_of_bedrooms",
      "mappings_types": [
        "integer"
      ],
      "is_included": true,
      "is_required": false,
      "feature_type": "numerical"
    },
    {
      "field": "postcode",
      "mappings_types": [
        "text"
      ],
      "is_included": false,
      "is_required": false,
      "reason": "[postcode.keyword] is preferred because it is aggregatable"
    },
    {
      "field": "postcode.keyword",
      "mappings_types": [
        "keyword"
      ],
      "is_included": true,
      "is_required": false,
      "feature_type": "categorical"
    },
    {
      "field": "price",
      "mappings_types": [
        "float"
      ],
      "is_included": true,
      "is_required": true,
      "feature_type": "numerical"
    }
  ],
  "memory_estimation": {
    "expected_memory_without_disk": "128MB",
    "expected_memory_with_disk": "32MB"
  }
}

Explain data frame analytics config Added in 7.3.0

POST /_ml/data_frame/analytics/{id}/_explain

Api key auth Basic auth Bearer auth

This API provides explanations for a data frame analytics config that either exists already or one that has not been created yet. The following explanations are provided:

which fields are included or not in the analysis and why,
how much memory is estimated to be required. The estimate can be used when deciding the appropriate value for model_memory_limit setting later on. If you have object fields or fields that are excluded via source filtering, they are not included in the explanation.

Path parameters

id string Required

Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

application/json

Body

source object
Hide source attributes Show source attributes object
- index string | array[string] Required
- runtime_mappings object
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  collapse object
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  from 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
  
  track_total_hits 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. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  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 array[object]
  
  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
  
  rank object
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  profile 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 object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  rescore
  
  retriever object
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size 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 object
  
  sort
  
  _source
  
  fields array[object]
  
  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 object
  
  terminate_after 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 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 boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  stored_fields string | array[string]
  
  pit object
  
  runtime_mappings object
  
  stats array[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.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- _source object
  Hide _source attributes Show _source attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
- query object
  
  The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.
  
  Query DSL
dest object
Hide dest attributes Show dest attributes object
- index string Required
- results_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
analysis object
Hide analysis attributes Show analysis attributes object
- classification object
  Hide classification attributes Show classification attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  Hide frequency_encoding attributes Show frequency_encoding attributes object
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  frequency_map object Required
  
  The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.
  
  multi_encoding object
  
  Hide multi_encoding attribute Show multi_encoding attribute object
  
  processors array[number] Required
  
  The ordered array of custom processors to execute. Must be more than 1.
  
  n_gram_encoding object
  
  Hide n_gram_encoding attributes Show n_gram_encoding attributes object
  
  feature_prefix string
  
  The feature name prefix. Defaults to ngram__.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  length number
  
  Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.
  
  n_grams array[number] Required
  
  Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.
  
  start number
  
  Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.
  
  custom boolean
  
  one_hot_encoding object
  
  Hide one_hot_encoding attributes Show one_hot_encoding attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  hot_map string Required
  
  The one hot map mapping the field value with the column name.
  
  target_mean_encoding object
  
  Hide target_mean_encoding attributes Show target_mean_encoding attributes object
  
  default_value number Required
  
  The default value if field value is not found in the target_map.
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_map object Required
  
  The field value to target mean transition map.
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  class_assignment_objective string
  
  num_top_classes number
  
  Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.
- outlier_detection object
  Hide outlier_detection attributes Show outlier_detection attributes object
  
  compute_feature_influence boolean
  
  Specifies whether the feature influence calculation is enabled.
  
  feature_influence_threshold number
  
  The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.
  
  method string
  
  The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.
  
  n_neighbors number
  
  Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.
  
  outlier_fraction number
  
  The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.
  
  standardization_enabled boolean
  
  If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).
- regression object
  Hide regression attributes Show regression attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  Hide frequency_encoding attributes Show frequency_encoding attributes object
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  frequency_map object Required
  
  The resulting frequency map for the field value. If the field value is missing from the frequency_map, the resulting value is 0.
  
  multi_encoding object
  
  Hide multi_encoding attribute Show multi_encoding attribute object
  
  processors array[number] Required
  
  The ordered array of custom processors to execute. Must be more than 1.
  
  n_gram_encoding object
  
  Hide n_gram_encoding attributes Show n_gram_encoding attributes object
  
  feature_prefix string
  
  The feature name prefix. Defaults to ngram__.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  length number
  
  Specifies the length of the n-gram substring. Defaults to 50. Must be greater than 0.
  
  n_grams array[number] Required
  
  Specifies which n-grams to gather. It’s an array of integer values where the minimum value is 1, and a maximum value is 5.
  
  start number
  
  Specifies the zero-indexed start of the n-gram substring. Negative values are allowed for encoding n-grams of string suffixes. Defaults to 0.
  
  custom boolean
  
  one_hot_encoding object
  
  Hide one_hot_encoding attributes Show one_hot_encoding attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  hot_map string Required
  
  The one hot map mapping the field value with the column name.
  
  target_mean_encoding object
  
  Hide target_mean_encoding attributes Show target_mean_encoding attributes object
  
  default_value number Required
  
  The default value if field value is not found in the target_map.
  
  feature_name string Required
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_map object Required
  
  The field value to target mean transition map.
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  loss_function string
  
  The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).
  
  loss_function_parameter number
  
  A positive number that is used as a parameter to the loss_function.
description string

A description of the job.
model_memory_limit string

The approximate maximum amount of memory resources that are permitted for analytical processing. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting.
max_num_threads number

The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.
analyzed_fields object
Hide analyzed_fields attributes Show analyzed_fields attributes object
- includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
- excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
allow_lazy_start boolean

Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

Responses

200 application/json
Hide response attributes Show response attributes object
- field_selection array[object] Required
  
  An array of objects that explain selection for each field, sorted by the field names.
  
  Hide field_selection attributes Show field_selection attributes object
  
  is_included boolean Required
  
  Whether the field is selected to be included in the analysis.
  
  is_required boolean Required
  
  Whether the field is required.
  
  feature_type string
  
  The feature type of this field for the analysis. May be categorical or numerical.
  
  mapping_types array[string] Required
  
  The mapping types of the field.
  
  name string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  reason string
  
  The reason a field is not selected to be included in the analysis.
- memory_estimation object Required
  
  Hide memory_estimation attributes Show memory_estimation attributes object
  
  expected_memory_with_disk string Required
  
  Estimated memory usage under the assumption that overflowing to disk is allowed during data frame analytics. expected_memory_with_disk is usually smaller than expected_memory_without_disk as using disk allows to limit the main memory needed to perform data frame analytics.
  
  expected_memory_without_disk string Required
  
  Estimated memory usage under the assumption that the whole data frame analytics should happen in memory (i.e. without overflowing to disk).

POST /_ml/data_frame/analytics/{id}/_explain

curl \
 --request POST 'http://api.example.com/_ml/data_frame/analytics/{id}/_explain' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"source\": {\n    \"index\": \"houses_sold_last_10_yrs\"\n  },\n  \"analysis\": {\n    \"regression\": {\n      \"dependent_variable\": \"price\"\n    }\n  }\n}"'

Request example

Run `POST _ml/data_frame/analytics/_explain` to explain a data frame analytics job configuration.

{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "price"
    }
  }
}

Response examples (200)

A succesful response for explaining a data frame analytics job configuration.

{
  "field_selection": [
    {
      "field": "number_of_bedrooms",
      "mappings_types": [
        "integer"
      ],
      "is_included": true,
      "is_required": false,
      "feature_type": "numerical"
    },
    {
      "field": "postcode",
      "mappings_types": [
        "text"
      ],
      "is_included": false,
      "is_required": false,
      "reason": "[postcode.keyword] is preferred because it is aggregatable"
    },
    {
      "field": "postcode.keyword",
      "mappings_types": [
        "keyword"
      ],
      "is_included": true,
      "is_required": false,
      "feature_type": "categorical"
    },
    {
      "field": "price",
      "mappings_types": [
        "float"
      ],
      "is_included": true,
      "is_required": true,
      "feature_type": "numerical"
    }
  ],
  "memory_estimation": {
    "expected_memory_without_disk": "128MB",
    "expected_memory_with_disk": "32MB"
  }
}

Get feature migration information Added in 7.16.0

GET /_migration/system_features

Api key auth Basic auth Bearer auth

Version upgrades sometimes require changes to how features store configuration information and data in system indices. Check which features need to be migrated and the status of any migrations that are in progress.

TIP: This API is designed for indirect use by the Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant.

Responses

200 application/json
Hide response attributes Show response attributes object
- features array[object] Required
  
  Hide features attributes Show features attributes object
  
  feature_name string Required
  
  minimum_index_version string Required
  
  migration_status string Required
  
  Values are NO_MIGRATION_NEEDED, MIGRATION_NEEDED, IN_PROGRESS, or ERROR.
  
  indices array[object] Required
  
  Hide indices attributes Show indices attributes object
  
  index string Required
  
  version string Required
  
  failure_cause object
  
  Hide failure_cause attributes Show failure_cause attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
- migration_status string Required
  
  Values are NO_MIGRATION_NEEDED, MIGRATION_NEEDED, IN_PROGRESS, or ERROR.

GET /_migration/system_features

curl \
 --request GET 'http://api.example.com/_migration/system_features' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_migration/system_features`.

{
  "features" : [
    {
      "feature_name" : "async_search",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "enrich",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "ent_search",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "fleet",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "geoip",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "kibana",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "logstash_management",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "machine_learning",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "searchable_snapshots",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "security",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "synonyms",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "tasks",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "transform",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    },
    {
      "feature_name" : "watcher",
      "minimum_index_version" : "8100099",
      "migration_status" : "NO_MIGRATION_NEEDED",
      "indices" : [ ]
    }
  ],
  "migration_status" : "NO_MIGRATION_NEEDED"
}

Run a script Technical preview

POST /_scripts/painless/_execute

Api key auth Basic auth Bearer auth

Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.

The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.

Each context requires a script, but additional parameters depend on the context you're using for that script.

application/json

Body

context string

Values are painless_test, filter, score, boolean_field, date_field, double_field, geo_point_field, ip_field, keyword_field, long_field, or composite_field.
context_setup object
Hide context_setup attributes Show context_setup attributes object
- document object Required
  
  Document that's temporarily indexed in-memory and accessible from the script.
- index string Required
- query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
script object
Hide script attributes Show script attributes object
- source string | object
 
 One of:
 ScriptSource string SearchRequestBody object
 
 Hide attributes Show attributes
 
 aggregations object
 
 Defines the aggregations that are run as part of the search request.
 
 External documentation
 
 collapse object
 External documentation
 
 explain boolean
 
 If true, the request returns detailed information about score computation as part of a hit.
 
 ext object
 
 Configuration of search extensions defined by Elasticsearch plugins.
 
 Hide ext attribute Show ext attribute object
 
 * object Additional properties
 
 from 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 object
 
 Hide highlight attributes Show highlight attributes object
 
 type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 Hide options attribute Show options attribute object
 
 * object Additional properties
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 track_total_hits 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. Defaults to 10,000 hits.
 
 indices_boost array[object]
 
 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.
 
 External documentation
 
 Hide indices_boost attribute Show indices_boost attribute object
 
 * number Additional properties
 
 docvalue_fields array[object]
 
 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.
 
 External documentation
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 knn object | array[object]
 
 The approximate kNN search to run.
 
 One of:
 KnnSearch object array-2 array[object]
 
 Hide attributes Show attributes
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 Hide query_vector_builder attribute Show query_vector_builder attribute object
 
 text_embedding object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter object | array[object]
 
 Filters for the kNN search query
 
 One of:
 QueryContainer object array-2 array[object]
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 Hide inner_hits attributes Show inner_hits attributes object
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 from number
 
 Inner hit starting document offset.
 
 collapse object
 
 docvalue_fields array[object]
 
 explain boolean
 
 highlight
 
 ignore_unmapped boolean
 
 script_fields object
 
 seq_no_primary_term boolean
 
 fields array[string]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 sort
 
 _source
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 version boolean
 
 rescore_vector object
 
 Hide rescore_vector attribute Show rescore_vector attribute object
 
 oversample number Required
 
 Applies the specified oversample factor to k on the approximate kNN search
 
 External documentation
 
 Hide attributes Show attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 rescore_vector object
 
 rank object
 
 Hide rank attribute Show rank attribute object
 
 rrf object
 
 Hide rrf attributes Show rrf attributes object
 
 rank_constant number
 
 How much influence documents in individual result sets per query have over the final ranked result set
 
 rank_window_size number
 
 Size of the individual result sets per query
 
 min_score number
 
 The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
 
 post_filter object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 profile 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 object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 rescore object | array[object]
 
 Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
 
 One of:
 Rescore object array-2 array[object]
 
 Hide attributes Show attributes
 
 window_size number
 
 query object
 
 learning_to_rank object
 
 retriever object
 
 Hide retriever attributes Show retriever attributes object
 
 standard object
 
 Hide standard attributes Show standard attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 terminate_after number
 
 Maximum number of documents to collect for each shard.
 
 sort
 
 collapse object
 
 knn object
 
 Hide knn attributes Show knn attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 field string Required
 
 The name of the vector field to search against.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number Required
 
 Number of nearest neighbors to return as top hits.
 
 num_candidates number Required
 
 Number of nearest neighbor candidates to consider per shard.
 
 similarity number
 
 The minimum similarity required for a document to be considered a match.
 
 rescore_vector object
 
 rrf object
 
 Hide rrf attributes Show rrf attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 retrievers array[object] Required
 
 A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
 
 rank_constant number
 
 This value determines how much influence documents in individual result sets per query have over the final ranked result set.
 
 rank_window_size number
 
 This value determines the size of the individual result sets per query.
 
 text_similarity_reranker object
 
 Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 retriever object Required
 
 rank_window_size number
 
 This value determines how many documents we will consider from the nested retriever.
 
 inference_id string
 
 Unique identifier of the inference endpoint created using the inference API.
 
 inference_text string
 
 The text snippet used as the basis for similarity comparison
 
 field string
 
 The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
 
 rule object
 
 Hide rule attributes Show rule attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 ruleset_ids array[string] Required
 
 The ruleset IDs containing the rules this retriever is evaluating against.
 
 match_criteria object Required
 
 The match criteria that will determine if a rule in the provided rulesets should be applied.
 
 retriever object Required
 
 rank_window_size number
 
 This value determines the size of the individual result set.
 
 script_fields object
 
 Retrieve a script evaluation (based on different fields) for each hit.
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 ignore_failure boolean
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 size 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 object
 
 Hide slice attributes Show slice attributes object
 
 field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 id string Required
 
 max number Required
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 fields array[object]
 
 An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
 
 Hide fields attributes Show fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 suggest object
 
 Hide suggest attribute Show suggest attribute object
 
 text string
 
 Global suggest text, to avoid repetition when the same text is used in several suggesters
 
 terminate_after 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 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 boolean
 
 If true, calculate and return document scores, even if the scores are not used for sorting.
 
 version boolean
 
 If true, the request returns the document version as part of a hit.
 
 seq_no_primary_term boolean
 
 If true, the request returns sequence number and primary term of the last modification of each hit.
 
 External documentation
 
 stored_fields string | array[string]
 
 pit object
 
 Hide pit attributes Show pit attributes object
 
 id string Required
 
 keep_alive string
 
 A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
 
 runtime_mappings object
 
 Hide runtime_mappings attribute Show runtime_mappings attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 fields object
 
 For type composite
 
 Hide fields attribute Show fields attribute object
 
 * object Additional properties
 
 fetch_fields array[object]
 
 For type lookup
 
 format string
 
 A custom format for date type runtime fields.
 
 input_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_index string
 
 script object
 
 type string Required
 
 Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
 
 stats array[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.
- id string
- params object
 
 Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
 Hide params attribute Show params attribute object
 
 * object Additional properties
- lang string
 
 Any of:
 ScriptLanguage string ScriptLanguage string
 
 Values are painless, expression, mustache, or java.
- options object
 Hide options attribute Show options attribute object
 
 * string Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- result object Required

POST /_scripts/painless/_execute

curl \
 --request POST 'http://api.example.com/_scripts/painless/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"script\": {\n    \"source\": \"params.count / params.total\",\n    \"params\": {\n      \"count\": 100.0,\n      \"total\": 1000.0\n    }\n  }\n}"'

Request examples

Run `POST /_scripts/painless/_execute`. The `painless_test` context is the default context. It runs scripts without additional parameters. The only variable that is available is `params`, which can be used to access user defined values. The result of the script is always converted to a string.

{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}

Run `POST /_scripts/painless/_execute` with a `filter` context. It treats scripts as if they were run inside a script query. For testing purposes, a document must be provided so that it will be temporarily indexed in-memory and is accessible from the script. More precisely, the `_source`, stored fields, and doc values of such a document are available to the script being tested.

{
  "script": {
    "source": "doc['field'].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "field": "four"
    }
  }
}

Run `POST /_scripts/painless/_execute` with a `score` context. It treats scripts as if they were run inside a `script_score` function in a `function_score` query.

{
  "script": {
    "source": "doc['rank'].value / params.max_rank",
    "params": {
      "max_rank": 5.0
    }
  },
  "context": "score",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "rank": 4
    }
  }
}

Response examples (200)

A successful response from `POST /_scripts/painless/_execute` with a `painless_test` context.

{
  "result": "0.1"
}

A successful response from `POST /_scripts/painless/_execute` with a `filter` context.

{
  "result": true
}

A successful response from `POST /_scripts/painless/_execute` with a `score` context.

{
  "result": 0.8
}

Count search results

POST /{index}/_count

Api key auth Basic auth Bearer auth

Get the number of documents matching a query.

The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. The query is optional. When no query is provided, the API uses match_all to count all the documents.

The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

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.

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams and indices, omit this parameter or use * or _all.

Query parameters

allow_no_indices 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 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 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 string

The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

Values are and, AND, or, or OR.
df 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 string | array[string]
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 comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_throttled boolean Deprecated

If true, concrete, expanded, or aliased indices are ignored when frozen.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
lenient 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 number

The minimum _score value that documents must have to be included in the result.
preference string

The node or shard the operation should be performed on. By default, it is random.
routing string

A custom value used to route operations to a specific shard.
terminate_after 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 string

The query in Lucene query string syntax. This parameter cannot be used with a request body.

application/json

Body

query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

POST /{index}/_count

curl \
 --request POST 'http://api.example.com/{index}/_count' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\" : {\n    \"term\" : { \"user.id\" : \"kimchy\" }\n  }\n}"'

Request example

Run `GET /my-index-000001/_count?q=user:kimchy`. Alternatively, run `GET /my-index-000001/_count` with the same query in the request body. Both requests count the number of documents in `my-index-000001` with a `user.id` of `kimchy`.

{
  "query" : {
    "term" : { "user.id" : "kimchy" }
  }
}

Response examples (200)

A successful response from `GET /my-index-000001/_count?q=user:kimchy`.

{
  "count": 1,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}

Run multiple searches Added in 1.3.0

POST /{index}/_msearch

Api key auth Basic auth Bearer auth

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.

IMPORTANT: 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 requests to this endpoint the Content-Type header should be set to application/x-ndjson.

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, and index aliases to search.

Query parameters

allow_no_indices 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 boolean

If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
expand_wildcards string | array[string]
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.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_throttled boolean

If true, concrete, expanded or aliased indices are ignored when frozen.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
include_named_queries_score 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 number

Maximum number of concurrent searches the multi search API can execute. Defaults to max(1, (# of data nodes * min(search thread pool size, 10))).
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.
pre_filter_shard_size 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.
rest_total_hits_as_int boolean

If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
routing string

Custom routing value used to route search operations to a specific shard.
search_type string
Indicates whether global term and document frequencies should be used when scoring returned documents.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
typed_keys boolean

Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.

application/json

Body object Required

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
External documentation
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from 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 object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
- boundary_max_scan number
 
 How far to scan for boundary characters.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object Required
track_total_hits 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. Defaults to 10,000 hits.
indices_boost array[object]

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.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

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.

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object
External documentation

docvalue_fields array[object]

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields array[string]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

sort array[string | object]

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields array[string]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

sort

_source

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
post_filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
profile 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 object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
Rescore object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature
Hide attributes Show attributes object

window_size number

query object

learning_to_rank object
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort array[string | object]
  
  collapse object
  External documentation
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string
  
  The text snippet used as the basis for similarity comparison
  
  field string
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  ruleset_ids array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size 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 object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfig boolean SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after 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 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 boolean

If true, calculate and return document scores, even if the scores are not used for sorting.
version boolean

If true, the request returns the document version as part of a hit.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[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.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- responses array[object] Required
  
  One of:
  MultiSearchItem object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  Hide attributes Show attributes
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  status number Required

POST /{index}/_msearch

curl \
 --request POST 'http://api.example.com/{index}/_msearch' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'

Open a point in time Added in 7.10.0

POST /{index}/_pit

Api key auth Basic auth Bearer auth

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.

Path parameters

index string | array[string] Required

A comma-separated list of index names to open point in time; use _all or empty string to perform the operation on all indices

Query parameters

keep_alive string Required

Extend the length of time that the point in time persists.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
preference string

The node or shard the operation should be performed on. By default, it is random.
routing string

A custom value that is used to route operations to a specific shard.
expand_wildcards string | array[string]
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 comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
allow_partial_search_results 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.
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.

application/json

Body

index_filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- id string Required

POST /{index}/_pit

curl \
 --request POST 'http://api.example.com/{index}/_pit?keep_alive=string' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"index_filter":{}}'

Response examples (200)

A successful response from `POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true`. It includes a summary of the total number of shards, as well as the number of successful shards when creating the PIT.

{
  "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=",
  "_shards": {
    "total": 10,
    "successful": 10,
    "skipped": 0,
    "failed": 0
  }
}

Clear the cache Technical preview

POST /_searchable_snapshots/cache/clear

Api key auth Basic auth Bearer auth

Clear indices and data streams from the shared cache for partially mounted indices.

External documentation

Query parameters

expand_wildcards string | array[string]
Whether to expand wildcard expression to concrete indices that are open, closed or both.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
allow_no_indices 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 boolean

Whether specified concrete indices should be ignored when unavailable (missing or closed)

Responses

200 application/json

POST /_searchable_snapshots/cache/clear

curl \
 --request POST 'http://api.example.com/_searchable_snapshots/cache/clear' \
 --header "Authorization: $API_KEY"

Clear the API key cache Added in 7.10.0

POST /_security/api_key/{ids}/_clear_cache

Api key auth Basic auth Bearer auth

Evict a subset of all entries from the API key cache. The cache is also automatically cleared on state changes of the security index.

Path parameters

ids string | array[string] Required

Comma-separated list of API key IDs to evict from the API key cache. To evict all API keys, use *. Does not support other wildcard patterns.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object Required
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  name string Required

POST /_security/api_key/{ids}/_clear_cache

curl \
 --request POST 'http://api.example.com/_security/api_key/{ids}/_clear_cache' \
 --header "Authorization: $API_KEY"

Clear the privileges cache Added in 7.9.0

POST /_security/privilege/{application}/_clear_cache

Api key auth Basic auth Bearer auth

Evict privileges from the native application privilege cache. The cache is also automatically cleared for applications that have their privileges updated.

Path parameters

application string Required

A comma-separated list of applications. To clear all applications, use an asterism (*). It does not support other wildcard patterns.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object Required
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  name string Required

POST /_security/privilege/{application}/_clear_cache

curl \
 --request POST 'http://api.example.com/_security/privilege/{application}/_clear_cache' \
 --header "Authorization: $API_KEY"

Create a service account token

PUT /_security/service/{namespace}/{service}/credential/token/{name}

Api key auth Basic auth Bearer auth

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.

External documentation

Path parameters

namespace string Required

The name of the namespace, which is a top-level grouping of service accounts.
service string Required

The name of the service.
name string Required

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 <namespace>/<service>/<token-name>.

Query parameters

refresh string

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.

Values are true, false, or wait_for.

Responses

200 application/json
Hide response attributes Show response attributes object
- created boolean Required
- token object Required
  
  Hide token attributes Show token attributes object
  
  name string Required
  
  value string Required

PUT /_security/service/{namespace}/{service}/credential/token/{name}

curl \
 --request PUT 'http://api.example.com/_security/service/{namespace}/{service}/credential/token/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `POST /_security/service/elastic/fleet-server/credential/token/token1`. The response includes the service account token, its name, and its secret value as a bearer token.

{
  "created": true,
  "token": {
    "name": "token1",
    "value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" 
  }
}

Delete application privileges Added in 6.4.0

DELETE /_security/privilege/{application}/{name}

Api key auth Basic auth Bearer auth

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.

External documentation

Path parameters

application string Required

The name of the application. Application privileges are always associated with exactly one application.
name string | array[string] Required

The name of the privilege.

Query parameters

refresh string

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.

Values are true, false, or wait_for.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  found boolean Required

DELETE /_security/privilege/{application}/{name}

curl \
 --request DELETE 'http://api.example.com/_security/privilege/{application}/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `DELETE /_security/privilege/myapp/read`. If the privilege is successfully deleted, `found` is set to `true`.

{
  "myapp": {
    "read": {
      "found" : true
    }
  }
}

Get roles

GET /_security/role/{name}

Api key auth Basic auth Bearer auth

Get 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 get roles API cannot retrieve roles that are defined in roles files.

Path parameters

name string | array[string] Required

The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attributes Show * attributes object
  
  cluster array[string] Required
  
  indices array[object] Required
  
  Hide indices attributes Show indices attributes object
  
  field_security object
  
  Hide field_security attributes Show field_security attributes object
  
  except string | array[string]
  
  grant string | array[string]
  
  names string | array[string]
  
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  
  One of:
  IndexName string array-2 array[string]
  
  privileges array[string] Required
  
  The index level privileges that owners of the role have on the specified indices.
  
  query string | object
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  One of:
  IndicesPrivilegesQuery string QueryContainer object RoleTemplateQuery object
  
  allow_restricted_indices boolean
  
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  
  remote_indices array[object]
  
  Hide remote_indices attributes Show remote_indices attributes object
  
  clusters string | array[string] Required
  
  field_security object
  
  Hide field_security attributes Show field_security attributes object
  
  except string | array[string]
  
  grant string | array[string]
  
  names string | array[string]
  
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  
  One of:
  IndexName string array-2 array[string]
  
  privileges array[string] Required
  
  The index level privileges that owners of the role have on the specified indices.
  
  query string | object
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  One of:
  IndicesPrivilegesQuery string QueryContainer object RoleTemplateQuery object
  
  allow_restricted_indices boolean
  
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  
  remote_cluster array[object]
  
  Hide remote_cluster attributes Show remote_cluster attributes object
  
  clusters string | array[string] Required
  
  privileges array[string] Required
  
  The cluster level privileges that owners of the role have on the remote cluster.
  
  Values are monitor_enrich or monitor_stats.
  
  metadata object Required
  
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties
  
  description string
  
  run_as array[string]
  
  transient_metadata object
  
  Hide transient_metadata attribute Show transient_metadata attribute object
  
  * object Additional properties
  
  applications array[object] Required
  
  Hide applications attributes Show applications attributes object
  
  application string Required
  
  The name of the application to which this entry applies.
  
  privileges array[string] Required
  
  A list of strings, where each element is the name of an application privilege or action.
  
  resources array[string] Required
  
  A list resources to which the privileges are applied.
  
  role_templates array[object]
  
  Hide role_templates attributes Show role_templates attributes object
  
  format string
  
  Values are string or json.
  
  template object Required
  
  Hide template attributes Show template attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  global object
  
  Hide global attribute Show global attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * array[string] Additional properties

GET /_security/role/{name}

curl \
 --request GET 'http://api.example.com/_security/role/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_security/role/my_admin_role`. The response contains information about the `my_admin_role` role in the native realm.

{
  "my_admin_role": {
    "description": "Grants full access to all management features within the cluster.",
    "cluster" : [ "all" ],
    "indices" : [
      {
        "names" : [ "index1", "index2" ],
        "privileges" : [ "all" ],
        "allow_restricted_indices" : false,
        "field_security" : {
          "grant" : [ "title", "body" ]}
      }
    ],
    "applications" : [ ],
    "run_as" : [ "other_user" ],
    "metadata" : {
      "version" : 1
    },
    "transient_metadata": {
      "enabled": true
    }
  }
}

Check user profile privileges Added in 8.3.0

GET /_security/profile/_has_privileges

Api key auth Basic auth Bearer auth

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.

External documentation

application/json

Body Required

uids array[string] Required

A list of profile IDs. The privileges are checked for associated users of the profiles.
privileges object Required
Hide privileges attributes Show privileges attributes object
- application array[object]
  Hide application attributes Show application attributes object
  
  application string Required
  
  The name of the application.
  
  privileges array[string] Required
  
  A list of the privileges that you want to check for the specified resources. It may be either application privilege names or the names of actions that are granted by those privileges
  
  resources array[string] Required
  
  A list of resource names against which the privileges should be checked.
- cluster array[string]
  
  A list of the cluster privileges that you want to check.
- index array[object]
  Hide index attributes Show index attributes object
  
  names string | array[string] Required
  
  privileges array[string] Required
  
  A list of the privileges that you want to check for the specified indices.
  
  allow_restricted_indices boolean
  
  This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices. Implicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false. If restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices.

Responses

200 application/json
Hide response attributes Show response attributes object
- has_privilege_uids array[string] Required
  
  The subset of the requested profile IDs of the users that have all the requested privileges.
- errors object
  
  Hide errors attributes Show errors attributes object
  
  count number Required
  
  details object Required
  
  Hide details attribute Show details attribute object
  
  * object
  
  Hide * attributes Show * attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]

GET /_security/profile/_has_privileges

curl \
 --request GET 'http://api.example.com/_security/profile/_has_privileges' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"uids\": [\n    \"u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0\",\n    \"u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1\",\n    \"u_does-not-exist_0\"\n  ],\n  \"privileges\": {\n    \"cluster\": [ \"monitor\", \"create_snapshot\", \"manage_ml\" ],\n    \"index\" : [\n      {\n        \"names\": [ \"suppliers\", \"products\" ],\n        \"privileges\": [ \"create_doc\"]\n      },\n      {\n        \"names\": [ \"inventory\" ],\n        \"privileges\" : [ \"read\", \"write\" ]\n      }\n    ],\n    \"application\": [\n      {\n        \"application\": \"inventory_manager\",\n        \"privileges\" : [ \"read\", \"data:write/inventory\" ],\n        \"resources\" : [ \"product/1852563\" ]\n      }\n    ]\n  }\n}"'

Request example

Run `POST /_security/profile/_has_privileges` to check whether the two users associated with the specified profiles have all the requested set of cluster, index, and application privileges.

{
  "uids": [
    "u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0",
    "u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1",
    "u_does-not-exist_0"
  ],
  "privileges": {
    "cluster": [ "monitor", "create_snapshot", "manage_ml" ],
    "index" : [
      {
        "names": [ "suppliers", "products" ],
        "privileges": [ "create_doc"]
      },
      {
        "names": [ "inventory" ],
        "privileges" : [ "read", "write" ]
      }
    ],
    "application": [
      {
        "application": "inventory_manager",
        "privileges" : [ "read", "data:write/inventory" ],
        "resources" : [ "product/1852563" ]
      }
    ]
  }
}

Response examples (200)

A response from `POST /_security/profile/_has_privileges` that indicates only one of the three users has all the privileges and one of them is not found.

{
  "has_privilege_uids": ["u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"],
  "errors": {
    "count": 1,
    "details": {
      "u_does-not-exist_0": {
        "type": "resource_not_found_exception",
        "reason": "profile document not found"
      }
    }
  }
}

Clone a snapshot Added in 7.10.0

PUT /_snapshot/{repository}/{snapshot}/_clone/{target_snapshot}

Api key auth Basic auth Bearer auth

Clone part of all of a snapshot into another snapshot in the same repository.

Path parameters

repository string Required

The name of the snapshot repository that both source and target snapshot belong to.
snapshot string Required

The source snapshot name.
target_snapshot string Required

The target snapshot name.

Query parameters

master_timeout string

The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

application/json

Body Required

indices string Required

A comma-separated list of indices to include in the snapshot. Multi-target syntax is supported.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_snapshot/{repository}/{snapshot}/_clone/{target_snapshot}

curl \
 --request PUT 'http://api.example.com/_snapshot/{repository}/{snapshot}/_clone/{target_snapshot}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"indices\": \"index_a,index_b\"\n}"'

Request example

Run `PUT /_snapshot/my_repository/source_snapshot/_clone/target_snapshot` to clone the `source_snapshot` into a new `target_snapshot`.

{
  "indices": "index_a,index_b"
}

Delete snapshot repositories Added in 0.0.0

DELETE /_snapshot/{repository}

Api key auth Basic auth Bearer auth

When a repository is unregistered, Elasticsearch removes only the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place.

Path parameters

repository string | array[string] Required

The ame of the snapshot repositories to unregister. Wildcard (*) patterns are supported.

Query parameters

master_timeout string

The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.
timeout string

The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. To indicate that the request should never timeout, set it to -1.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_snapshot/{repository}

curl \
 --request DELETE 'http://api.example.com/_snapshot/{repository}' \
 --header "Authorization: $API_KEY"

Get the snapshot lifecycle management status Added in 7.6.0

GET /_slm/status

Api key auth Basic auth Bearer auth

Query parameters

master_timeout string

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. To indicate that the request should never timeout, set it to -1.
timeout string

The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

Responses

200 application/json
Hide response attribute Show response attribute object
- operation_mode string Required
  
  Values are RUNNING, STOPPING, or STOPPED.

GET /_slm/status

curl \
 --request GET 'http://api.example.com/_slm/status' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _slm/status`.

{
  "operation_mode": "RUNNING"
}

Translate SQL into Elasticsearch queries Added in 6.3.0

GET /_sql/translate

Api key auth Basic auth Bearer auth

Translate an SQL search into a search API request containing Query DSL. It accepts the same request body parameters as the SQL search API, excluding cursor.

application/json

Body Required

fetch_size number

The maximum number of rows (or entries) to return in one response.
filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
query string Required

The SQL query to run.
time_zone string

Responses

200 application/json
Hide response attributes Show response attributes object
- aggregations object
- size number
- _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  SourceConfig boolean SourceFilter object
- fields array[object]
  
  Hide fields attributes Show fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  The format in which the values are returned.
  
  include_unmapped boolean
- query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- sort string | object | array[string | object]
  
  One of:
  Field string SortOptions object Sort array[string | object]
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  Hide attributes Show attributes
  
  _score object
  
  Hide _score attribute Show _score attribute object
  
  order string
  
  Values are asc or desc.
  
  _doc object
  
  Hide _doc attribute Show _doc attribute object
  
  order string
  
  Values are asc or desc.
  
  _geo_distance object
  
  Hide _geo_distance attributes Show _geo_distance attributes object
  
  mode string
  
  Values are min, max, sum, avg, or median.
  
  distance_type string
  
  Values are arc or plane.
  
  ignore_unmapped boolean
  
  order string
  
  Values are asc or desc.
  
  unit string
  
  Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
  
  nested object
  
  Hide nested attributes Show nested attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  max_children number
  
  nested object
  
  path string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  _script object
  
  Hide _script attributes Show _script attributes object
  
  order string
  
  Values are asc or desc.
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string
  
  Values are string, number, or version.
  
  mode string
  
  Values are min, max, sum, avg, or median.
  
  nested object
  
  Hide nested attributes Show nested attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  max_children number
  
  nested object
  
  path string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  One of:
  Field string SortOptions object
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  Hide attributes Show attributes
  
  _score object
  
  Hide _score attribute Show _score attribute object
  
  order string
  
  Values are asc or desc.
  
  _doc object
  
  Hide _doc attribute Show _doc attribute object
  
  order string
  
  Values are asc or desc.
  
  _geo_distance object
  
  Hide _geo_distance attributes Show _geo_distance attributes object
  
  mode string
  
  Values are min, max, sum, avg, or median.
  
  distance_type string
  
  Values are arc or plane.
  
  ignore_unmapped boolean
  
  order string
  
  Values are asc or desc.
  
  unit string
  
  Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
  
  nested object
  
  _script object
  
  Hide _script attributes Show _script attributes object
  
  order string
  
  Values are asc or desc.
  
  script object Required
  
  type string
  
  Values are string, number, or version.
  
  mode string
  
  Values are min, max, sum, avg, or median.
  
  nested object

GET /_sql/translate

curl \
 --request GET 'http://api.example.com/_sql/translate' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": \"SELECT * FROM library ORDER BY page_count DESC\",\n  \"fetch_size\": 10\n}"'

Request example

{
  "query": "SELECT * FROM library ORDER BY page_count DESC",
  "fetch_size": 10
}

Delete a synonym set Added in 8.10.0

DELETE /_synonyms/{id}

Api key auth Basic auth Bearer auth

You can only delete a synonyms set that is not in use by any index analyzer.

Synonyms sets can be used in synonym graph token filters and synonym token filters. These synonym filters can be used as part of search analyzers.

Analyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open). Even if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.

If any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available. To prevent that, synonyms sets that are used in analyzers can't be deleted. A delete request in this case will return a 400 response code.

To remove a synonyms set, you must first remove all indices that contain analyzers using it. You can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data. Once finished, you can delete the index. When the synonyms set is not used in analyzers, you will be able to delete it.

Path parameters

id string Required

The synonyms set identifier to delete.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_synonyms/{id}

curl \
 --request DELETE 'http://api.example.com/_synonyms/{id}' \
 --header "Authorization: $API_KEY"

Activate a watch

POST /_watcher/watch/{watch_id}/_activate

Api key auth Basic auth Bearer auth

A watch can be either active or inactive.

External documentation

Path parameters

watch_id string Required

The watch identifier.

Responses

200 application/json
Hide response attribute Show response attribute object
- status object Required
  
  Hide status attributes Show status attributes object
  
  actions object Required
  
  Hide actions attribute Show actions attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  ack object Required
  
  Hide ack attributes Show ack attributes object
  
  state string Required
  
  Values are awaits_successful_execution, ackable, or acked.
  
  timestamp string
  
  last_execution object
  
  Hide last_execution attributes Show last_execution attributes object
  
  successful boolean Required
  
  timestamp string
  
  reason string
  
  last_successful_execution object
  
  Hide last_successful_execution attributes Show last_successful_execution attributes object
  
  successful boolean Required
  
  timestamp string
  
  reason string
  
  last_throttle object
  
  Hide last_throttle attributes Show last_throttle attributes object
  
  reason string Required
  
  timestamp string
  
  state object Required
  
  Hide state attributes Show state attributes object
  
  active boolean Required
  
  timestamp string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  version number Required

POST /_watcher/watch/{watch_id}/_activate

curl \
 --request POST 'http://api.example.com/_watcher/watch/{watch_id}/_activate' \
 --header "Authorization: $API_KEY"

Deactivate a watch

PUT /_watcher/watch/{watch_id}/_deactivate

Api key auth Basic auth Bearer auth

A watch can be either active or inactive.

External documentation

Path parameters

watch_id string Required

The watch identifier.

Responses

200 application/json
Hide response attribute Show response attribute object
- status object Required
  
  Hide status attributes Show status attributes object
  
  actions object Required
  
  Hide actions attribute Show actions attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  ack object Required
  
  Hide ack attributes Show ack attributes object
  
  state string Required
  
  Values are awaits_successful_execution, ackable, or acked.
  
  timestamp string
  
  last_execution object
  
  Hide last_execution attributes Show last_execution attributes object
  
  successful boolean Required
  
  timestamp string
  
  reason string
  
  last_successful_execution object
  
  Hide last_successful_execution attributes Show last_successful_execution attributes object
  
  successful boolean Required
  
  timestamp string
  
  reason string
  
  last_throttle object
  
  Hide last_throttle attributes Show last_throttle attributes object
  
  reason string Required
  
  timestamp string
  
  state object Required
  
  Hide state attributes Show state attributes object
  
  active boolean Required
  
  timestamp string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  version number Required

PUT /_watcher/watch/{watch_id}/_deactivate

curl \
 --request PUT 'http://api.example.com/_watcher/watch/{watch_id}/_deactivate' \
 --header "Authorization: $API_KEY"

Run a watch

PUT /_watcher/watch/{id}/_execute

Api key auth Basic auth Bearer auth

This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing and debugging your watches prior to adding them to Watcher.

When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches. If your user is allowed to read index a, but not index b, then the exact same set of rules will apply during execution of a watch.

When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch.

Path parameters

id string Required

The watch identifier.

Query parameters

debug boolean

Defines whether the watch runs in debug mode.

application/json

Body

action_modes object

Determines how to handle the watch actions as part of the watch execution.
Hide action_modes attribute Show action_modes attribute object
- * string Additional properties
  
  Values are simulate, force_simulate, execute, force_execute, or skip.
alternative_input object

When present, the watch uses this object as a payload instead of executing its own input.
Hide alternative_input attribute Show alternative_input attribute object
- * object Additional properties
ignore_condition boolean

When set to true, the watch execution uses the always condition. This can also be specified as an HTTP parameter.
record_execution boolean

When set to true, the watch record representing the watch execution result is persisted to the .watcher-history index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent runs. This can also be specified as an HTTP parameter.
simulated_actions object
Hide simulated_actions attributes Show simulated_actions attributes object
- actions array[string] Required
- all object Required
- use_all boolean Required
trigger_data object
Hide trigger_data attributes Show trigger_data attributes object
- scheduled_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
- triggered_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
watch object
Hide watch attributes Show watch attributes object
- actions object Required
  Hide actions attribute Show actions attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  action_type string
  
  Values are email, webhook, index, logging, slack, or pagerduty.
  
  condition object
  
  Hide condition attributes Show condition attributes object
  
  always object
  
  array_compare object
  
  Hide array_compare attribute Show array_compare attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  path string Required
  
  compare object
  
  Hide compare attribute Show compare attribute object
  
  * object Additional properties
  
  never object
  
  script object
  
  Hide script attributes Show script attributes object
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  foreach string
  
  max_iterations number
  
  name string
  
  throttle_period string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  throttle_period_in_millis number
  
  Time unit for milliseconds
  
  transform object
  
  Hide transform attributes Show transform attributes object
  
  chain array[object]
  
  script object
  
  Hide script attributes Show script attributes object
  
  lang string
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  search object
  
  Hide search attributes Show search attributes object
  
  request object Required
  
  Hide request attributes Show request attributes object
  
  body object
  
  indices array[string]
  
  indices_options object
  
  search_type string
  
  Values are query_then_fetch or dfs_query_then_fetch.
  
  template object
  
  rest_total_hits_as_int boolean
  
  timeout string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  index object
  
  Hide index attributes Show index attributes object
  
  index string Required
  
  doc_id string
  
  refresh string
  
  Values are true, false, or wait_for.
  
  op_type string
  
  Values are index or create.
  
  timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  execution_time_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  logging object
  
  Hide logging attributes Show logging attributes object
  
  level string
  
  text string Required
  
  category string
  
  email object
  
  Hide email attributes Show email attributes object
  
  id string
  
  bcc string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  body object
  
  Hide body attributes Show body attributes object
  
  html string
  
  text string
  
  cc string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  from string
  
  priority string
  
  Values are lowest, low, normal, high, or highest.
  
  reply_to string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  sent_date string
  
  subject string Required
  
  to string | array[string] Required
  
  One of:
  string-1 string array-2 array[string]
  
  attachments object
  
  Hide attachments attribute Show attachments attribute object
  
  * object Additional properties
  
  pagerduty object
  
  Hide pagerduty attributes Show pagerduty attributes object
  
  account string
  
  attach_payload boolean Required
  
  client string
  
  client_url string
  
  contexts array[object]
  
  description string Required
  
  event_type string
  
  Values are trigger, resolve, or acknowledge.
  
  incident_key string Required
  
  proxy object
  
  Hide proxy attributes Show proxy attributes object
  
  host string
  
  port number
  
  slack object
  
  Hide slack attributes Show slack attributes object
  
  account string
  
  message object Required
  
  Hide message attributes Show message attributes object
  
  attachments array[object] Required
  
  dynamic_attachments object
  
  Hide dynamic_attachments attributes Show dynamic_attachments attributes object
  
  attachment_template object Required
  
  list_path string Required
  
  from string Required
  
  icon string
  
  text string Required
  
  to array[string] Required
  
  webhook object
  
  Hide webhook attributes Show webhook attributes object
  
  auth object
  
  Hide auth attribute Show auth attribute object
  
  basic object Required
  
  body string
  
  connection_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  headers object
  
  Hide headers attribute Show headers attribute object
  
  * string Additional properties
  
  host string
  
  method string
  
  Values are head, get, post, put, or delete.
  
  params object
  
  Hide params attribute Show params attribute object
  
  * string Additional properties
  
  path string
  
  port number
  
  proxy object
  
  Hide proxy attributes Show proxy attributes object
  
  host string Required
  
  port number Required
  
  read_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  scheme string
  
  Values are http or https.
  
  url string
- condition object Required
  Hide condition attributes Show condition attributes object
  
  always object
  
  array_compare object
  
  Hide array_compare attribute Show array_compare attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  path string Required
  
  compare object
  
  Hide compare attribute Show compare attribute object
  
  * object Additional properties
  
  never object
  
  script object
  
  Hide script attributes Show script attributes object
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from 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 object
  
  track_total_hits 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. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  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.
  
  External documentation
  
  docvalue_fields array[object]
  
  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.
  
  External documentation
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile 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 object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size 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 object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  SourceConfig boolean SourceFilter object
  
  fields array[object]
  
  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 object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  terminate_after 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 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 boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  stats array[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.
  
  id string
- input object Required
  Hide input attributes Show input attributes object
  
  chain object
  
  Hide chain attribute Show chain attribute object
  
  inputs array[object] Required
  
  Hide inputs attribute Show inputs attribute object
  
  * object
  
  http object
  
  Hide http attributes Show http attributes object
  
  extract array[string]
  
  request object
  
  Hide request attributes Show request attributes object
  
  auth object
  
  Hide auth attribute Show auth attribute object
  
  basic object Required
  
  Hide basic attributes Show basic attributes object
  
  password string Required
  
  username string Required
  
  body string
  
  connection_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  headers object
  
  Hide headers attribute Show headers attribute object
  
  * string Additional properties
  
  host string
  
  method string
  
  Values are head, get, post, put, or delete.
  
  params object
  
  Hide params attribute Show params attribute object
  
  * string Additional properties
  
  path string
  
  port number
  
  proxy object
  
  Hide proxy attributes Show proxy attributes object
  
  host string Required
  
  port number Required
  
  read_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  scheme string
  
  Values are http or https.
  
  url string
  
  response_content_type string
  
  Values are json, yaml, or text.
  
  search object
  
  Hide search attributes Show search attributes object
  
  extract array[string]
  
  request object Required
  
  Hide request attributes Show request attributes object
  
  body object
  
  Hide body attribute Show body attribute object
  
  query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  indices array[string]
  
  indices_options object
  
  Hide indices_options attributes Show indices_options attributes object
  
  allow_no_indices 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 string | array[string]
  
  ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
  
  ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
  
  search_type string
  
  Values are query_then_fetch or dfs_query_then_fetch.
  
  template object
  
  Hide template attributes Show template attributes object
  
  explain boolean
  
  id string
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  profile boolean
  
  source 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.
  
  rest_total_hits_as_int boolean
  
  timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  simple object
  
  Hide simple attribute Show simple attribute object
  
  * object Additional properties
- metadata object
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties
- status object
  Hide status attributes Show status attributes object
  
  actions object Required
  
  Hide actions attribute Show actions attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  ack object Required
  
  Hide ack attributes Show ack attributes object
  
  state string Required
  
  Values are awaits_successful_execution, ackable, or acked.
  
  timestamp string
  
  last_execution object
  
  Hide last_execution attributes Show last_execution attributes object
  
  successful boolean Required
  
  timestamp string
  
  reason string
  
  last_successful_execution object
  
  Hide last_successful_execution attributes Show last_successful_execution attributes object
  
  successful boolean Required
  
  timestamp string
  
  reason string
  
  last_throttle object
  
  Hide last_throttle attributes Show last_throttle attributes object
  
  reason string Required
  
  timestamp string
  
  last_checked string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  last_met_condition string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  state object Required
  
  Hide state attributes Show state attributes object
  
  active boolean Required
  
  timestamp string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  version number Required
  
  execution_state string
- throttle_period string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- throttle_period_in_millis number
  
  Time unit for milliseconds
- transform object
  Hide transform attributes Show transform attributes object
  
  chain array[object]
  
  script object
  
  Hide script attributes Show script attributes object
  
  lang string
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from 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 object
  
  track_total_hits 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. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  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.
  
  External documentation
  
  docvalue_fields array[object]
  
  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.
  
  External documentation
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile 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 object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size 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 object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  SourceConfig boolean SourceFilter object
  
  fields array[object]
  
  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 object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  terminate_after 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 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 boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  stats array[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.
  
  id string
  
  search object
  
  Hide search attributes Show search attributes object
  
  request object Required
  
  Hide request attributes Show request attributes object
  
  body object
  
  Hide body attribute Show body attribute object
  
  query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  indices array[string]
  
  indices_options object
  
  Hide indices_options attributes Show indices_options attributes object
  
  allow_no_indices 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 string | array[string]
  
  ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
  
  ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
  
  search_type string
  
  Values are query_then_fetch or dfs_query_then_fetch.
  
  template object
  
  Hide template attributes Show template attributes object
  
  explain boolean
  
  id string
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  profile boolean
  
  source 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.
  
  rest_total_hits_as_int boolean
  
  timeout string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- trigger object Required
  Hide trigger attribute Show trigger attribute object
  
  schedule object
  
  Hide schedule attributes Show schedule attributes object
  
  timezone string
  
  cron string
  
  daily object
  
  Hide daily attribute Show daily attribute object
  
  at array[string | object] Required
  
  A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.
  
  A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.
  
  One of:
  ScheduleTimeOfDay string HourAndMinute object
  
  hourly object
  
  Hide hourly attribute Show hourly attribute object
  
  minute array[number] Required
  
  interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  monthly object | array[object]
  
  One of:
  TimeOfMonth object array-2 array[object]
  
  Hide attributes Show attributes
  
  at array[string] Required
  
  on array[number] Required
  
  weekly object | array[object]
  
  One of:
  TimeOfWeek object array-2 array[object]
  
  Hide attributes Show attributes
  
  at array[string] Required
  
  on array[string] Required
  
  Values are sunday, monday, tuesday, wednesday, thursday, friday, or saturday.
  
  yearly object | array[object]
  
  One of:
  TimeOfYear object array-2 array[object]
  
  Hide attributes Show attributes
  
  at array[string] Required
  
  int array[string] Required
  
  Values are january, february, march, april, may, june, july, august, september, october, november, or december.
  
  on array[number] Required
  
  Hide attributes Show attributes object
  
  at array[string] Required
  
  int array[string] Required
  
  Values are january, february, march, april, may, june, july, august, september, october, november, or december.
  
  on array[number] Required

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- watch_record object Required
  
  Hide watch_record attributes Show watch_record attributes object
  
  condition object Required
  
  Hide condition attributes Show condition attributes object
  
  always object
  
  array_compare object
  
  Hide array_compare attribute Show array_compare attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  path string Required
  
  compare object
  
  Hide compare attribute Show compare attribute object
  
  * object Additional properties
  
  never object
  
  script object
  
  Hide script attributes Show script attributes object
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  params object
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  collapse object
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  from 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
  
  track_total_hits 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. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  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 array[object]
  
  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
  
  rank object
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  profile 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 object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  rescore
  
  retriever object
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size 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 object
  
  sort
  
  _source
  
  fields array[object]
  
  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 object
  
  terminate_after 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 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 boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  stored_fields string | array[string]
  
  pit object
  
  runtime_mappings object
  
  stats array[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.
  
  id string
  
  input object Required
  
  Hide input attributes Show input attributes object
  
  chain object
  
  Hide chain attribute Show chain attribute object
  
  inputs array[object] Required
  
  Hide inputs attribute Show inputs attribute object
  
  * object
  
  http object
  
  Hide http attributes Show http attributes object
  
  extract array[string]
  
  request object
  
  Hide request attributes Show request attributes object
  
  auth object
  
  Hide auth attribute Show auth attribute object
  
  basic object Required
  
  body string
  
  connection_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  headers object
  
  Hide headers attribute Show headers attribute object
  
  * string Additional properties
  
  host string
  
  method string
  
  Values are head, get, post, put, or delete.
  
  params object
  
  Hide params attribute Show params attribute object
  
  * string Additional properties
  
  path string
  
  port number
  
  proxy object
  
  Hide proxy attributes Show proxy attributes object
  
  host string Required
  
  port number Required
  
  read_timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  scheme string
  
  Values are http or https.
  
  url string
  
  response_content_type string
  
  Values are json, yaml, or text.
  
  search object
  
  Hide search attributes Show search attributes object
  
  extract array[string]
  
  request object Required
  
  Hide request attributes Show request attributes object
  
  body object
  
  Hide body attribute Show body attribute object
  
  query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  indices array[string]
  
  indices_options object
  
  Hide indices_options attributes Show indices_options attributes object
  
  allow_no_indices 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 string | array[string]
  
  ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
  
  ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
  
  search_type string
  
  Values are query_then_fetch or dfs_query_then_fetch.
  
  template object
  
  Hide template attributes Show template attributes object
  
  explain boolean
  
  id string
  
  params object
  
  profile boolean
  
  source 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.
  
  rest_total_hits_as_int boolean
  
  timeout string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  simple object
  
  Hide simple attribute Show simple attribute object
  
  * object Additional properties
  
  messages array[string] Required
  
  metadata object
  
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties
  
  node string Required
  
  result object Required
  
  Hide result attributes Show result attributes object
  
  actions array[object] Required
  
  Hide actions attributes Show actions attributes object
  
  email object
  
  Hide email attributes Show email attributes object
  
  account string
  
  message object Required
  
  reason string
  
  id string Required
  
  index object
  
  Hide index attribute Show index attribute object
  
  response object Required
  
  logging object
  
  Hide logging attribute Show logging attribute object
  
  logged_text string Required
  
  pagerduty object
  
  Hide pagerduty attributes Show pagerduty attributes object
  
  event object Required
  
  reason string
  
  request
  
  response object
  
  reason string
  
  slack object
  
  Hide slack attributes Show slack attributes object
  
  account string
  
  message object Required
  
  status string Required
  
  Values are success, failure, simulated, or throttled.
  
  type string Required
  
  Values are email, webhook, index, logging, slack, or pagerduty.
  
  webhook object
  
  Hide webhook attributes Show webhook attributes object
  
  request
  
  response object
  
  error object
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  condition object Required
  
  Hide condition attributes Show condition attributes object
  
  met boolean Required
  
  status string Required
  
  Values are success, failure, simulated, or throttled.
  
  type string Required
  
  Values are always, never, script, compare, or array_compare.
  
  execution_duration number
  
  Time unit for milliseconds
  
  execution_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  input object Required
  
  Hide input attributes Show input attributes object
  
  payload object Required
  
  Hide payload attribute Show payload attribute object
  
  * object Additional properties
  
  status string Required
  
  Values are success, failure, simulated, or throttled.
  
  type string Required
  
  Values are http, search, or simple.
  
  state string Required
  
  Values are awaits_execution, checking, execution_not_needed, throttled, executed, failed, deleted_while_queued, or not_executed_already_queued.
  
  trigger_event object Required
  
  Hide trigger_event attributes Show trigger_event attributes object
  
  manual object Required
  
  Hide manual attribute Show manual attribute object
  
  schedule object
  
  Hide schedule attributes Show schedule attributes object
  
  scheduled_time string
  
  triggered_time string
  
  triggered_time string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  type string Required
  
  user string Required
  
  watch_id string Required
  
  status object
  
  Hide status attributes Show status attributes object
  
  actions object Required
  
  Hide actions attribute Show actions attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  ack object Required
  
  Hide ack attributes Show ack attributes object
  
  state string Required
  
  Values are awaits_successful_execution, ackable, or acked.
  
  timestamp
  
  last_execution object
  
  Hide last_execution attributes Show last_execution attributes object
  
  successful boolean Required
  
  timestamp
  
  reason string
  
  last_successful_execution object
  
  Hide last_successful_execution attributes Show last_successful_execution attributes object
  
  successful boolean Required
  
  timestamp
  
  reason string
  
  last_throttle object
  
  Hide last_throttle attributes Show last_throttle attributes object
  
  reason string Required
  
  timestamp
  
  last_checked string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  last_met_condition string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  state object Required
  
  Hide state attributes Show state attributes object
  
  active boolean Required
  
  timestamp string | number Required
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  version number Required
  
  execution_state string

PUT /_watcher/watch/{id}/_execute

curl \
 --request PUT 'http://api.example.com/_watcher/watch/{id}/_execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"trigger_data\" : { \n    \"triggered_time\" : \"now\",\n    \"scheduled_time\" : \"now\"\n  },\n  \"alternative_input\" : { \n    \"foo\" : \"bar\"\n  },\n  \"ignore_condition\" : true, \n  \"action_modes\" : {\n    \"my-action\" : \"force_simulate\" \n  },\n  \"record_execution\" : true \n}"'

Request examples

Run `POST _watcher/watch/my_watch/_execute` to run a watch. The input defined in the watch is ignored and the `alternative_input` is used as the payload. The condition as defined by the watch is ignored and is assumed to evaluate to true. The `force_simulate` action forces the simulation of `my-action`. Forcing the simulation means that throttling is ignored and the watch is simulated by Watcher instead of being run normally.

{
  "trigger_data" : { 
    "triggered_time" : "now",
    "scheduled_time" : "now"
  },
  "alternative_input" : { 
    "foo" : "bar"
  },
  "ignore_condition" : true, 
  "action_modes" : {
    "my-action" : "force_simulate" 
  },
  "record_execution" : true 
}

Run `POST _watcher/watch/my_watch/_execute` and set a different mode for each action.

{
  "action_modes" : {
    "action1" : "force_simulate",
    "action2" : "skip"
  }
}

Run `POST _watcher/watch/_execute` to run a watch inline. All other settings for this API still apply when inlining a watch. In this example, while the inline watch defines a compare condition, during the execution this condition will be ignored.

{
  "watch" : {
    "trigger" : { "schedule" : { "interval" : "10s" } },
    "input" : {
      "search" : {
        "request" : {
          "indices" : [ "logs" ],
          "body" : {
            "query" : {
              "match" : { "message": "error" }
            }
          }
        }
      }
    },
    "condition" : {
      "compare" : { "ctx.payload.hits.total" : { "gt" : 0 }}
    },
    "actions" : {
      "log_error" : {
        "logging" : {
          "text" : "Found {{ctx.payload.hits.total}} errors in the logs"
        }
      }
    }
  }
}

Response examples (200)

A successful response from `POST _watcher/watch/my_watch/_execute`.

{
  "_id": "my_watch_0-2015-06-02T23:17:55.124Z", 
  "watch_record": { 
    "@timestamp": "2015-06-02T23:17:55.124Z",
    "watch_id": "my_watch",
    "node": "my_node",
    "messages": [],
    "trigger_event": {
      "type": "manual",
      "triggered_time": "2015-06-02T23:17:55.124Z",
      "manual": {
        "schedule": {
          "scheduled_time": "2015-06-02T23:17:55.124Z"
        }
      }
    },
    "state": "executed",
    "status": {
      "version": 1,
      "execution_state": "executed",
      "state": {
        "active": true,
        "timestamp": "2015-06-02T23:17:55.111Z"
      },
      "last_checked": "2015-06-02T23:17:55.124Z",
      "last_met_condition": "2015-06-02T23:17:55.124Z",
      "actions": {
        "test_index": {
          "ack": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "state": "ackable"
          },
          "last_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          },
          "last_successful_execution": {
            "timestamp": "2015-06-02T23:17:55.124Z",
            "successful": true
          }
        }
      }
    },
    "input": {
      "simple": {
        "payload": {
          "send": "yes"
        }
      }
    },
    "condition": {
      "always": {}
    },
    "result": { 
      "execution_time": "2015-06-02T23:17:55.124Z",
      "execution_duration": 12608,
      "input": {
        "type": "simple",
        "payload": {
          "foo": "bar"
        },
        "status": "success"
      },
      "condition": {
        "type": "always",
        "met": true,
        "status": "success"
      },
      "actions": [
        {
          "id": "test_index",
          "index": {
            "response": {
              "index": "test",
              "version": 1,
              "created": true,
              "result": "created",
              "id": "AVSHKzPa9zx62AzUzFXY"
            }
          },
          "status": "success",
          "type": "index"
        }
      ]
    },
    "user": "test_admin" 
  }
}

Start the watch service

POST /_watcher/_start

Api key auth Basic auth Bearer auth

Start the Watcher service if it is not already running.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_watcher/_start

curl \
 --request POST 'http://api.example.com/_watcher/_start' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `POST _watcher/_start`.

{
  "acknowledged": true
}

Get transform information Added in 7.7.0

checkpoint_progress string | null

last_search_time string | null

changes_last_detection_time string | null

Update the connector error field Technical preview

Body Required

error string | null

Update the connector pipeline Beta

Body Required

Get follower information Added in 6.7.0

max_read_request_size number | string

max_write_buffer_size number | string

max_write_request_size number | string

Get data stream stats Added in 7.9.0

store_size number | string

total_store_sizes number | string

Update data streams Added in 7.16.0

Body Required

Delete documents Added in 5.0.0

Body Required

task string | number

Delete a dangling index Added in 7.9.0

Add an index block Added in 7.9.0

Get field usage stats Technical preview

routing_path string | array[string]

order string | array[string]

mode string | array[string]

missing string | array[string]

number_of_shards number | string

number_of_replicas number | string

routing_partition_size number | string

hidden boolean | string

auto_expand_replicas string | null

max_thread_count number | string

max_merge_count number | string

read_only boolean | string

read_only_allow_delete boolean | string

read boolean | string

write boolean | string

metadata boolean | string

max_token_count number | string

indexing_complete boolean | string

prefer_ilm boolean | string

creation_date number | string

creation_date_string string | number

verified_before_close boolean | string

format string | number

flush_threshold_size number | string

size number | string

lenient boolean | string Required

priority number | string

end_time string | number

start_time string | number

limit number | string

ignore_dynamic_beyond_limit boolean | string

ignore_malformed boolean | string

type string Required

routing_path string | array[string]

order string | array[string]

mode string | array[string]

missing string | array[string]

number_of_shards number | string

number_of_replicas number | string

routing_partition_size number | string

hidden boolean | string

auto_expand_replicas string | null

max_thread_count number | string

max_merge_count number | string

read_only boolean | string

read_only_allow_delete boolean | string

read boolean | string

write boolean | string

metadata boolean | string

max_token_count number | string

indexing_complete boolean | string

prefer_ilm boolean | string

creation_date number | string

creation_date_string string | number

verified_before_close boolean | string

format string | number