The API accepts 3 different authentication methods:
Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password
(separated by a : colon).
Example: send a Authorization: Basic aGVsbG86aGVsbG8=
HTTP header with your requests to authenticate with the API.
Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
the name of the autoscaling policy
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.
curl \
--request GET 'http://api.example.com/_autoscaling/policy/{name}' \
--header "Authorization: $API_KEY"{
"roles": <roles>,
"deciders": <deciders>
}NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
the name of the autoscaling policy
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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Decider settings.
curl \
--request PUT 'http://api.example.com/_autoscaling/policy/{name}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"roles\": [],\n \"deciders\": {\n \"fixed\": {\n }\n }\n}"'{
"roles": [],
"deciders": {
"fixed": {
}
}
}{
"roles" : [ "data_hot" ],
"deciders": {
"fixed": {
}
}
}{
"acknowledged": true
}The associated data stream is also deleted.
The name of the analytics collection to be deleted
curl \
--request DELETE 'http://api.example.com/_application/analytics/{name}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
List of columns to appear in the response. Supports simple wildcards.
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.
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.
The period to wait for a connection to the master node.
If the master node is not available before the timeout expires, the request fails and returns an error.
To indicated that the request should never timeout, you can set it to -1.
curl \
--request GET 'http://api.example.com/_cat/aliases' \
--header "Authorization: $API_KEY"[
{
"alias": "alias1",
"index": "test1",
"filter": "-",
"routing.index": "-",
"routing.search": "-",
"is_write_index": "true"
},
{
"alias": "alias1",
"index": "test1",
"filter": "*",
"routing.index": "-",
"routing.search": "-",
"is_write_index": "true"
},
{
"alias": "alias3",
"index": "test1",
"filter": "-",
"routing.index": "1",
"routing.search": "1",
"is_write_index": "true"
},
{
"alias": "alias4",
"index": "test1",
"filter": "-",
"routing.index": "2",
"routing.search": "1,2",
"is_write_index": "true"
}
]Get a snapshot of the number of shards allocated to each data node and their disk space.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
A comma-separated list of node identifiers or names used to limit the returned information.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
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.
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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/allocation/{node_id}' \
--header "Authorization: $API_KEY"[
{
"shards": "1",
"shards.undesired": "0",
"write_load.forecast": "0.0",
"disk.indices.forecast": "260b",
"disk.indices": "260b",
"disk.used": "47.3gb",
"disk.avail": "43.4gb",
"disk.total": "100.7gb",
"disk.percent": "46",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "CSUXak2",
"node.role": "himrst"
}
]Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API.
List of columns to appear in the response. Supports simple wildcards.
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.
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.
The period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/component_templates' \
--header "Authorization: $API_KEY"[
{
"name": "my-template-1",
"version": "null",
"alias_count": "0",
"mapping_count": "0",
"settings_count": "1",
"metadata_count": "0",
"included_in": "[my-index-template]"
},
{
"name": "my-template-2",
"version": null,
"alias_count": "0",
"mapping_count": "3",
"settings_count": "0",
"metadata_count": "0",
"included_in": "[my-index-template]"
}
]Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API.
curl \
--request GET 'http://api.example.com/_cat/count' \
--header "Authorization: $API_KEY"[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "120"
}
][
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "121"
}
]Get configuration and usage information about datafeeds.
This API returns a maximum of 10,000 datafeeds.
If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage
cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API.
A numerical character string that uniquely identifies the datafeed.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.If true, the API returns an empty datafeeds 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.
Comma-separated list of column names to display.
Comma-separated list of column names or column aliases used to sort the response.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/ml/datafeeds/{datafeed_id}' \
--header "Authorization: $API_KEY"[
{
"id": "datafeed-high_sum_total_sales",
"state": "stopped",
"buckets.count": "743",
"search.count": "7"
},
{
"id": "datafeed-low_request_rate",
"state": "stopped",
"buckets.count": "1457",
"search.count": "3"
},
{
"id": "datafeed-response_code_rates",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
},
{
"id": "datafeed-url_scanning",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
}
]Get a list of snapshot repositories for a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot repository API.
List of columns to appear in the response. Supports simple wildcards.
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.
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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/repositories' \
--header "Authorization: $API_KEY"[
{
"id": "repo1",
"type": "fs"
},
{
"id": "repo2",
"type": "s3"
}
]Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
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.
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.
Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/segments' \
--header "Authorization: $API_KEY"[
{
"index": "test",
"shard": "0",
"prirep": "p",
"ip": "127.0.0.1",
"segment": "_0",
"generation": "0",
"docs.count": "1",
"docs.deleted": "0",
"size": "3kb",
"size.memory": "0",
"committed": "false",
"searchable": "true",
"version": "9.12.0",
"compound": "true"
},
{
"index": "test1",
"shard": "0",
"prirep": "p",
"ip": "127.0.0.1",
"segment": "_0",
"generation": "0",
"docs.count": "1",
"docs.deleted": "0",
"size": "3kb",
"size.memory": "0",
"committed": "false",
"searchable": "true",
"version": "9.12.0",
"compound": "true"
}
]Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
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.
Period to wait for a connection to the master node.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/shards' \
--header "Authorization: $API_KEY"[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "RELOCATING",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA -> -> 192.168.56.30 bGG90GE"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "INITIALIZING",
"docs": "0",
"store": "14.3mb",
"dataset": "249b",
"ip": "192.168.56.30",
"node": "bGG90GE"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.10 H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.30 bGG90GE"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.20 I8hydUG"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "UNASSIGNED",
"unassigned.reason": "ALLOCATION_FAILED"
}
]Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
List of columns to appear in the response. Supports simple wildcards.
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.
Period to wait for a connection to the master node.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/snapshots' \
--header "Authorization: $API_KEY"[
{
"id": "snap1",
"repository": "repo1",
"status": "FAILED",
"start_epoch": "1445616705",
"start_time": "18:11:45",
"end_epoch": "1445616978",
"end_time": "18:16:18",
"duration": "4.6m",
"indices": "1",
"successful_shards": "4",
"failed_shards": "1",
"total_shards": "5"
},
{
"id": "snap2",
"repository": "repo1",
"status": "SUCCESS",
"start_epoch": "1445634298",
"start_time": "23:04:58",
"end_epoch": "1445634672",
"end_time": "23:11:12",
"duration": "6.2m",
"indices": "2",
"successful_shards": "10",
"failed_shards": "0",
"total_shards": "10"
}
]Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
A comma-separated list of snapshot repositories used to limit the request.
Accepts wildcard expressions.
_all returns all repositories.
If any repository fails during the request, Elasticsearch returns an error.
List of columns to appear in the response. Supports simple wildcards.
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.
Period to wait for a connection to the master node.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
curl \
--request GET 'http://api.example.com/_cat/snapshots/{repository}' \
--header "Authorization: $API_KEY"[
{
"id": "snap1",
"repository": "repo1",
"status": "FAILED",
"start_epoch": "1445616705",
"start_time": "18:11:45",
"end_epoch": "1445616978",
"end_time": "18:16:18",
"duration": "4.6m",
"indices": "1",
"successful_shards": "4",
"failed_shards": "1",
"total_shards": "5"
},
{
"id": "snap2",
"repository": "repo1",
"status": "SUCCESS",
"start_epoch": "1445634298",
"start_time": "23:04:58",
"end_epoch": "1445634672",
"end_time": "23:11:12",
"duration": "6.2m",
"indices": "2",
"successful_shards": "10",
"failed_shards": "0",
"total_shards": "10"
}
]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.
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.
Skips the specified number of transforms.
Comma-separated list of column names to display.
Comma-separated list of column names or column aliases used to sort the response.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
The maximum number of transforms to obtain.
curl \
--request GET 'http://api.example.com/_cat/transforms' \
--header "Authorization: $API_KEY"[
{
"id" : "ecommerce_transform",
"state" : "started",
"checkpoint" : "1",
"documents_processed" : "705",
"checkpoint_progress" : "100.00",
"changes_last_detection_time" : null
}
]Update the cluster voting config exclusions by node IDs or node names. By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks. If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually. The API adds an entry for each specified node to the cluster’s voting configuration exclusions list. It then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes.
Clusters should have no voting configuration exclusions in normal operation.
Once the excluded nodes have stopped, clear the voting configuration exclusions with DELETE /_cluster/voting_config_exclusions.
This API waits for the nodes to be fully removed from the cluster before it returns.
If your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use DELETE /_cluster/voting_config_exclusions?wait_for_removal=false to clear the voting configuration exclusions without waiting for the nodes to leave the cluster.
A response to POST /_cluster/voting_config_exclusions with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling DELETE /_cluster/voting_config_exclusions.
If the call to POST /_cluster/voting_config_exclusions fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration.
In that case, you may safely retry the call.
NOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period. They are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.
A comma-separated list of the names of the nodes to exclude from the voting configuration. If specified, you may not also specify node_ids.
A comma-separated list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify node_names.
Period to wait for a connection to the master node.
When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error.
curl \
--request POST 'http://api.example.com/_cluster/voting_config_exclusions' \
--header "Authorization: $API_KEY"Configure and update dynamic settings on a running cluster.
You can also configure dynamic settings locally on an unstarted or shut down node in elasticsearch.yml.
Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a null value.
If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) elasticsearch.yml setting; 4) Default setting value.
For example, you can apply a transient setting to override a persistent setting or elasticsearch.yml setting.
However, a change to an elasticsearch.yml setting will not override a defined transient or persistent setting.
TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.
If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.
Only use elasticsearch.yml for static cluster settings and node settings.
The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.
WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.
Return settings in flat format (default: false)
Explicit operation timeout for connection to master node
Explicit operation timeout
curl \
--request PUT 'http://api.example.com/_cluster/settings' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"persistent\" : {\n \"indices.recovery.max_bytes_per_sec\" : \"50mb\"\n }\n}"'{
"persistent" : {
"indices.recovery.max_bytes_per_sec" : "50mb"
}
}{
"persistent": {
"action.auto_create_index": "my-index-000001,index10,-index1*,+ind*"
}
}{
"acknowledged": true,
"persistent": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"transient": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.
The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.
One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.
Whether to expand wildcard expression to concrete indices that are open, closed or both.
Can be one of cluster, indices or shards. Controls the details level of the health information returned.
Values are cluster, indices, or shards.
If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.
Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.
Values are immediate, urgent, high, normal, low, or languid.
The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.
A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.
A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.
One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.
Values are green, GREEN, yellow, YELLOW, red, or RED.
curl \
--request GET 'http://api.example.com/_cluster/health' \
--header "Authorization: $API_KEY"{
"cluster_name" : "testcluster",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 1,
"active_shards" : 1,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 1,
"delayed_unassigned_shards": 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch": 0,
"task_max_waiting_in_queue_millis": 0,
"active_shards_percent_as_number": 50.0
}Manually change the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.
It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as cluster.routing.rebalance.enable) in order to remain in a balanced state.
For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.
The cluster can be set to disable allocations using the cluster.routing.allocation.enable setting.
If allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.
The cluster will attempt to allocate a shard a maximum of index.allocation.max_retries times in a row (defaults to 5), before giving up and leaving the shard unallocated.
This scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.
Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the ?retry_failed URI query parameter, which will attempt a single retry round for these shards.
If true, then the request simulates the operation. It will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes.
If true, then the response contains an explanation of why the commands can or cannot run.
Limits the information returned to the specified metrics.
If true, then retries allocation of shards that are blocked due to too many subsequent allocation failures.
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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request POST 'http://api.example.com/_cluster/reroute' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"commands\": [\n {\n \"move\": {\n \"index\": \"test\", \"shard\": 0,\n \"from_node\": \"node1\", \"to_node\": \"node2\"\n }\n },\n {\n \"allocate_replica\": {\n \"index\": \"test\", \"shard\": 1,\n \"node\": \"node3\"\n }\n }\n ]\n}"'{
"commands": [
{
"move": {
"index": "test", "shard": 0,
"from_node": "node1", "to_node": "node2"
}
},
{
"allocate_replica": {
"index": "test", "shard": 1,
"node": "node3"
}
}
]
}{
"acknowledged": true,
"explanations": [
{
"command": "string",
"decisions": [
{
"decider": "string",
"decision": "string",
"explanation": "string"
}
],
"parameters": {
"allow_primary": true,
"index": "string",
"node": "string",
"shard": 42.0,
"from_node": "string",
"to_node": "string"
}
}
],
"state": {}
}curl \
--request HEAD 'http://api.example.com/' \
--header "Authorization: $API_KEY"Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.
Comma-separated list of node IDs or names used to limit returned information.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/_repositories_metering' \
--header "Authorization: $API_KEY"{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"repository_name": "string",
"repository_type": "string",
"repository_location": {
"base_path": "string",
"container": "string",
"bucket": "string"
},
"repository_ephemeral_id": "string",
"": 42.0,
"archived": true,
"cluster_version": 42.0,
"request_counts": {
"GetBlobProperties": 42.0,
"GetBlob": 42.0,
"ListBlobs": 42.0,
"PutBlob": 42.0,
"PutBlock": 42.0,
"PutBlockList": 42.0,
"GetObject": 42.0,
"ListObjects": 42.0,
"InsertObject": 42.0,
"PutObject": 42.0,
"PutMultipartObject": 42.0
}
},
"additionalProperty2": {
"repository_name": "string",
"repository_type": "string",
"repository_location": {
"base_path": "string",
"container": "string",
"bucket": "string"
},
"repository_ephemeral_id": "string",
"": 42.0,
"archived": true,
"cluster_version": 42.0,
"request_counts": {
"GetBlobProperties": 42.0,
"GetBlob": 42.0,
"ListBlobs": 42.0,
"PutBlob": 42.0,
"PutBlock": 42.0,
"PutBlockList": 42.0,
"GetObject": 42.0,
"ListObjects": 42.0,
"InsertObject": 42.0,
"PutObject": 42.0,
"PutMultipartObject": 42.0
}
}
}
}Get a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of the top hot threads for each node.
List of node IDs or names used to limit returned information.
If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out.
The interval to do the second sampling of threads.
Number of samples of thread stacktrace.
Specifies the number of hot threads to provide information for.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
The type to sample.
Values are cpu, wait, block, gpu, or mem.
The sort order for 'cpu' type (default: total)
Values are cpu, wait, block, gpu, or mem.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/hot_threads' \
--header "Authorization: $API_KEY"{}By default, the API returns all attributes and core settings for cluster nodes.
Comma-separated list of node IDs or names used to limit returned information.
If true, returns settings in flat format.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}' \
--header "Authorization: $API_KEY"{
"_nodes": {},
"cluster_name": "elasticsearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.elastic.co",
"ip": "192.168.17",
"version": "{version}",
"transport_version": 100000298,
"index_version": 100000074,
"component_versions": {
"ml_config_version": 100000162,
"transform_config_version": 100000096
},
"build_flavor": "default",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [
"master",
"data",
"ingest"
],
"attributes": {},
"plugins": [
{
"name": "analysis-icu",
"version": "{version}",
"description": "The ICU Analysis plugin integrates Lucene ICU
module into elasticsearch, adding ICU relates analysis components.",
"classname":
"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
}
],
"modules": [
{
"name": "lang-painless",
"version": "{version}",
"description": "An easy, safe and fast scripting language for
Elasticsearch",
"classname": "org.elasticsearch.painless.PainlessPlugin",
"has_native_controller": false
}
]
}
}
}By default, the API returns all attributes and core settings for cluster nodes.
Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest.
If true, returns settings in flat format.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_nodes/{metric}' \
--header "Authorization: $API_KEY"{
"_nodes": {},
"cluster_name": "elasticsearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.elastic.co",
"ip": "192.168.17",
"version": "{version}",
"transport_version": 100000298,
"index_version": 100000074,
"component_versions": {
"ml_config_version": 100000162,
"transform_config_version": 100000096
},
"build_flavor": "default",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [
"master",
"data",
"ingest"
],
"attributes": {},
"plugins": [
{
"name": "analysis-icu",
"version": "{version}",
"description": "The ICU Analysis plugin integrates Lucene ICU
module into elasticsearch, adding ICU relates analysis components.",
"classname":
"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
}
],
"modules": [
{
"name": "lang-painless",
"version": "{version}",
"description": "An easy, safe and fast scripting language for
Elasticsearch",
"classname": "org.elasticsearch.painless.PainlessPlugin",
"has_native_controller": false
}
]
}
}
}By default, the API returns all attributes and core settings for cluster nodes.
If true, returns settings in flat format.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/{metric}' \
--header "Authorization: $API_KEY"{
"_nodes": {},
"cluster_name": "elasticsearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.elastic.co",
"ip": "192.168.17",
"version": "{version}",
"transport_version": 100000298,
"index_version": 100000074,
"component_versions": {
"ml_config_version": 100000162,
"transform_config_version": 100000096
},
"build_flavor": "default",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [
"master",
"data",
"ingest"
],
"attributes": {},
"plugins": [
{
"name": "analysis-icu",
"version": "{version}",
"description": "The ICU Analysis plugin integrates Lucene ICU
module into elasticsearch, adding ICU relates analysis components.",
"classname":
"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
}
],
"modules": [
{
"name": "lang-painless",
"version": "{version}",
"description": "An easy, safe and fast scripting language for
Elasticsearch",
"classname": "org.elasticsearch.painless.PainlessPlugin",
"has_native_controller": false
}
]
}
}
}Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.
Comma-separated list of node IDs or names used to limit returned information.
Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.
Comma-separated list or wildcard expressions of fields to include in fielddata statistics.
Comma-separated list or wildcard expressions of fields to include in the statistics.
Comma-separated list of search groups to include in the search statistics.
If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).
Indicates whether statistics are aggregated at the cluster, index, or shard level.
Values are cluster, indices, or shards.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
A comma-separated list of document types for the indexing index metric.
If true, the response includes information from segments that are not loaded into memory.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/stats' \
--header "Authorization: $API_KEY"{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"adaptive_selection": {
"additionalProperty1": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
},
"additionalProperty2": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
}
},
"breakers": {
"additionalProperty1": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
},
"additionalProperty2": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
}
},
"fs": {
"data": [
{}
],
"timestamp": 42.0,
"total": {
"available": "string",
"available_in_bytes": 42.0,
"free": "string",
"free_in_bytes": 42.0,
"total": "string",
"total_in_bytes": 42.0
},
"io_stats": {
"devices": [
{}
],
"total": {}
}
},
"host": "string",
"http": {
"current_open": 42.0,
"total_opened": 42.0,
"clients": [
{}
],
"routes": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"ingest": {
"pipelines": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"total": {
"count": 42.0,
"current": 42.0,
"failed": 42.0
}
},
"ip": "string",
"jvm": {
"buffer_pools": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"classes": {
"current_loaded_count": 42.0,
"total_loaded_count": 42.0,
"total_unloaded_count": 42.0
},
"gc": {
"collectors": {}
},
"mem": {
"heap_used_in_bytes": 42.0,
"heap_used_percent": 42.0,
"heap_committed_in_bytes": 42.0,
"heap_max_in_bytes": 42.0,
"non_heap_used_in_bytes": 42.0,
"non_heap_committed_in_bytes": 42.0,
"pools": {}
},
"threads": {
"count": 42.0,
"peak_count": 42.0
},
"timestamp": 42.0,
"uptime": "string",
"uptime_in_millis": 42.0
},
"name": "string",
"os": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"": {},
"swap": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"cgroup": {
"cpuacct": {},
"cpu": {},
"memory": {}
},
"timestamp": 42.0
},
"process": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"mem": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"open_file_descriptors": 42.0,
"max_file_descriptors": 42.0,
"timestamp": 42.0
},
"roles": [
"master"
],
"script": {
"cache_evictions": 42.0,
"compilations": 42.0,
"compilations_history": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"compilation_limit_triggered": 42.0,
"contexts": [
{}
]
},
"script_cache": {},
"thread_pool": {
"additionalProperty1": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
},
"additionalProperty2": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
}
},
"timestamp": 42.0,
"transport": {
"inbound_handling_time_histogram": [
{}
],
"outbound_handling_time_histogram": [
{}
],
"rx_count": 42.0,
"rx_size": "string",
"rx_size_in_bytes": 42.0,
"server_open": 42.0,
"tx_count": 42.0,
"tx_size": "string",
"tx_size_in_bytes": 42.0,
"total_outbound_connections": 42.0
},
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"discovery": {
"cluster_state_queue": {
"total": 42.0,
"pending": 42.0,
"committed": 42.0
},
"published_cluster_states": {
"full_states": 42.0,
"incompatible_diffs": 42.0,
"compatible_diffs": 42.0
},
"cluster_state_update": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"serialized_cluster_states": {
"full_states": {},
"diffs": {}
},
"cluster_applier_stats": {
"recordings": [
{}
]
}
},
"indexing_pressure": {
"memory": {
"limit_in_bytes": 42.0,
"current": {},
"total": {}
}
},
"indices": {
"commit": {
"generation": 42.0,
"id": "string",
"num_docs": 42.0,
"user_data": {}
},
"completion": {
"size_in_bytes": 42.0,
"fields": {}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string"
},
"get": {
"current": 42.0,
"exists_time": "string",
"exists_total": 42.0,
"missing_time": "string",
"missing_total": 42.0,
"time": "string",
"total": 42.0
},
"indexing": {
"index_current": 42.0,
"delete_current": 42.0,
"delete_time": "string",
"delete_total": 42.0,
"is_throttled": true,
"noop_update_total": 42.0,
"throttle_time": "string",
"index_time": "string",
"index_total": 42.0,
"index_failed": 42.0,
"types": {},
"write_load": 42.0,
"recent_write_load": 42.0,
"peak_write_load": 42.0
},
"mappings": {
"total_count": 42.0,
"total_estimated_overhead_in_bytes": 42.0
},
"merges": {
"current": 42.0,
"current_docs": 42.0,
"current_size": "string",
"current_size_in_bytes": 42.0,
"total": 42.0,
"total_auto_throttle": "string",
"total_auto_throttle_in_bytes": 42.0,
"total_docs": 42.0,
"total_size": "string",
"total_size_in_bytes": 42.0,
"total_stopped_time": "string",
"total_throttled_time": "string",
"total_time": "string"
},
"shard_path": {
"data_path": "string",
"is_custom_data_path": true,
"state_path": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"recovery": {
"current_as_source": 42.0,
"current_as_target": 42.0,
"throttle_time": "string"
},
"refresh": {
"external_total": 42.0,
"listeners": 42.0,
"total": 42.0,
"total_time": "string"
},
"request_cache": {
"evictions": 42.0,
"hit_count": 42.0,
"memory_size": "string",
"memory_size_in_bytes": 42.0,
"miss_count": 42.0
},
"retention_leases": {
"primary_term": 42.0,
"version": 42.0,
"leases": [
{}
]
},
"routing": {
"node": "string",
"primary": true,
"state": "UNASSIGNED"
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"fetch_total": 42.0,
"open_contexts": 42.0,
"query_current": 42.0,
"query_time": "string",
"query_total": 42.0,
"scroll_current": 42.0,
"scroll_time": "string",
"scroll_total": 42.0,
"suggest_current": 42.0,
"suggest_time": "string",
"suggest_total": 42.0,
"groups": {}
},
"segments": {
"count": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {},
"fixed_bit_set_memory_in_bytes": 42.0,
"index_writer_max_memory_in_bytes": 42.0,
"index_writer_memory_in_bytes": 42.0,
"max_unsafe_auto_id_timestamp": 42.0,
"memory_in_bytes": 42.0,
"norms_memory_in_bytes": 42.0,
"points_memory_in_bytes": 42.0,
"stored_fields_memory_in_bytes": 42.0,
"terms_memory_in_bytes": 42.0,
"term_vectors_memory_in_bytes": 42.0,
"version_map_memory_in_bytes": 42.0
},
"seq_no": {
"global_checkpoint": 42.0,
"local_checkpoint": 42.0,
"max_seq_no": 42.0
},
"store": {
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"translog": {
"earliest_last_modified_age": 42.0,
"operations": 42.0,
"size": "string",
"size_in_bytes": 42.0,
"uncommitted_operations": 42.0,
"uncommitted_size": "string",
"uncommitted_size_in_bytes": 42.0
},
"warmer": {
"current": 42.0,
"total": 42.0,
"total_time": "string"
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shard_stats": {
"total_count": 42.0
},
"additionalProperty1": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
}
}
},
"additionalProperty2": {
"adaptive_selection": {
"additionalProperty1": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
},
"additionalProperty2": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
}
},
"breakers": {
"additionalProperty1": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
},
"additionalProperty2": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
}
},
"fs": {
"data": [
{}
],
"timestamp": 42.0,
"total": {
"available": "string",
"available_in_bytes": 42.0,
"free": "string",
"free_in_bytes": 42.0,
"total": "string",
"total_in_bytes": 42.0
},
"io_stats": {
"devices": [
{}
],
"total": {}
}
},
"host": "string",
"http": {
"current_open": 42.0,
"total_opened": 42.0,
"clients": [
{}
],
"routes": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"ingest": {
"pipelines": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"total": {
"count": 42.0,
"current": 42.0,
"failed": 42.0
}
},
"ip": "string",
"jvm": {
"buffer_pools": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"classes": {
"current_loaded_count": 42.0,
"total_loaded_count": 42.0,
"total_unloaded_count": 42.0
},
"gc": {
"collectors": {}
},
"mem": {
"heap_used_in_bytes": 42.0,
"heap_used_percent": 42.0,
"heap_committed_in_bytes": 42.0,
"heap_max_in_bytes": 42.0,
"non_heap_used_in_bytes": 42.0,
"non_heap_committed_in_bytes": 42.0,
"pools": {}
},
"threads": {
"count": 42.0,
"peak_count": 42.0
},
"timestamp": 42.0,
"uptime": "string",
"uptime_in_millis": 42.0
},
"name": "string",
"os": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"": {},
"swap": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"cgroup": {
"cpuacct": {},
"cpu": {},
"memory": {}
},
"timestamp": 42.0
},
"process": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"mem": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"open_file_descriptors": 42.0,
"max_file_descriptors": 42.0,
"timestamp": 42.0
},
"roles": [
"master"
],
"script": {
"cache_evictions": 42.0,
"compilations": 42.0,
"compilations_history": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"compilation_limit_triggered": 42.0,
"contexts": [
{}
]
},
"script_cache": {},
"thread_pool": {
"additionalProperty1": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
},
"additionalProperty2": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
}
},
"timestamp": 42.0,
"transport": {
"inbound_handling_time_histogram": [
{}
],
"outbound_handling_time_histogram": [
{}
],
"rx_count": 42.0,
"rx_size": "string",
"rx_size_in_bytes": 42.0,
"server_open": 42.0,
"tx_count": 42.0,
"tx_size": "string",
"tx_size_in_bytes": 42.0,
"total_outbound_connections": 42.0
},
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"discovery": {
"cluster_state_queue": {
"total": 42.0,
"pending": 42.0,
"committed": 42.0
},
"published_cluster_states": {
"full_states": 42.0,
"incompatible_diffs": 42.0,
"compatible_diffs": 42.0
},
"cluster_state_update": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"serialized_cluster_states": {
"full_states": {},
"diffs": {}
},
"cluster_applier_stats": {
"recordings": [
{}
]
}
},
"indexing_pressure": {
"memory": {
"limit_in_bytes": 42.0,
"current": {},
"total": {}
}
},
"indices": {
"commit": {
"generation": 42.0,
"id": "string",
"num_docs": 42.0,
"user_data": {}
},
"completion": {
"size_in_bytes": 42.0,
"fields": {}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string"
},
"get": {
"current": 42.0,
"exists_time": "string",
"exists_total": 42.0,
"missing_time": "string",
"missing_total": 42.0,
"time": "string",
"total": 42.0
},
"indexing": {
"index_current": 42.0,
"delete_current": 42.0,
"delete_time": "string",
"delete_total": 42.0,
"is_throttled": true,
"noop_update_total": 42.0,
"throttle_time": "string",
"index_time": "string",
"index_total": 42.0,
"index_failed": 42.0,
"types": {},
"write_load": 42.0,
"recent_write_load": 42.0,
"peak_write_load": 42.0
},
"mappings": {
"total_count": 42.0,
"total_estimated_overhead_in_bytes": 42.0
},
"merges": {
"current": 42.0,
"current_docs": 42.0,
"current_size": "string",
"current_size_in_bytes": 42.0,
"total": 42.0,
"total_auto_throttle": "string",
"total_auto_throttle_in_bytes": 42.0,
"total_docs": 42.0,
"total_size": "string",
"total_size_in_bytes": 42.0,
"total_stopped_time": "string",
"total_throttled_time": "string",
"total_time": "string"
},
"shard_path": {
"data_path": "string",
"is_custom_data_path": true,
"state_path": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"recovery": {
"current_as_source": 42.0,
"current_as_target": 42.0,
"throttle_time": "string"
},
"refresh": {
"external_total": 42.0,
"listeners": 42.0,
"total": 42.0,
"total_time": "string"
},
"request_cache": {
"evictions": 42.0,
"hit_count": 42.0,
"memory_size": "string",
"memory_size_in_bytes": 42.0,
"miss_count": 42.0
},
"retention_leases": {
"primary_term": 42.0,
"version": 42.0,
"leases": [
{}
]
},
"routing": {
"node": "string",
"primary": true,
"state": "UNASSIGNED"
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"fetch_total": 42.0,
"open_contexts": 42.0,
"query_current": 42.0,
"query_time": "string",
"query_total": 42.0,
"scroll_current": 42.0,
"scroll_time": "string",
"scroll_total": 42.0,
"suggest_current": 42.0,
"suggest_time": "string",
"suggest_total": 42.0,
"groups": {}
},
"segments": {
"count": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {},
"fixed_bit_set_memory_in_bytes": 42.0,
"index_writer_max_memory_in_bytes": 42.0,
"index_writer_memory_in_bytes": 42.0,
"max_unsafe_auto_id_timestamp": 42.0,
"memory_in_bytes": 42.0,
"norms_memory_in_bytes": 42.0,
"points_memory_in_bytes": 42.0,
"stored_fields_memory_in_bytes": 42.0,
"terms_memory_in_bytes": 42.0,
"term_vectors_memory_in_bytes": 42.0,
"version_map_memory_in_bytes": 42.0
},
"seq_no": {
"global_checkpoint": 42.0,
"local_checkpoint": 42.0,
"max_seq_no": 42.0
},
"store": {
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"translog": {
"earliest_last_modified_age": 42.0,
"operations": 42.0,
"size": "string",
"size_in_bytes": 42.0,
"uncommitted_operations": 42.0,
"uncommitted_size": "string",
"uncommitted_size_in_bytes": 42.0
},
"warmer": {
"current": 42.0,
"total": 42.0,
"total_time": "string"
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shard_stats": {
"total_count": 42.0
},
"additionalProperty1": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
}
}
}
}
}A comma-separated list of node IDs or names to limit the returned information; use _local to return information from the node you're connecting to, leave empty to get information from all nodes
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/usage' \
--header "Authorization: $API_KEY"{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"rest_actions": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"": 42.0,
"aggregations": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"rest_actions": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"": 42.0,
"aggregations": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
}
}Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.
Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.
The cluster’s status is controlled by the worst indicator status.
In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.
Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.
NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
curl \
--request GET 'http://api.example.com/_health_report' \
--header "Authorization: $API_KEY"{
"cluster_name": "string",
"indicators": {
"master_is_stable": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"current_master": {},
"recent_masters": [
{}
],
"exception_fetching_history": {
"message": "string",
"stack_trace": "string"
},
"cluster_formation": [
{}
]
}
},
"shards_availability": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"creating_primaries": 42.0,
"creating_replicas": 42.0,
"initializing_primaries": 42.0,
"initializing_replicas": 42.0,
"restarting_primaries": 42.0,
"restarting_replicas": 42.0,
"started_primaries": 42.0,
"started_replicas": 42.0,
"unassigned_primaries": 42.0,
"unassigned_replicas": 42.0
}
},
"disk": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"indices_with_readonly_block": 42.0,
"nodes_with_enough_disk_space": 42.0,
"nodes_over_high_watermark": 42.0,
"nodes_over_flood_stage_watermark": 42.0,
"nodes_with_unknown_disk_status": 42.0
}
},
"repository_integrity": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"total_repositories": 42.0,
"corrupted_repositories": 42.0,
"corrupted": [
"string"
]
}
},
"data_stream_lifecycle": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"stagnating_backing_indices_count": 42.0,
"total_backing_indices_in_error": 42.0,
"stagnating_backing_indices": [
{}
]
}
},
"ilm": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"ilm_status": "RUNNING",
"policies": 42.0,
"stagnating_indices": 42.0
}
},
"slm": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"slm_status": "RUNNING",
"policies": 42.0,
"unhealthy_policies": {
"count": 42.0,
"invocations_since_last_success": {}
}
}
},
"shards_capacity": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"data": {
"max_shards_in_cluster": 42.0,
"current_used_shards": 42.0
},
"frozen": {
"max_shards_in_cluster": 42.0,
"current_used_shards": 42.0
}
}
},
"file_settings": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"failure_streak": 42.0,
"most_recent_failure": "string"
}
}
},
"status": "green"
}Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.
Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.
The cluster’s status is controlled by the worst indicator status.
In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.
Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.
NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.
A feature of the cluster, as returned by the top-level health report API.
curl \
--request GET 'http://api.example.com/_health_report/{feature}' \
--header "Authorization: $API_KEY"{
"cluster_name": "string",
"indicators": {
"master_is_stable": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"current_master": {},
"recent_masters": [
{}
],
"exception_fetching_history": {
"message": "string",
"stack_trace": "string"
},
"cluster_formation": [
{}
]
}
},
"shards_availability": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"creating_primaries": 42.0,
"creating_replicas": 42.0,
"initializing_primaries": 42.0,
"initializing_replicas": 42.0,
"restarting_primaries": 42.0,
"restarting_replicas": 42.0,
"started_primaries": 42.0,
"started_replicas": 42.0,
"unassigned_primaries": 42.0,
"unassigned_replicas": 42.0
}
},
"disk": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"indices_with_readonly_block": 42.0,
"nodes_with_enough_disk_space": 42.0,
"nodes_over_high_watermark": 42.0,
"nodes_over_flood_stage_watermark": 42.0,
"nodes_with_unknown_disk_status": 42.0
}
},
"repository_integrity": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"total_repositories": 42.0,
"corrupted_repositories": 42.0,
"corrupted": [
"string"
]
}
},
"data_stream_lifecycle": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"stagnating_backing_indices_count": 42.0,
"total_backing_indices_in_error": 42.0,
"stagnating_backing_indices": [
{}
]
}
},
"ilm": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"ilm_status": "RUNNING",
"policies": 42.0,
"stagnating_indices": 42.0
}
},
"slm": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"slm_status": "RUNNING",
"policies": 42.0,
"unhealthy_policies": {
"count": 42.0,
"invocations_since_last_success": {}
}
}
},
"shards_capacity": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"data": {
"max_shards_in_cluster": 42.0,
"current_used_shards": 42.0
},
"frozen": {
"max_shards_in_cluster": 42.0,
"current_used_shards": 42.0
}
}
},
"file_settings": {
"status": "green",
"symptom": "string",
"impacts": [
{
"description": "string",
"id": "string",
"impact_areas": [
"search"
],
"severity": 42.0
}
],
"diagnosis": [
{
"id": "string",
"action": "string",
"affected_resources": {},
"cause": "string",
"help_url": "string"
}
],
"details": {
"failure_streak": 42.0,
"most_recent_failure": "string"
}
}
},
"status": "green"
}Update the last_seen field in the connector and set it to the current timestamp.
The unique identifier of the connector to be checked in
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_check_in' \
--header "Authorization: $API_KEY"{
"result": "updated"
}The unique identifier of the connector
A flag to indicate if the desired connector should be fetched, even if it was soft-deleted.
curl \
--request GET 'http://api.example.com/_connector/{connector_id}' \
--header "Authorization: $API_KEY"{
"api_key_id": "string",
"api_key_secret_id": "string",
"configuration": {
"additionalProperty1": {
"category": "string",
"": 42.0,
"depends_on": [
{
"field": "string",
"": 42.0
}
],
"display": "textbox",
"label": "string",
"options": [
{
"label": "string",
"": 42.0
}
],
"order": 42.0,
"placeholder": "string",
"required": true,
"sensitive": true,
"tooltip": "string",
"type": "str",
"ui_restrictions": [
"string"
],
"validations": [
{
"type": "less_than",
"constraint": 42.0
}
],
"value": {}
},
"additionalProperty2": {
"category": "string",
"": 42.0,
"depends_on": [
{
"field": "string",
"": 42.0
}
],
"display": "textbox",
"label": "string",
"options": [
{
"label": "string",
"": 42.0
}
],
"order": 42.0,
"placeholder": "string",
"required": true,
"sensitive": true,
"tooltip": "string",
"type": "str",
"ui_restrictions": [
"string"
],
"validations": [
{
"type": "less_than",
"constraint": 42.0
}
],
"value": {}
}
},
"custom_scheduling": {
"additionalProperty1": {
"configuration_overrides": {
"max_crawl_depth": 42.0,
"sitemap_discovery_disabled": true,
"domain_allowlist": [
"string"
],
"sitemap_urls": [
"string"
],
"seed_urls": [
"string"
]
},
"enabled": true,
"interval": "string",
"": "string",
"name": "string"
},
"additionalProperty2": {
"configuration_overrides": {
"max_crawl_depth": 42.0,
"sitemap_discovery_disabled": true,
"domain_allowlist": [
"string"
],
"sitemap_urls": [
"string"
],
"seed_urls": [
"string"
]
},
"enabled": true,
"interval": "string",
"": "string",
"name": "string"
}
},
"deleted": true,
"description": "string",
"error": "string",
"features": {
"document_level_security": {
"enabled": true
},
"incremental_sync": {
"enabled": true
},
"native_connector_api_keys": {
"enabled": true
},
"sync_rules": {
"advanced": {
"enabled": true
},
"basic": {
"enabled": true
}
}
},
"filtering": [
{
"active": {
"advanced_snippet": {
"": "string",
"value": {}
},
"rules": [
{
"field": "string",
"id": "string",
"order": 42.0,
"policy": "exclude",
"rule": "contains",
"value": "string"
}
],
"validation": {
"errors": [
{}
],
"state": "edited"
}
},
"domain": "string",
"draft": {
"advanced_snippet": {
"": "string",
"value": {}
},
"rules": [
{
"field": "string",
"id": "string",
"order": 42.0,
"policy": "exclude",
"rule": "contains",
"value": "string"
}
],
"validation": {
"errors": [
{}
],
"state": "edited"
}
}
}
],
"id": "string",
"index_name": "string",
"is_native": true,
"language": "string",
"last_access_control_sync_error": "string",
"": "string",
"last_access_control_sync_status": "canceling",
"last_deleted_document_count": 42.0,
"last_indexed_document_count": 42.0,
"last_sync_error": "string",
"last_sync_status": "canceling",
"name": "string",
"pipeline": {
"extract_binary_content": true,
"name": "string",
"reduce_whitespace": true,
"run_ml_inference": true
},
"scheduling": {
"access_control": {
"enabled": true,
"interval": "string"
},
"full": {
"enabled": true,
"interval": "string"
},
"incremental": {
"enabled": true,
"interval": "string"
}
},
"service_type": "string",
"status": "created",
"sync_cursor": {},
"sync_now": true
}The unique identifier of the connector to be created or updated. ID is auto-generated if not provided.
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"index_name\": \"search-google-drive\",\n \"name\": \"My Connector\",\n \"service_type\": \"google_drive\"\n}"'{
"index_name": "search-google-drive",
"name": "My Connector",
"service_type": "google_drive"
}{
"index_name": "search-google-drive",
"name": "My Connector",
"description": "My Connector to sync data to Elastic index from Google Drive",
"service_type": "google_drive",
"language": "english"
}{
"result": "created",
"id": "my-connector"
}The unique identifier of the connector sync job
curl \
--request GET 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}' \
--header "Authorization: $API_KEY"{
"": "string",
"connector": {
"configuration": {
"additionalProperty1": {
"category": "string",
"": 42.0,
"depends_on": [
{
"field": "string"
}
],
"display": "textbox",
"label": "string",
"options": [
{
"label": "string"
}
],
"order": 42.0,
"placeholder": "string",
"required": true,
"sensitive": true,
"tooltip": "string",
"type": "str",
"ui_restrictions": [
"string"
],
"validations": [
{}
],
"value": {}
},
"additionalProperty2": {
"category": "string",
"": 42.0,
"depends_on": [
{
"field": "string"
}
],
"display": "textbox",
"label": "string",
"options": [
{
"label": "string"
}
],
"order": 42.0,
"placeholder": "string",
"required": true,
"sensitive": true,
"tooltip": "string",
"type": "str",
"ui_restrictions": [
"string"
],
"validations": [
{}
],
"value": {}
}
},
"filtering": {
"advanced_snippet": {
"": "string",
"value": {}
},
"rules": [
{
"": "string",
"field": "string",
"id": "string",
"order": 42.0,
"policy": "exclude",
"rule": "contains",
"value": "string"
}
],
"validation": {
"errors": [
{
"ids": [
"string"
],
"messages": [
"string"
]
}
],
"state": "edited"
}
},
"id": "string",
"index_name": "string",
"language": "string",
"pipeline": {
"extract_binary_content": true,
"name": "string",
"reduce_whitespace": true,
"run_ml_inference": true
},
"service_type": "string",
"sync_cursor": {}
},
"deleted_document_count": 42.0,
"error": "string",
"id": "string",
"indexed_document_count": 42.0,
"indexed_document_volume": 42.0,
"job_type": "full",
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"status": "canceling",
"total_document_count": 42.0,
"trigger_method": "on_demand",
"worker_hostname": "string"
}Update the api_key_id and api_key_secret_id fields of a connector.
You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored.
The connector secret ID is required only for Elastic managed (native) connectors.
Self-managed connectors (connector clients) do not use this field.
The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_api_key_id' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"api_key_id\": \"my-api-key-id\",\n \"api_key_secret_id\": \"my-connector-secret-id\"\n}"'{
"api_key_id": "my-api-key-id",
"api_key_secret_id": "my-connector-secret-id"
}{
"result": "updated"
}Update the connector features in the connector document. This API can be used to control the following aspects of a connector:
Normally, the running connector service automatically manages these features. However, you can use this API to override the default behavior.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
The unique identifier of the connector to be updated.
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_features' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"features\": {\n \"document_level_security\": {\n \"enabled\": true\n },\n \"incremental_sync\": {\n \"enabled\": true\n },\n \"sync_rules\": {\n \"advanced\": {\n \"enabled\": false\n },\n \"basic\": {\n \"enabled\": true\n }\n }\n }\n}"'{
"features": {
"document_level_security": {
"enabled": true
},
"incremental_sync": {
"enabled": true
},
"sync_rules": {
"advanced": {
"enabled": false
},
"basic": {
"enabled": true
}
}
}
}{
"features": {
"document_level_security": {
"enabled": true
}
}
}{
"result": "updated"
}Update the draft filtering configuration of a connector and marks the draft validation state as edited. The filtering draft is activated once validated by the running Elastic connector service. The filtering property is used to configure sync rules (both basic and advanced) for a connector.
The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"rules\": [\n {\n \"field\": \"file_extension\",\n \"id\": \"exclude-txt-files\",\n \"order\": 0,\n \"policy\": \"exclude\",\n \"rule\": \"equals\",\n \"value\": \"txt\"\n },\n {\n \"field\": \"_\",\n \"id\": \"DEFAULT\",\n \"order\": 1,\n \"policy\": \"include\",\n \"rule\": \"regex\",\n \"value\": \".*\"\n }\n ]\n}"'{
"rules": [
{
"field": "file_extension",
"id": "exclude-txt-files",
"order": 0,
"policy": "exclude",
"rule": "equals",
"value": "txt"
},
{
"field": "_",
"id": "DEFAULT",
"order": 1,
"policy": "include",
"rule": "regex",
"value": ".*"
}
]
}{
"advanced_snippet": {
"value": [{
"tables": [
"users",
"orders"
],
"query": "SELECT users.id AS id, orders.order_id AS order_id FROM users JOIN orders ON users.id = orders.user_id"
}]
}
}{
"result": "updated"
}When you create a new connector, the configuration of an ingest pipeline is populated with default settings.
The unique identifier of the connector to be updated
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}"'{
"pipeline": {
"extract_binary_content": true,
"name": "my-connector-pipeline",
"reduce_whitespace": true,
"run_ml_inference": true
}
}{
"result": "updated"
}Create a cross-cluster replication follower index that follows a specific leader index. When the API returns, the follower index exists and cross-cluster replication starts replicating operations from the leader index to the follower index.
The name of the follower index.
Period to wait for a connection to the master node.
Specifies the number of shards to wait on being active before responding. This defaults to waiting on none of the shards to be active. A shard must be restored from the leader index before being active. Restoring a follower shard requires transferring all the remote Lucene segment files to the follower index.
If the leader index is part of a data stream, the name to which the local data stream for the followed index should be renamed.
The maximum number of outstanding reads requests from the remote cluster.
The maximum number of outstanding write requests on the follower.
The maximum number of operations to pull per read from the remote cluster.
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.
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.
The maximum number of operations per bulk write request executed on the follower.
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.
The remote cluster containing the leader index.
curl \
--request PUT 'http://api.example.com/{index}/_ccr/follow' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"remote_cluster\" : \"remote_cluster\",\n \"leader_index\" : \"leader_index\",\n \"settings\": {\n \"index.number_of_replicas\": 0\n },\n \"max_read_request_operation_count\" : 1024,\n \"max_outstanding_read_requests\" : 16,\n \"max_read_request_size\" : \"1024k\",\n \"max_write_request_operation_count\" : 32768,\n \"max_write_request_size\" : \"16k\",\n \"max_outstanding_write_requests\" : 8,\n \"max_write_buffer_count\" : 512,\n \"max_write_buffer_size\" : \"512k\",\n \"max_retry_delay\" : \"10s\",\n \"read_poll_timeout\" : \"30s\"\n}"'{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}{
"follow_index_created" : true,
"follow_index_shards_acked" : true,
"index_following_started" : true
}Get cross-cluster replication follower stats. The API returns shard-level stats about the "following tasks" associated with each shard for the specified indices.
A comma-delimited list of index patterns.
The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/{index}/_ccr/stats' \
--header "Authorization: $API_KEY"{
"indices" : [
{
"index" : "follower_index",
"total_global_checkpoint_lag" : 256,
"shards" : [
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"follower_index" : "follower_index",
"shard_id" : 0,
"leader_global_checkpoint" : 1024,
"leader_max_seq_no" : 1536,
"follower_global_checkpoint" : 768,
"follower_max_seq_no" : 896,
"last_requested_seq_no" : 897,
"outstanding_read_requests" : 8,
"outstanding_write_requests" : 2,
"write_buffer_operation_count" : 64,
"follower_mapping_version" : 4,
"follower_settings_version" : 2,
"follower_aliases_version" : 8,
"total_read_time_millis" : 32768,
"total_read_remote_exec_time_millis" : 16384,
"successful_read_requests" : 32,
"failed_read_requests" : 0,
"operations_read" : 896,
"bytes_read" : 32768,
"total_write_time_millis" : 16384,
"write_buffer_size_in_bytes" : 1536,
"successful_write_requests" : 16,
"failed_write_requests" : 0,
"operations_written" : 832,
"read_exceptions" : [ ],
"time_since_last_read_millis" : 8
}
]
}
]
}Get cross-cluster replication auto-follow patterns.
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.
curl \
--request GET 'http://api.example.com/_ccr/auto_follow' \
--header "Authorization: $API_KEY"{
"patterns": [
{
"name": "my_auto_follow_pattern",
"pattern": {
"active": true,
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"leader_index_exclusion_patterns":
[
"leader_index_001"
],
"follow_index_pattern" : "{{leader_index}}-follower"
}
}
]
}Resume a cross-cluster replication auto-follow pattern that was paused. The auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster. Remote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.
The name of the auto-follow pattern to resume.
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.
curl \
--request POST 'http://api.example.com/_ccr/auto_follow/{name}/resume' \
--header "Authorization: $API_KEY"{
"acknowledged" : true
}This API returns stats about auto-following and the same shard-level stats as the get follower stats API.
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.
The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_ccr/stats' \
--header "Authorization: $API_KEY"{
"auto_follow_stats" : {
"number_of_failed_follow_indices" : 0,
"number_of_failed_remote_cluster_state_requests" : 0,
"number_of_successful_follow_indices" : 1,
"recent_auto_follow_errors" : [],
"auto_followed_clusters" : []
},
"follow_stats" : {
"indices" : [
{
"index" : "follower_index",
"total_global_checkpoint_lag" : 256,
"shards" : [
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"follower_index" : "follower_index",
"shard_id" : 0,
"leader_global_checkpoint" : 1024,
"leader_max_seq_no" : 1536,
"follower_global_checkpoint" : 768,
"follower_max_seq_no" : 896,
"last_requested_seq_no" : 897,
"outstanding_read_requests" : 8,
"outstanding_write_requests" : 2,
"write_buffer_operation_count" : 64,
"follower_mapping_version" : 4,
"follower_settings_version" : 2,
"follower_aliases_version" : 8,
"total_read_time_millis" : 32768,
"total_read_remote_exec_time_millis" : 16384,
"successful_read_requests" : 32,
"failed_read_requests" : 0,
"operations_read" : 896,
"bytes_read" : 32768,
"total_write_time_millis" : 16384,
"write_buffer_size_in_bytes" : 1536,
"successful_write_requests" : 16,
"failed_write_requests" : 0,
"operations_written" : 832,
"read_exceptions" : [ ],
"time_since_last_read_millis" : 8
}
]
}
]
}
}Deletes one or more data streams and their backing indices.
Comma-separated list of data streams to delete. Wildcard (*) expressions are supported.
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.
Type of data stream that wildcard patterns can match. Supports comma-separated values,such as open,hidden.
curl \
--request DELETE 'http://api.example.com/_data_stream/{name}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.
The name of the index to explain
indicates if the API should return the default values the system uses for the index's lifecycle
Specify timeout for connection to master
curl \
--request GET 'http://api.example.com/{index}/_lifecycle/explain' \
--header "Authorization: $API_KEY"{
"indices": {
".ds-metrics-2023.03.22-000001": {
"index" : ".ds-metrics-2023.03.22-000001",
"managed_by_lifecycle" : true,
"index_creation_date_millis" : 1679475563571,
"time_since_index_creation" : "843ms",
"rollover_date_millis" : 1679475564293,
"time_since_rollover" : "121ms",
"lifecycle" : { },
"generation_time" : "121ms"
}
}{
"indices": {
".ds-metrics-2023.03.22-000001": {
"index" : ".ds-metrics-2023.03.22-000001",
"managed_by_lifecycle" : true,
"index_creation_date_millis" : 1679475563571,
"time_since_index_creation" : "843ms",
"lifecycle" : {
"enabled": true
},
"error": "{\"type\":\"validation_exception\",\"reason\":\"Validation Failed: 1: this action would add [2] shards, but this cluster
currently has [4]/[3] maximum normal shards open;\"}"
}
}Performs one or more data stream modification actions in a single atomic operation.
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"}}]}'{
"actions": [
{
"add_backing_index": {
"data_stream": "string",
"index": "string"
},
"remove_backing_index": {
"data_stream": "string",
"index": "string"
}
}
]
}{
"acknowledged": true
}Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.
With CCR auto following, a data stream from a remote cluster can be replicated to the local cluster. These data streams can't be rolled over in the local cluster. These replicated data streams roll over only if the upstream data stream rolls over. In the event that the remote cluster is no longer available, the data stream in the local cluster can be promoted to a regular data stream, which allows these data streams to be rolled over in the local cluster.
NOTE: When promoting a data stream, ensure the local cluster has a data stream enabled index template that matches the data stream. If this is missing, the data stream will not be able to roll over until a matching index template is created. This will affect the lifecycle management of the data stream and interfere with the data stream size and retention.
The name of the data stream
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.
curl \
--request POST 'http://api.example.com/_data_stream/_promote/{name}' \
--header "Authorization: $API_KEY"{}Perform multiple index, create, delete, and update actions in a single request.
This reduces overhead and can greatly increase indexing speed.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
create action, you must have the create_doc, create, index, or write index privilege. Data streams support only the create action.index action, you must have the create, index, or write index privilege.delete action, you must have the delete or write index privilege.update action, you must have the index or write index privilege.auto_configure, create_index, or manage index privilege.refresh parameter, you must have the maintenance or manage index privilege.Automatic data stream creation requires a matching index template with data stream enabled.
The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:
action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n
The index and create actions expect a source on the next line and have the same semantics as the op_type parameter in the standard index API.
A create action fails if a document with the same ID already exists in the target
An index action adds or replaces a document as necessary.
NOTE: Data streams support only the create action.
To update or delete a document in a data stream, you must target the backing index containing the document.
An update action expects that the partial doc, upsert, and script and its options are specified on the next line.
A delete action does not expect a source on the next line and has the same semantics as the standard delete API.
NOTE: The final line of data must end with a newline character (\n).
Each newline character may be preceded by a carriage return (\r).
When sending NDJSON data to the _bulk endpoint, use a Content-Type header of application/json or application/x-ndjson.
Because this format uses literal newline characters (\n) as delimiters, make sure that the JSON actions and sources are not pretty printed.
If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index argument.
A note on the format: the idea here is to make processing as fast as possible.
As some of the actions are redirected to other shards on other nodes, only action_meta_data is parsed on the receiving node side.
Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.
There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.
Client suppport for bulk requests
Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:
esutil.BulkIndexerSearch::Elasticsearch::Client::5_0::Bulk and Search::Elasticsearch::Client::5_0::Scrollelasticsearch.helpers.*client.helpers.*BulkAllObservableSubmitting bulk requests with cURL
If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d.
The latter doesn't preserve newlines. For example:
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
Optimistic concurrency control
Each index and delete action within a bulk API call may include the if_seq_no and if_primary_term parameters in their respective action and meta data lines.
The if_seq_no and if_primary_term parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.
Versioning
Each bulk item can include the version value using the version field.
It automatically follows the behavior of the index or delete operation based on the _version mapping.
It also support the version_type.
Routing
Each bulk item can include the routing value using the routing field.
It automatically follows the behavior of the index or delete operation based on the _routing mapping.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.
Wait for active shards
When making bulk calls, you can set the wait_for_active_shards parameter to require a minimum number of shard copies to be active before starting to process the bulk request.
Refresh
Control when the changes made by this request are visible to search.
NOTE: Only the shards that receive the bulk request will be affected by refresh.
Imagine a _bulk?refresh=wait_for request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the _bulk request at all.
The name of the data stream, index, or index alias to perform bulk actions on.
True or false if to include the document source in the error message in case of parsing errors.
If true, the response will include the ingest pipelines that were run for each index or create.
The pipeline identifier to use to preprocess incoming documents.
If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request.
If a final pipeline is configured, it will always run regardless of the value of this parameter.
If true, Elasticsearch refreshes the affected shards to make this operation visible to search.
If wait_for, wait for a refresh to make this operation visible to search.
If false, do nothing with refreshes.
Valid values: true, false, wait_for.
Values are true, false, or wait_for.
A custom value that is used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or contains a list of fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned.
You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards.
The default is 1m (one minute), which guarantees Elasticsearch waits for at least the timeout before failing.
The actual wait time could be longer, particularly when multiple waits occur.
The number of shard copies that must be active before proceeding with the operation.
Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default is 1, which waits for each primary shard to be active.
If true, the request's actions must target an index alias.
If true, the request's actions must target a data stream (existing or to be created).
curl \
--request PUT 'http://api.example.com/{index}/_bulk' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{ \"index\" : { \"_index\" : \"test\", \"_id\" : \"1\" } }\n{ \"field1\" : \"value1\" }\n{ \"delete\" : { \"_index\" : \"test\", \"_id\" : \"2\" } }\n{ \"create\" : { \"_index\" : \"test\", \"_id\" : \"3\" } }\n{ \"field1\" : \"value3\" }\n{ \"update\" : {\"_id\" : \"1\", \"_index\" : \"test\"} }\n{ \"doc\" : {\"field2\" : \"value2\"} }"'{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}{
"took": 30,
"errors": false,
"items": [
{
"index": {
"_index": "test",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 201,
"_seq_no" : 0,
"_primary_term": 1
}
},
{
"delete": {
"_index": "test",
"_id": "2",
"_version": 1,
"result": "not_found",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 404,
"_seq_no" : 1,
"_primary_term" : 2
}
},
{
"create": {
"_index": "test",
"_id": "3",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 201,
"_seq_no" : 2,
"_primary_term" : 3
}
},
{
"update": {
"_index": "test",
"_id": "1",
"_version": 2,
"result": "updated",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 200,
"_seq_no" : 3,
"_primary_term" : 4
}
}
]
}{
"took": 486,
"errors": true,
"items": [
{
"update": {
"_index": "index1",
"_id": "5",
"status": 404,
"error": {
"type": "document_missing_exception",
"reason": "[5]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"update": {
"_index": "index1",
"_id": "6",
"status": 404,
"error": {
"type": "document_missing_exception",
"reason": "[6]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"create": {
"_index": "index1",
"_id": "7",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 201
}
}
]
}{
"items": [
{
"update": {
"error": {
"type": "document_missing_exception",
"reason": "[5]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"update": {
"error": {
"type": "document_missing_exception",
"reason": "[6]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
}
]
}Get a document and its source or stored fields from an index.
By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search).
In the case where stored fields are requested with the stored_fields parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields.
To turn off realtime behavior, set the realtime parameter to false.
Source filtering
By default, the API returns the contents of the _source field unless you have used the stored_fields parameter or the _source field is turned off.
You can turn off _source retrieval by using the _source parameter:
GET my-index-000001/_doc/0?_source=false
If you only need one or two fields from the _source, use the _source_includes or _source_excludes parameters to include or filter out particular fields.
This can be helpful with large documents where partial retrieval can save on network overhead
Both parameters take a comma separated list of fields or wildcard expressions.
For example:
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
If you only want to specify includes, you can use a shorter notation:
GET my-index-000001/_doc/0?_source=*.id
Routing
If routing is used during indexing, the routing value also needs to be specified to retrieve a document. For example:
GET my-index-000001/_doc/2?routing=user1
This request gets the document with ID 2, but it is routed based on the user. The document is not fetched if the correct routing is not specified.
Distributed
The GET operation is hashed into a specific shard ID. It is then redirected to one of the replicas within that shard ID and returns the result. The replicas are the primary shard and its replicas within that shard ID group. This means that the more replicas you have, the better your GET scaling will be.
Versioning support
You can use the version parameter to retrieve the document only if its current version is equal to the specified one.
Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. The old version of the document doesn't disappear immediately, although you won't be able to access it. Elasticsearch cleans up deleted documents in the background as you continue to index more data.
Indicates whether the request forces synthetic _source.
Use this paramater to test if the mapping supports synthetic _source and to get a sense of the worst case performance.
Fetches with this parameter enabled will be slower than enabling synthetic source natively in the index.
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If it is set to _local, the operation will prefer to be run on a local allocated shard when possible.
If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.
This can help with "jumping values" when hitting different shards in different refresh states.
A sample value can be something like the web session ID or the user name.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned.
You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of stored fields to return as part of a hit.
If no fields are specified, no stored fields are included in the response.
If this field is specified, the _source parameter defaults to false.
Only leaf fields can be retrieved with the stored_field option.
Object fields can't be returned;if specified, the request fails.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Values are internal, external, external_gte, or force.
curl \
--request GET 'http://api.example.com/{index}/_doc/{id}' \
--header "Authorization: $API_KEY"{
"_index": "my-index-000001",
"_id": "0",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"found": true,
"_source": {
"@timestamp": "2099-11-15T14:12:12",
"http": {
"request": {
"method": "get"
},
"response": {
"status_code": 200,
"bytes": 1070000
},
"version": "1.1"
},
"source": {
"ip": "127.0.0.1"
},
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"_seq_no" : 22,
"_primary_term" : 1,
"found": true,
"fields": {
"tags": [
"production"
]
}
}{
"_index": "my-index-000001",
"_id": "2",
"_version": 1,
"_seq_no" : 13,
"_primary_term" : 1,
"_routing": "user1",
"found": true,
"fields": {
"tags": [
"env2"
]
}
}Check whether a document source exists in an index. For example:
HEAD my-index-000001/_source/1
A document's source is not available if it is disabled in the mapping.
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Values are internal, external, external_gte, or force.
curl \
--request HEAD 'http://api.example.com/{index}/_source/{id}' \
--header "Authorization: $API_KEY"Get multiple JSON documents by ID from one or more indices. If you specify an index in the request URI, you only need to specify the document IDs in the request body. To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.
Filter source fields
By default, the _source field is returned for every document (if stored).
Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document.
You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.
Get stored fields
Use the stored_fields attribute to specify the set of stored fields you want to retrieve.
Any requested fields that are not stored are ignored.
You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.
Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.
Specifies the node or shard the operation should be performed on. Random by default.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes relevant shards before retrieving documents.
Custom value used to route operations to a specific shard.
True or false to return the _source field or not, or a list of fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
If true, retrieves the document fields stored in the index rather than the document _source.
curl \
--request GET 'http://api.example.com/_mget' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"docs\": [\n {\n \"_id\": \"1\"\n },\n {\n \"_id\": \"2\"\n }\n ]\n}"'{
"docs": [
{
"_id": "1"
},
{
"_id": "2"
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"_source": false
},
{
"_index": "test",
"_id": "2",
"_source": [ "field3", "field4" ]
},
{
"_index": "test",
"_id": "3",
"_source": {
"include": [ "user" ],
"exclude": [ "user.location" ]
}
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"stored_fields": [ "field1", "field2" ]
},
{
"_index": "test",
"_id": "2",
"stored_fields": [ "field3", "field4" ]
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"routing": "key2"
},
{
"_index": "test",
"_id": "2"
}
]
}{
"docs": [
{
"_index": "string",
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"_ignored": [
"string"
],
"found": true,
"_id": "string",
"_primary_term": 42.0,
"_routing": "string",
"_seq_no": 42.0,
"_source": {},
"_version": 42.0
}
]
}Get multiple JSON documents by ID from one or more indices. If you specify an index in the request URI, you only need to specify the document IDs in the request body. To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.
Filter source fields
By default, the _source field is returned for every document (if stored).
Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document.
You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.
Get stored fields
Use the stored_fields attribute to specify the set of stored fields you want to retrieve.
Any requested fields that are not stored are ignored.
You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.
Name of the index to retrieve documents from when ids are specified, or when a document in the docs array does not specify an index.
Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.
Specifies the node or shard the operation should be performed on. Random by default.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes relevant shards before retrieving documents.
Custom value used to route operations to a specific shard.
True or false to return the _source field or not, or a list of fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
If true, retrieves the document fields stored in the index rather than the document _source.
curl \
--request POST 'http://api.example.com/{index}/_mget' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"docs\": [\n {\n \"_id\": \"1\"\n },\n {\n \"_id\": \"2\"\n }\n ]\n}"'{
"docs": [
{
"_id": "1"
},
{
"_id": "2"
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"_source": false
},
{
"_index": "test",
"_id": "2",
"_source": [ "field3", "field4" ]
},
{
"_index": "test",
"_id": "3",
"_source": {
"include": [ "user" ],
"exclude": [ "user.location" ]
}
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"stored_fields": [ "field1", "field2" ]
},
{
"_index": "test",
"_id": "2",
"stored_fields": [ "field3", "field4" ]
}
]
}{
"docs": [
{
"_index": "test",
"_id": "1",
"routing": "key2"
},
{
"_index": "test",
"_id": "2"
}
]
}{
"docs": [
{
"_index": "string",
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"_ignored": [
"string"
],
"found": true,
"_id": "string",
"_primary_term": 42.0,
"_routing": "string",
"_seq_no": 42.0,
"_source": {},
"_version": 42.0
}
]
}Change the number of requests per second for a particular reindex operation. For example:
POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
Rethrottling that speeds up the query takes effect immediately. Rethrottling that slows down the query will take effect after completing the current batch. This behavior prevents scroll timeouts.
The task identifier, which can be found by using the tasks API.
The throttle for this request in sub-requests per second.
It can be either -1 to turn off throttling or any decimal number like 1.7 or 12 to throttle to that level.
curl \
--request POST 'http://api.example.com/_reindex/{task_id}/_rethrottle' \
--header "Authorization: $API_KEY"{
"nodes": {}
}Get information and statistics about terms in the fields of a particular document.
You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request.
You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body.
For example:
GET /my-index-000001/_termvectors/1?fields=message
Fields can be specified using wildcards, similar to the multi match query.
Term vectors are real-time by default, not near real-time.
This can be changed by setting realtime parameter to false.
You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.
Term information
positions: true)offsets: true)payloads: true), as base64 encoded bytesIf the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.
Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.
Behaviour
The term and field statistics are not accurate.
Deleted documents are not taken into account.
The information is only retrieved for the shard the requested document resides in.
The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
Use routing only to hit a particular shard.
A comma-separated list or wildcard expressions of fields to include in the statistics.
It is used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.
If true, the response includes:
If true, the response includes term offsets.
If true, the response includes term payloads.
If true, the response includes term positions.
The node or shard the operation should be performed on. It is random by default.
If true, the request is real-time as opposed to near-real-time.
A custom value that is used to route operations to a specific shard.
If true, the response includes:
By default these values are not returned since term statistics can have a serious performance impact.
If true, returns the document version as part of a hit.
The version type.
Values are internal, external, external_gte, or force.
An artificial document (a document not present in the index) for which you want to retrieve term vectors.
Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.
If true, the response includes:
If true, the response includes term offsets.
If true, the response includes term payloads.
If true, the response includes term positions.
If true, the response includes:
By default these values are not returned since term statistics can have a serious performance impact.
Values are internal, external, external_gte, or force.
curl \
--request POST 'http://api.example.com/{index}/_termvectors/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"fields\" : [\"text\"],\n \"offsets\" : true,\n \"payloads\" : true,\n \"positions\" : true,\n \"term_statistics\" : true,\n \"field_statistics\" : true\n}"'{
"fields" : ["text"],
"offsets" : true,
"payloads" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
},
"fields": ["fullname"],
"per_field_analyzer" : {
"fullname": "keyword"
}
}{
"doc": {
"plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
},
"term_statistics": true,
"field_statistics": true,
"positions": false,
"offsets": false,
"filter": {
"max_num_terms": 3,
"min_term_freq": 1,
"min_doc_freq": 1
}
}{
"fields" : ["text", "some_field_without_term_vectors"],
"offsets" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"found": true,
"took": 6,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 4,
"doc_count": 2,
"sum_ttf": 6
},
"terms": {
"test": {
"doc_freq": 2,
"ttf": 4,
"term_freq": 3,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 4,
"payload": "d29yZA=="
},
{
"position": 1,
"start_offset": 5,
"end_offset": 9,
"payload": "d29yZA=="
},
{
"position": 2,
"start_offset": 10,
"end_offset": 14,
"payload": "d29yZA=="
}
]
}
}
}
}
}{
"_index": "my-index-000001",
"_version": 0,
"found": true,
"took": 6,
"term_vectors": {
"fullname": {
"field_statistics": {
"sum_doc_freq": 2,
"doc_count": 4,
"sum_ttf": 4
},
"terms": {
"John Doe": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 8
}
]
}
}
}
}
}{
"_index": "imdb",
"_version": 0,
"found": true,
"term_vectors": {
"plot": {
"field_statistics": {
"sum_doc_freq": 3384269,
"doc_count": 176214,
"sum_ttf": 3753460
},
"terms": {
"armored": {
"doc_freq": 27,
"ttf": 27,
"term_freq": 1,
"score": 9.74725
},
"industrialist": {
"doc_freq": 88,
"ttf": 88,
"term_freq": 1,
"score": 8.590818
},
"stark": {
"doc_freq": 44,
"ttf": 47,
"term_freq": 1,
"score": 9.272792
}
}
}
}
}Get information and statistics about terms in the fields of a particular document.
You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request.
You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body.
For example:
GET /my-index-000001/_termvectors/1?fields=message
Fields can be specified using wildcards, similar to the multi match query.
Term vectors are real-time by default, not near real-time.
This can be changed by setting realtime parameter to false.
You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.
Term information
positions: true)offsets: true)payloads: true), as base64 encoded bytesIf the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.
Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.
Behaviour
The term and field statistics are not accurate.
Deleted documents are not taken into account.
The information is only retrieved for the shard the requested document resides in.
The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
Use routing only to hit a particular shard.
The name of the index that contains the document.
A comma-separated list or wildcard expressions of fields to include in the statistics.
It is used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.
If true, the response includes:
If true, the response includes term offsets.
If true, the response includes term payloads.
If true, the response includes term positions.
The node or shard the operation should be performed on. It is random by default.
If true, the request is real-time as opposed to near-real-time.
A custom value that is used to route operations to a specific shard.
If true, the response includes:
By default these values are not returned since term statistics can have a serious performance impact.
If true, returns the document version as part of a hit.
The version type.
Values are internal, external, external_gte, or force.
An artificial document (a document not present in the index) for which you want to retrieve term vectors.
Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.
If true, the response includes:
If true, the response includes term offsets.
If true, the response includes term payloads.
If true, the response includes term positions.
If true, the response includes:
By default these values are not returned since term statistics can have a serious performance impact.
Values are internal, external, external_gte, or force.
curl \
--request POST 'http://api.example.com/{index}/_termvectors' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"fields\" : [\"text\"],\n \"offsets\" : true,\n \"payloads\" : true,\n \"positions\" : true,\n \"term_statistics\" : true,\n \"field_statistics\" : true\n}"'{
"fields" : ["text"],
"offsets" : true,
"payloads" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
},
"fields": ["fullname"],
"per_field_analyzer" : {
"fullname": "keyword"
}
}{
"doc": {
"plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
},
"term_statistics": true,
"field_statistics": true,
"positions": false,
"offsets": false,
"filter": {
"max_num_terms": 3,
"min_term_freq": 1,
"min_doc_freq": 1
}
}{
"fields" : ["text", "some_field_without_term_vectors"],
"offsets" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"found": true,
"took": 6,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 4,
"doc_count": 2,
"sum_ttf": 6
},
"terms": {
"test": {
"doc_freq": 2,
"ttf": 4,
"term_freq": 3,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 4,
"payload": "d29yZA=="
},
{
"position": 1,
"start_offset": 5,
"end_offset": 9,
"payload": "d29yZA=="
},
{
"position": 2,
"start_offset": 10,
"end_offset": 14,
"payload": "d29yZA=="
}
]
}
}
}
}
}{
"_index": "my-index-000001",
"_version": 0,
"found": true,
"took": 6,
"term_vectors": {
"fullname": {
"field_statistics": {
"sum_doc_freq": 2,
"doc_count": 4,
"sum_ttf": 4
},
"terms": {
"John Doe": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 8
}
]
}
}
}
}
}{
"_index": "imdb",
"_version": 0,
"found": true,
"term_vectors": {
"plot": {
"field_statistics": {
"sum_doc_freq": 3384269,
"doc_count": 176214,
"sum_ttf": 3753460
},
"terms": {
"armored": {
"doc_freq": 27,
"ttf": 27,
"term_freq": 1,
"score": 9.74725
},
"industrialist": {
"doc_freq": 88,
"ttf": 88,
"term_freq": 1,
"score": 8.590818
},
"stark": {
"doc_freq": 44,
"ttf": 47,
"term_freq": 1,
"score": 9.272792
}
}
}
}
}Update a document by running a script or passing a partial document.
If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.
The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:
The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.
The _source field must be enabled to use this API.
In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).
Only perform the operation if the document has this primary term.
Only perform the operation if the document has this sequence number.
True or false if to include the document source in the error message in case of parsing errors.
The script language.
If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes.
Values are true, false, or wait_for.
If true, the destination must be an index alias.
The number of times the operation should be retried when a conflict occurs.
A custom value used to route operations to a specific shard.
The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
The number of copies of each shard that must be active before proceeding with the operation.
Set to 'all' or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default value of 1 means it waits for each primary shard to be active.
If false, source retrieval is turned off.
You can also specify a comma-separated list of the fields you want to retrieve.
The source fields you want to exclude.
The source fields you want to retrieve.
If true, the result in the response is set to noop (no operation) when there are no changes to the document.
A partial update to an existing document.
If both doc and script are specified, doc is ignored.
If true, use the contents of 'doc' as the value of 'upsert'.
NOTE: Using ingest pipelines with doc_as_upsert is not supported.
If true, run the script whether or not the document exists.
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run.
curl \
--request POST 'http://api.example.com/{index}/_update/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\" : {\n \"source\": \"ctx._source.counter += params.count\",\n \"lang\": \"painless\",\n \"params\" : {\n \"count\" : 4\n }\n }\n}"'{
"script" : {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params" : {
"count" : 4
}
}
}{
"scripted_upsert": true,
"script": {
"source": """
if ( ctx.op == 'create' ) {
ctx._source.counter = params.count
} else {
ctx._source.counter += params.count
}
""",
"params": {
"count": 4
}
},
"upsert": {}
}{
"doc": {
"name": "new_name"
},
"doc_as_upsert": true
}{
"script": {
"source": "ctx._source.tags.add(params.tag)",
"lang": "painless",
"params": {
"tag": "blue"
}
}
}{
"script": {
"source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
"lang": "painless",
"params": {
"tag": "blue"
}
}
}{
"script" : "ctx._source.new_field = 'value_of_new_field'"
}{
"script" : "ctx._source.remove('new_field')"
}{
"script": "ctx._source['my-object'].remove('my-subfield')"
}{
"script": {
"source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
"lang": "painless",
"params": {
"tag": "green"
}
}
}{
"doc": {
"name": "new_name"
}
}{
"script": {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params": {
"count": 4
}
},
"upsert": {
"counter": 1
}
}{
"_shards": {
"total": 0,
"successful": 0,
"failed": 0
},
"_index": "test",
"_id": "1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 1,
"result": "noop"
}Deletes an existing enrich policy and its enrich index.
Enrich policy to delete.
Period to wait for a connection to the master node.
curl \
--request DELETE 'http://api.example.com/_enrich/policy/{name}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}Create the enrich index for an existing enrich policy.
Enrich policy to execute.
Period to wait for a connection to the master node.
If true, the request blocks other enrich policy execution requests until complete.
curl \
--request PUT 'http://api.example.com/_enrich/policy/{name}/_execute' \
--header "Authorization: $API_KEY"{
"status": {
"phase": "SCHEDULED",
"step": "string"
},
"": "string"
}Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_enrich/policy' \
--header "Authorization: $API_KEY"{
"policies": [
{
"config": {
"additionalProperty1": {
"enrich_fields": "string",
"indices": "string",
"match_field": "string",
"query": {},
"name": "string",
"elasticsearch_version": "string"
},
"additionalProperty2": {
"enrich_fields": "string",
"indices": "string",
"match_field": "string",
"query": {},
"name": "string",
"elasticsearch_version": "string"
}
}
}
]
}Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
Get the current status and available results for an async EQL search or a stored synchronous EQL search.
Identifier for the search.
Period for which the search and its results are stored on the cluster. Defaults to the keep_alive value set by the search’s EQL search API request.
Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.
curl \
--request GET 'http://api.example.com/_eql/search/{id}' \
--header "Authorization: $API_KEY"{
"id": "string",
"is_partial": true,
"is_running": true,
"": 42.0,
"timed_out": true,
"hits": {
"total": {
"relation": "eq",
"value": 42.0
},
"events": [
{
"_index": "string",
"_id": "string",
"_source": {},
"missing": true,
"fields": {
"additionalProperty1": [
{}
],
"additionalProperty2": [
{}
]
}
}
],
"sequences": [
{
"events": [
{
"_index": "string",
"_id": "string",
"_source": {},
"missing": true,
"fields": {}
}
],
"join_keys": [
{}
]
}
]
},
"shard_failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
]
}Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.
Identifier for the search to delete.
A search ID is provided in the EQL search API's response for an async search.
A search ID is also provided if the request’s keep_on_completion parameter is true.
curl \
--request DELETE 'http://api.example.com/_eql/search/{id}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.
The name of the index to scope the operation
If true, returns partial results if there are shard failures. If false, returns an error with no partial results.
If true, sequence queries will return partial results in case of shard failures. If false, they will return no results at all. This flag has effect only if allow_partial_search_results is true.
Period for which the search and its results are stored on the cluster.
If true, the search and its results are stored on the cluster.
Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.
EQL query you wish to run.
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Query, written in Query DSL, used to filter the events on which the EQL query runs.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
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.
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.
Allow query execution also in case of shard failures. If true, the query will keep running and will return results based on the available shards. For sequences, the behavior can be further refined using allow_partial_sequence_results
This flag applies only to sequences and has effect only if allow_partial_search_results=true. If true, the sequence query will return results based on the available shards, ignoring the others. If false, the sequence query will return successfully, but will always have empty results.
Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.
Values are tail or head.
By default, the response of a sample query contains up to 10 samples, with one sample per unique set of join keys. Use the size
parameter to get a smaller or larger set of samples. To retrieve more than one sample per set of join keys, use the
max_samples_per_key parameter. Pipes are not supported for sample queries.
curl \
--request GET 'http://api.example.com/{index}/_eql/search' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": \"\"\"\n process where (process.name == \"cmd.exe\" and process.pid != 2013)\n \"\"\"\n}"'{
"query": """
process where (process.name == "cmd.exe" and process.pid != 2013)
"""
}{
"query": """
sequence by process.pid
[ file where file.name == "cmd.exe" and process.pid != 2013 ]
[ process where stringContains(process.executable, "regsvr32") ]
"""
}{
"is_partial": false,
"is_running": false,
"took": 6,
"timed_out": false,
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"sequences": [
{
"join_keys": [
2012
],
"events": [
{
"_index": ".ds-my-data-stream-2099.12.07-000001",
"_id": "AtOJ4UjUBAAx3XR5kcCM",
"_source": {
"@timestamp": "2099-12-06T11:04:07.000Z",
"event": {
"category": "file",
"id": "dGCHwoeS",
"sequence": 2
},
"file": {
"accessed": "2099-12-07T11:07:08.000Z",
"name": "cmd.exe",
"path": "C:\\Windows\\System32\\cmd.exe",
"type": "file",
"size": 16384
},
"process": {
"pid": 2012,
"name": "cmd.exe",
"executable": "C:\\Windows\\System32\\cmd.exe"
}
}
},
{
"_index": ".ds-my-data-stream-2099.12.07-000001",
"_id": "OQmfCaduce8zoHT93o4H",
"_source": {
"@timestamp": "2099-12-07T11:07:09.000Z",
"event": {
"category": "process",
"id": "aR3NWVOs",
"sequence": 4
},
"process": {
"pid": 2012,
"name": "regsvr32.exe",
"command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll",
"executable": "C:\\Windows\\System32\\regsvr32.exe"
}
}
}
]
}
]
}
}Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.
The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.
If true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards.
The character to use between values within a CSV row. It is valid only for the CSV format.
Indicates whether columns that are entirely null will be removed from the columns and values portion of the results.
If true, the response will include an extra section under the name all_columns which has the name of all the columns.
A short version of the Accept header, for example json or yaml.
Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
The period for which the query and its results are stored in the cluster.
The default period is five days.
When this period expires, the query and its results are deleted, even if the query is still ongoing.
If the keep_on_completion parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the wait_for_completion_timeout parameter, regardless of this value.
Indicates whether the query and its results are stored in the cluster.
If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.
The period to wait for the request to finish. By default, the request waits for 1 second for the query results. If the query completes during this period, results are returned Otherwise, a query ID is returned that can later be used to retrieve the results.
By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
If provided and true the response will include an extra profile object
with information on how the query was executed. This information is for human debugging
and its format can change at any time but it can give some insight into the performance
of each part of the query.
The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
When set to true and performing a cross-cluster query, the response will include an extra _clusters
object with information about the clusters that participated in the search along with info such as shards
count.
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.
curl \
--request POST 'http://api.example.com/_query/async' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": \"\"\"\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n \"\"\",\n \"wait_for_completion_timeout\": \"2s\",\n \"include_ccs_metadata\": true\n}"'{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s",
"include_ccs_metadata": true
}{
"": 42.0,
"is_partial": true,
"all_columns": [
{
"name": "string",
"type": "string"
}
],
"columns": [
{
"name": "string",
"type": "string"
}
],
"values": [
[
42.0
]
],
"_clusters": {
"total": 42.0,
"successful": 42.0,
"running": 42.0,
"skipped": 42.0,
"partial": 42.0,
"failed": 42.0,
"details": {
"additionalProperty1": {
"status": "running",
"indices": "string",
"": 42.0,
"_shards": {
"total": 42.0,
"successful": 42.0,
"skipped": 42.0,
"failed": 42.0,
"failures": [
{}
]
}
},
"additionalProperty2": {
"status": "running",
"indices": "string",
"": 42.0,
"_shards": {
"total": 42.0,
"successful": 42.0,
"skipped": 42.0,
"failed": 42.0,
"failures": [
{}
]
}
}
}
},
"profile": {},
"id": "string",
"is_running": true
}Get search results for an ES|QL (Elasticsearch query language) query.
A short version of the Accept header, e.g. json, yaml.
Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
The character to use between values within a CSV row. Only valid for the CSV format.
Should columns that are entirely null be removed from the columns and values portion of the results?
Defaults to false. If true then the response will include an extra section under the name all_columns which has the name of all columns.
If true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards.
By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
If provided and true the response will include an extra profile object
with information on how the query was executed. This information is for human debugging
and its format can change at any time but it can give some insight into the performance
of each part of the query.
The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
When set to true and performing a cross-cluster query, the response will include an extra _clusters
object with information about the clusters that participated in the search along with info such as shards
count.
curl \
--request POST 'http://api.example.com/_query' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": \"\"\"\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n \"\"\",\n \"include_ccs_metadata\": true\n}"'{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"include_ccs_metadata": true
}{
"": 42.0,
"is_partial": true,
"all_columns": [
{
"name": "string",
"type": "string"
}
],
"columns": [
{
"name": "string",
"type": "string"
}
],
"values": [
[
42.0
]
],
"_clusters": {
"total": 42.0,
"successful": 42.0,
"running": 42.0,
"skipped": 42.0,
"partial": 42.0,
"failed": 42.0,
"details": {
"additionalProperty1": {
"status": "running",
"indices": "string",
"": 42.0,
"_shards": {
"total": 42.0,
"successful": 42.0,
"skipped": 42.0,
"failed": 42.0,
"failures": [
{}
]
}
},
"additionalProperty2": {
"status": "running",
"indices": "string",
"": 42.0,
"_shards": {
"total": 42.0,
"successful": 42.0,
"skipped": 42.0,
"failed": 42.0,
"failures": [
{}
]
}
}
}
},
"profile": {}
}Get the current global checkpoints for an index. This API is designed for internal use by the Fleet server project.
A single index or index alias that resolves to a single index.
A boolean value which controls whether to wait (until the timeout) for the global checkpoints
to advance past the provided checkpoints.
A boolean value which controls whether to wait (until the timeout) for the target index to exist
and all primary shards be active. Can only be true when wait_for_advance is true.
A comma separated list of previous global checkpoints. When used in combination with wait_for_advance,
the API will only return once the global checkpoints advances past the checkpoints. Providing an empty list
will cause Elasticsearch to immediately return the current global checkpoints.
Period to wait for a global checkpoints to advance past checkpoints.
curl \
--request GET 'http://api.example.com/{index}/_fleet/global_checkpoints' \
--header "Authorization: $API_KEY"{
"global_checkpoints": [
42.0
],
"timed_out": true
}