Create or update an autoscaling policy Added in 7.11.0
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
Path parameters
-
the name of the autoscaling policy
Query parameters
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Body Required
-
Decider settings.
curl \
--request PUT http://api.example.com/_autoscaling/policy/{name} \
--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
}
Delete a behavioral analytics collection Technical preview
The associated data stream is also deleted.
Path parameters
-
The name of the analytics collection to be deleted
curl \
--request DELETE http://api.example.com/_application/analytics/{name}
{
"acknowledged": true
}
Get anomaly detection jobs Added in 7.7.0
Get configuration and usage information for anomaly detection jobs.
This API returns a maximum of 10,000 jobs.
If the Elasticsearch security features are enabled, you must have monitor_ml
,
monitor
, manage_ml
, or manage
cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get anomaly detection job statistics API.
Path parameters
-
Identifier for the anomaly detection job.
Query parameters
-
allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs that match.
- Contains the
_all
string or no identifiers and there are no matches. - Contains wildcard expressions and there are only partial matches.
If
true
, the API returns an empty jobs array when there are no matches and the subset of results when there are partial matches. Iffalse
, the API returns a 404 status code when there are no matches or only partial matches. -
bytes string
The unit used to display byte values.
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
h string | array[string]
Comma-separated list of column names to display.
-
s string | array[string]
Comma-separated list of column names or column aliases used to sort the response.
-
time string
The unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
curl \
--request GET http://api.example.com/_cat/ml/anomaly_detectors/{job_id}
[
{
"id": "string",
"state": "closing",
"opened_time": "string",
"assignment_explanation": "string",
"data.processed_records": "string",
"data.processed_fields": "string",
"": 42.0,
"data.input_records": "string",
"data.input_fields": "string",
"data.invalid_dates": "string",
"data.missing_fields": "string",
"data.out_of_order_timestamps": "string",
"data.empty_buckets": "string",
"data.sparse_buckets": "string",
"data.buckets": "string",
"data.earliest_record": "string",
"data.latest_record": "string",
"data.last": "string",
"data.last_empty_bucket": "string",
"data.last_sparse_bucket": "string",
"model.memory_status": "ok",
"model.memory_limit": "string",
"model.by_fields": "string",
"model.over_fields": "string",
"model.partition_fields": "string",
"model.bucket_allocation_failures": "string",
"model.categorization_status": "ok",
"model.categorized_doc_count": "string",
"model.total_category_count": "string",
"model.frequent_category_count": "string",
"model.rare_category_count": "string",
"model.dead_category_count": "string",
"model.failed_category_count": "string",
"model.log_time": "string",
"model.timestamp": "string",
"forecasts.total": "string",
"forecasts.memory.min": "string",
"forecasts.memory.max": "string",
"forecasts.memory.avg": "string",
"forecasts.memory.total": "string",
"forecasts.records.min": "string",
"forecasts.records.max": "string",
"forecasts.records.avg": "string",
"forecasts.records.total": "string",
"forecasts.time.min": "string",
"forecasts.time.max": "string",
"forecasts.time.avg": "string",
"forecasts.time.total": "string",
"node.id": "string",
"node.name": "string",
"node.ephemeral_id": "string",
"node.address": "string",
"buckets.count": "string",
"buckets.time.total": "string",
"buckets.time.min": "string",
"buckets.time.max": "string",
"buckets.time.exp_avg": "string",
"buckets.time.exp_avg_hour": "string"
}
]
name version alias_count mapping_count settings_count metadata_count included_in
my-template-1 0 0 1 0 [my-index-template]
my-template-2 0 3 0 0 [my-index-template]
Get plugin information
Get a list of plugins running on each node of a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
Query parameters
-
include_bootstrap boolean
Include bootstrap plugins in the response
-
local boolean
If
true
, the request computes the list of selected nodes from the local cluster state. Iffalse
the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. -
master_timeout string
Period to wait for a connection to the master node.
curl \
--request GET http://api.example.com/_cat/plugins
[
{
"id": "string",
"name": "string",
"component": "string",
"version": "string",
"description": "string",
"type": "string"
}
]
name component version description
U7321H6 analysis-icu 8.17.0 The ICU Analysis plugin integrates the Lucene ICU module into Elasticsearch, adding ICU-related analysis components.
U7321H6 analysis-kuromoji 8.17.0 The Japanese (kuromoji) Analysis plugin integrates Lucene kuromoji analysis module into elasticsearch.
U7321H6 analysis-nori 8.17.0 The Korean (nori) Analysis plugin integrates Lucene nori analysis module into elasticsearch.
U7321H6 analysis-phonetic 8.17.0 The Phonetic Analysis plugin integrates phonetic token filter analysis with elasticsearch.
U7321H6 analysis-smartcn 8.17.0 Smart Chinese Analysis plugin integrates Lucene Smart Chinese analysis module into elasticsearch.
U7321H6 analysis-stempel 8.17.0 The Stempel (Polish) Analysis plugin integrates Lucene stempel (polish) analysis module into elasticsearch.
U7321H6 analysis-ukrainian 8.17.0 The Ukrainian Analysis plugin integrates the Lucene UkrainianMorfologikAnalyzer into elasticsearch.
U7321H6 discovery-azure-classic 8.17.0 The Azure Classic Discovery plugin allows to use Azure Classic API for the unicast discovery mechanism
U7321H6 discovery-ec2 8.17.0 The EC2 discovery plugin allows to use AWS API for the unicast discovery mechanism.
U7321H6 discovery-gce 8.17.0 The Google Compute Engine (GCE) Discovery plugin allows to use GCE API for the unicast discovery mechanism.
U7321H6 mapper-annotated-text 8.17.0 The Mapper Annotated_text plugin adds support for text fields with markup used to inject annotation tokens into the index.
U7321H6 mapper-murmur3 8.17.0 The Mapper Murmur3 plugin allows to compute hashes of a field's values at index-time and to store them in the index.
U7321H6 mapper-size 8.17.0 The Mapper Size plugin allows document to record their uncompressed size at index time.
U7321H6 store-smb 8.17.0 The Store SMB plugin adds support for SMB stores.
Get shard information
Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
Query parameters
-
bytes string
The unit used to display byte values.
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
master_timeout string
Period to wait for a connection to the master node.
-
time string
Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
curl \
--request GET http://api.example.com/_cat/shards
[
{
"index": "string",
"shard": "string",
"prirep": "string",
"state": "string",
"docs": "string",
"store": "string",
"dataset": "string",
"ip": "string",
"id": "string",
"node": "string",
"sync_id": "string",
"unassigned.reason": "string",
"unassigned.at": "string",
"unassigned.for": "string",
"unassigned.details": "string",
"recoverysource.type": "string",
"completion.size": "string",
"fielddata.memory_size": "string",
"fielddata.evictions": "string",
"query_cache.memory_size": "string",
"query_cache.evictions": "string",
"flush.total": "string",
"flush.total_time": "string",
"get.current": "string",
"get.time": "string",
"get.total": "string",
"get.exists_time": "string",
"get.exists_total": "string",
"get.missing_time": "string",
"get.missing_total": "string",
"indexing.delete_current": "string",
"indexing.delete_time": "string",
"indexing.delete_total": "string",
"indexing.index_current": "string",
"indexing.index_time": "string",
"indexing.index_total": "string",
"indexing.index_failed": "string",
"merges.current": "string",
"merges.current_docs": "string",
"merges.current_size": "string",
"merges.total": "string",
"merges.total_docs": "string",
"merges.total_size": "string",
"merges.total_time": "string",
"refresh.total": "string",
"refresh.time": "string",
"refresh.external_total": "string",
"refresh.external_time": "string",
"refresh.listeners": "string",
"search.fetch_current": "string",
"search.fetch_time": "string",
"search.fetch_total": "string",
"search.open_contexts": "string",
"search.query_current": "string",
"search.query_time": "string",
"search.query_total": "string",
"search.scroll_current": "string",
"search.scroll_time": "string",
"search.scroll_total": "string",
"segments.count": "string",
"segments.memory": "string",
"segments.index_writer_memory": "string",
"segments.version_map_memory": "string",
"segments.fixed_bitset_memory": "string",
"seq_no.max": "string",
"seq_no.local_checkpoint": "string",
"seq_no.global_checkpoint": "string",
"warmer.current": "string",
"warmer.total": "string",
"warmer.total_time": "string",
"path.data": "string",
"path.state": "string",
"bulk.total_operations": "string",
"bulk.total_time": "string",
"bulk.total_size_in_bytes": "string",
"bulk.avg_time": "string",
"bulk.avg_size_in_bytes": "string"
}
]
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
my-index-000001 0 p RELOCATING 3014 31.1mb 192.168.56.10 H5dfFeA -> -> 192.168.56.30 bGG90GE
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
my-index-000001 0 r INITIALIZING 0 14.3mb 192.168.56.30 bGG90GE
my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
my-index-000001 0 r STARTED 3014 31.1mb 192.168.56.30 bGG90GE
my-index-000001 0 r STARTED 3014 31.1mb 192.168.56.20 I8hydUG
my-index-000001 0 r UNASSIGNED ALLOCATION_FAILED
Get cluster statistics Added in 1.3.0
Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).
Path parameters
-
Comma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.
Query parameters
-
include_remotes boolean
Include remote cluster data into the response
-
timeout string
Period to wait for each node to respond. If a node does not respond before its timeout expires, the response does not include its stats. However, timed out nodes are included in the response’s
_nodes.failed
property. Defaults to no timeout.
curl \
--request GET http://api.example.com/_cluster/stats/nodes/{node_id}
{
"_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",
"cluster_uuid": "string",
"indices": {
"analysis": {
"analyzer_types": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"built_in_analyzers": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"built_in_char_filters": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"built_in_filters": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"built_in_tokenizers": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"char_filter_types": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"filter_types": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"tokenizer_types": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
]
},
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {
"size_in_bytes": 42.0
},
"additionalProperty2": {
"size_in_bytes": 42.0
}
}
},
"count": 42.0,
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {
"memory_size_in_bytes": 42.0
},
"additionalProperty2": {
"memory_size_in_bytes": 42.0
}
}
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"segments": {
"count": 42.0,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
},
"additionalProperty2": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
}
},
"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
},
"shards": {
"index": {
"primaries": {
"avg": 42.0,
"max": 42.0,
"min": 42.0
},
"replication": {
"avg": 42.0,
"max": 42.0,
"min": 42.0
},
"shards": {
"avg": 42.0,
"max": 42.0,
"min": 42.0
}
},
"primaries": 42.0,
"replication": 42.0,
"total": 42.0
},
"store": {
"": 42.0,
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"mappings": {
"field_types": [
{
"name": "string",
"count": 42.0,
"index_count": 42.0,
"indexed_vector_count": 42.0,
"indexed_vector_dim_max": 42.0,
"indexed_vector_dim_min": 42.0,
"script_count": 42.0
}
],
"runtime_field_types": [
{
"chars_max": 42.0,
"chars_total": 42.0,
"count": 42.0,
"doc_max": 42.0,
"doc_total": 42.0,
"index_count": 42.0,
"lang": [
"string"
],
"lines_max": 42.0,
"lines_total": 42.0,
"name": "string",
"scriptless_count": 42.0,
"shadowed_count": 42.0,
"source_max": 42.0,
"source_total": 42.0
}
],
"total_field_count": 42.0,
"total_deduplicated_field_count": 42.0,
"": 42.0,
"total_deduplicated_mapping_size_in_bytes": 42.0
},
"versions": [
{
"index_count": 42.0,
"primary_shard_count": 42.0,
"total_primary_bytes": 42.0,
"version": "string"
}
]
},
"nodes": {
"count": {
"coordinating_only": 42.0,
"data": 42.0,
"data_cold": 42.0,
"data_content": 42.0,
"data_frozen": 42.0,
"data_hot": 42.0,
"data_warm": 42.0,
"ingest": 42.0,
"master": 42.0,
"ml": 42.0,
"remote_cluster_client": 42.0,
"total": 42.0,
"transform": 42.0,
"voting_only": 42.0
},
"discovery_types": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"fs": {
"available_in_bytes": 42.0,
"free_in_bytes": 42.0,
"total_in_bytes": 42.0
},
"indexing_pressure": {
"memory": {
"current": {
"all_in_bytes": 42.0,
"combined_coordinating_and_primary_in_bytes": 42.0,
"coordinating_in_bytes": 42.0,
"coordinating_rejections": 42.0,
"primary_in_bytes": 42.0,
"primary_rejections": 42.0,
"replica_in_bytes": 42.0,
"replica_rejections": 42.0
},
"limit_in_bytes": 42.0,
"total": {
"all_in_bytes": 42.0,
"combined_coordinating_and_primary_in_bytes": 42.0,
"coordinating_in_bytes": 42.0,
"coordinating_rejections": 42.0,
"primary_in_bytes": 42.0,
"primary_rejections": 42.0,
"replica_in_bytes": 42.0,
"replica_rejections": 42.0
}
}
},
"ingest": {
"number_of_pipelines": 42.0,
"processor_stats": {
"additionalProperty1": {
"count": 42.0,
"current": 42.0,
"failed": 42.0,
"time": "string"
},
"additionalProperty2": {
"count": 42.0,
"current": 42.0,
"failed": 42.0,
"time": "string"
}
}
},
"jvm": {
"": 42.0,
"mem": {
"heap_max_in_bytes": 42.0,
"heap_used_in_bytes": 42.0
},
"threads": 42.0,
"versions": [
{
"bundled_jdk": true,
"count": 42.0,
"using_bundled_jdk": true,
"version": "string",
"vm_name": "string",
"vm_vendor": "string",
"vm_version": "string"
}
]
},
"network_types": {
"http_types": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"transport_types": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
}
},
"os": {
"allocated_processors": 42.0,
"architectures": [
{
"arch": "string",
"count": 42.0
}
],
"available_processors": 42.0,
"mem": {
"adjusted_total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"free_percent": 42.0,
"total_in_bytes": 42.0,
"used_in_bytes": 42.0,
"used_percent": 42.0
},
"names": [
{
"count": 42.0,
"name": "string"
}
],
"pretty_names": [
{
"count": 42.0,
"pretty_name": "string"
}
]
},
"packaging_types": [
{
"count": 42.0,
"flavor": "string",
"type": "string"
}
],
"plugins": [
{
"classname": "string",
"description": "string",
"elasticsearch_version": "string",
"extended_plugins": [
"string"
],
"has_native_controller": true,
"java_version": "string",
"name": "string",
"version": "string",
"licensed": true
}
],
"process": {
"cpu": {
"percent": 42.0
},
"open_file_descriptors": {
"avg": 42.0,
"max": 42.0,
"min": 42.0
}
},
"versions": [
"string"
]
},
"status": "green",
"timestamp": 42.0
}
Reload the keystore on nodes in the cluster Added in 6.5.0
Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. That is, you can change them on disk and reload them without restarting any nodes in the cluster. When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.
When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted. Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.
Query parameters
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Body
-
secure_settings_password string
curl \
--request POST http://api.example.com/_nodes/reload_secure_settings \
--header "Content-Type: application/json" \
--data '"{\n \"secure_settings_password\": \"keystore-password\"\n}"'
{
"secure_settings_password": "keystore-password"
}
{
"_nodes": {
"total": 1,
"successful": 1,
"failed": 0
},
"cluster_name": "my_cluster",
"nodes": {
"pQHNt5rXTTWNvUgOrdynKg": {
"name": "node-0"
}
}
}
Reload the keystore on nodes in the cluster Added in 6.5.0
Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. That is, you can change them on disk and reload them without restarting any nodes in the cluster. When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.
When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted. Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.
Path parameters
-
The names of particular nodes in the cluster to target.
Query parameters
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Body
-
secure_settings_password string
curl \
--request POST http://api.example.com/_nodes/{node_id}/reload_secure_settings \
--header "Content-Type: application/json" \
--data '"{\n \"secure_settings_password\": \"keystore-password\"\n}"'
{
"secure_settings_password": "keystore-password"
}
{
"_nodes": {
"total": 1,
"successful": 1,
"failed": 0
},
"cluster_name": "my_cluster",
"nodes": {
"pQHNt5rXTTWNvUgOrdynKg": {
"name": "node-0"
}
}
}
Get node statistics
Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.
Path parameters
-
Limit the information returned to the specified metrics
-
Limit the information returned for indices metric to the specific index metrics. It can be used only if indices (or all) metric is specified.
Query parameters
-
completion_fields string | array[string]
Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.
-
fielddata_fields string | array[string]
Comma-separated list or wildcard expressions of fields to include in fielddata statistics.
-
fields string | array[string]
Comma-separated list or wildcard expressions of fields to include in the statistics.
-
groups boolean
Comma-separated list of search groups to include in the search statistics.
-
include_segment_file_sizes boolean
If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).
-
level string
Indicates whether statistics are aggregated at the cluster, index, or shard level.
Values are
cluster
,indices
, orshards
. -
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
types array[string]
A comma-separated list of document types for the indexing index metric.
-
include_unloaded_segments boolean
If
true
, the response includes information from segments that are not loaded into memory.
curl \
--request GET http://api.example.com/_nodes/stats/{metric}/{index_metric}
{
"_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
},
"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
},
"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"
}
}
}
}
}
Get the cluster health Added in 8.7.0
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
{
"cluster_name": "string",
"indicators": {
"": {
"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"
}
Check in a connector sync job Technical preview
Check in a connector sync job and set the last_seen
field to the current time before updating it in the internal index.
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.
Path parameters
-
The unique identifier of the connector sync job to be checked in.
curl \
--request PUT http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_check_in
{}
Get a connector sync job Beta
Path parameters
-
The unique identifier of the connector sync job
curl \
--request GET http://api.example.com/_connector/_sync_job/{connector_sync_job_id}
{
"": "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"
}
Resume a follower Added in 6.5.0
Resume a cross-cluster replication follower index that was paused. The follower index could have been paused with the pause follower API. Alternatively it could be paused due to replication that cannot be retried due to failures during following tasks. When this API returns, the follower index will resume fetching operations from the leader index.
Path parameters
-
The name of the follow index to resume following.
Query parameters
-
master_timeout string
Period to wait for a connection to the master node.
Body
-
max_read_request_size string
-
max_retry_delay string
A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. -
max_write_buffer_count number
-
max_write_buffer_size string
-
max_write_request_size string
-
read_poll_timeout string
A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
curl \
--request POST http://api.example.com/{index}/_ccr/resume_follow \
--header "Content-Type: application/json" \
--data '"{\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}"'
{
"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"
}
{
"acknowledged" : true
}
Get data streams Added in 7.9.0
Get information about one or more data streams.
Path parameters
-
Comma-separated list of data stream names used to limit the request. Wildcard (
*
) expressions are supported. If omitted, all data streams are returned.
Query parameters
-
expand_wildcards string | array[string]
Type of data stream that wildcard patterns can match. Supports comma-separated values, such as
open,hidden
. -
include_defaults boolean
If true, returns all relevant default configurations for the index template.
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
verbose boolean
Whether the maximum timestamp for each data stream should be calculated and returned.
curl \
--request GET http://api.example.com/_data_stream/{name}
{
"data_streams": [
{
"name": "my-data-stream",
"timestamp_field": {
"name": "@timestamp"
},
"indices": [
{
"index_name": ".ds-my-data-stream-2099.03.07-000001",
"index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
},
{
"index_name": ".ds-my-data-stream-2099.03.08-000002",
"index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
}
],
"generation": 2,
"_meta": {
"my-meta-field": "foo"
},
"status": "GREEN",
"next_generation_managed_by": "Index Lifecycle Management",
"prefer_ilm": true,
"template": "my-index-template",
"ilm_policy": "my-lifecycle-policy",
"hidden": false,
"system": false,
"allow_custom_routing": false,
"replicated": false,
"rollover_on_write": false
},
{
"name": "my-data-stream-two",
"timestamp_field": {
"name": "@timestamp"
},
"indices": [
{
"index_name": ".ds-my-data-stream-two-2099.03.08-000001",
"index_uuid": "3liBu2SYS5axasRt6fUIpA",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
}
],
"generation": 1,
"_meta": {
"my-meta-field": "foo"
},
"status": "YELLOW",
"next_generation_managed_by": "Index Lifecycle Management",
"prefer_ilm": true,
"template": "my-index-template",
"ilm_policy": "my-lifecycle-policy",
"hidden": false,
"system": false,
"allow_custom_routing": false,
"replicated": false,
"rollover_on_write": false
}
]
}
Bulk index or delete documents
Perform multiple index
, create
, delete
, and update
actions in a single request.
This reduces overhead and can greatly increase indexing speed.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To use the
create
action, you must have thecreate_doc
,create
,index
, orwrite
index privilege. Data streams support only thecreate
action. - To use the
index
action, you must have thecreate
,index
, orwrite
index privilege. - To use the
delete
action, you must have thedelete
orwrite
index privilege. - To use the
update
action, you must have theindex
orwrite
index privilege. - To automatically create a data stream or index with a bulk API request, you must have the
auto_configure
,create_index
, ormanage
index privilege. - To make the result of a bulk operation visible to search using the
refresh
parameter, you must have themaintenance
ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:
action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n
The index
and create
actions expect a source on the next line and have the same semantics as the op_type
parameter in the standard index API.
A create
action fails if a document with the same ID already exists in the target
An index
action adds or replaces a document as necessary.
NOTE: Data streams support only the create
action.
To update or delete a document in a data stream, you must target the backing index containing the document.
An update
action expects that the partial doc, upsert, and script and its options are specified on the next line.
A delete
action does not expect a source on the next line and has the same semantics as the standard delete API.
NOTE: The final line of data must end with a newline character (\n
).
Each newline character may be preceded by a carriage return (\r
).
When sending NDJSON data to the _bulk
endpoint, use a Content-Type
header of application/json
or application/x-ndjson
.
Because this format uses literal newline characters (\n
) as delimiters, make sure that the JSON actions and sources are not pretty printed.
If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index
argument.
A note on the format: the idea here is to make processing as fast as possible.
As some of the actions are redirected to other shards on other nodes, only action_meta_data
is parsed on the receiving node side.
Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.
There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.
Client suppport for bulk requests
Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:
- Go: Check out
esutil.BulkIndexer
- Perl: Check out
Search::Elasticsearch::Client::5_0::Bulk
andSearch::Elasticsearch::Client::5_0::Scroll
- Python: Check out
elasticsearch.helpers.*
- JavaScript: Check out
client.helpers.*
- .NET: Check out
BulkAllObservable
- PHP: Check out bulk indexing.
Submitting bulk requests with cURL
If you're providing text file input to curl
, you must use the --data-binary
flag instead of plain -d
.
The latter doesn't preserve newlines. For example:
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
Optimistic concurrency control
Each index
and delete
action within a bulk API call may include the if_seq_no
and if_primary_term
parameters in their respective action and meta data lines.
The if_seq_no
and if_primary_term
parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.
Versioning
Each bulk item can include the version value using the version
field.
It automatically follows the behavior of the index or delete operation based on the _version
mapping.
It also support the version_type
.
Routing
Each bulk item can include the routing value using the routing
field.
It automatically follows the behavior of the index or delete operation based on the _routing
mapping.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Wait for active shards
When making bulk calls, you can set the wait_for_active_shards
parameter to require a minimum number of shard copies to be active before starting to process the bulk request.
Refresh
Control when the changes made by this request are visible to search.
NOTE: Only the shards that receive the bulk request will be affected by refresh.
Imagine a _bulk?refresh=wait_for
request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the _bulk
request at all.
Path parameters
-
The name of the data stream, index, or index alias to perform bulk actions on.
Query parameters
-
include_source_on_error boolean
True or false if to include the document source in the error message in case of parsing errors.
-
list_executed_pipelines boolean
If
true
, the response will include the ingest pipelines that were run for each index or create. -
pipeline string
The pipeline identifier to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to
_none
turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter. -
refresh string
If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, wait for a refresh to make this operation visible to search. Iffalse
, do nothing with refreshes. Valid values:true
,false
,wait_for
.Values are
true
,false
, orwait_for
. -
routing string
A custom value that is used to route operations to a specific shard.
-
_source boolean | string | array[string]
Indicates whether to return the
_source
field (true
orfalse
) or contains a list of fields to return. -
_source_excludes string | array[string]
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 isfalse
, this parameter is ignored. -
_source_includes string | array[string]
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 isfalse
, this parameter is ignored. -
timeout string
The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards. The default is
1m
(one minute), which guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur. -
wait_for_active_shards number | string
The number of shard copies that must be active before proceeding with the operation. Set to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default is1
, which waits for each primary shard to be active. -
require_alias boolean
If
true
, the request's actions must target an index alias. -
require_data_stream boolean
If
true
, the request's actions must target a data stream (existing or to be created).
curl \
--request POST http://api.example.com/{index}/_bulk \
--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"
}
}
}
]
}
Create a new document in the index Added in 5.0.0
You can index a new JSON document with the /<target>/_doc/
or /<target>/_create/<_id>
APIs
Using _create
guarantees that the document is indexed only if it does not already exist.
It returns a 409 response when a document with a same ID already exists in the index.
To update an existing document, you must use the /<target>/_doc/
API.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To add a document using the
PUT /<target>/_create/<_id>
orPOST /<target>/_create/<_id>
request formats, you must have thecreate_doc
,create
,index
, orwrite
index privilege. - To automatically create a data stream or index with this API request, you must have the
auto_configure
,create_index
, ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
Automatically create data streams and indices
If the request's target doesn't exist and matches an index template with a data_stream
definition, the index operation automatically creates the data stream.
If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.
NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.
If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.
Automatic index creation is controlled by the action.auto_create_index
setting.
If it is true
, any index can be created automatically.
You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false
to turn off automatic index creation entirely.
Specify a comma-separated list of patterns you want to allow or prefix each pattern with +
or -
to indicate whether it should be allowed or blocked.
When a list is specified, the default behaviour is to disallow.
NOTE: The action.auto_create_index
setting affects the automatic creation of indices only.
It does not affect the creation of data streams.
Routing
By default, shard placement — or routing — is controlled by using a hash of the document's ID value.
For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing
parameter.
When setting up explicit mapping, you can also use the _routing
field to direct the index operation to extract the routing value from the document itself.
This does come at the (very minimal) cost of an additional document parsing pass.
If the _routing
mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Distributed
The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.
Active shards
To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.
If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.
By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards
is 1
).
This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards
.
To alter this behavior per operation, use the wait_for_active_shards request
parameter.
Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas
+1).
Specifying a negative value or a number greater than the number of shard copies will throw an error.
For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).
If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.
This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.
If wait_for_active_shards
is set on the request to 3
(and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.
This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.
However, if you set wait_for_active_shards
to all
(or to 4
, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.
The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.
It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.
After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.
The _shards
section of the API response reveals the number of shard copies on which replication succeeded and failed.
Path parameters
-
The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (
*
) pattern of an index template with adata_stream
definition, this request creates the data stream. If the target doesn't exist and doesn’t match a data stream template, this request creates the index. -
A unique identifier for the document. To automatically generate a document ID, use the
POST /<target>/_doc/
request format.
Query parameters
-
include_source_on_error boolean
True or false if to include the document source in the error message in case of parsing errors.
-
pipeline string
The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to
_none
turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter. -
refresh string
If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, it waits for a refresh to make this operation visible to search. Iffalse
, it does nothing with refreshes.Values are
true
,false
, orwait_for
. -
routing string
A custom value that is used to route operations to a specific shard.
-
timeout string
The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. Elasticsearch waits for at least the specified timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.
-
version number
The explicit version number for concurrency control. It must be a non-negative long number.
-
version_type string
The version type.
Values are
internal
,external
,external_gte
, orforce
. -
wait_for_active_shards number | string
The number of shard copies that must be active before proceeding with the operation. You can set it to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default value of1
means it waits for each primary shard to be active.
curl \
--request POST http://api.example.com/{index}/_create/{id} \
--header "Content-Type: application/json" \
--data '"{\n \"@timestamp\": \"2099-11-15T13:12:00\",\n \"message\": \"GET /search HTTP/1.1 200 1070000\",\n \"user\": {\n \"id\": \"kimchy\"\n }\n}"'
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
{
"_id": "string",
"_index": "string",
"_primary_term": 42.0,
"result": "created",
"_seq_no": 42.0,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
},
"_version": 42.0,
"forced_refresh": true
}
Create or update a document in an index
Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.
NOTE: You cannot use this API to send update requests for existing documents in a data stream.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To add or overwrite a document using the
PUT /<target>/_doc/<_id>
request format, you must have thecreate
,index
, orwrite
index privilege. - To add a document using the
POST /<target>/_doc/
request format, you must have thecreate_doc
,create
,index
, orwrite
index privilege. - To automatically create a data stream or index with this API request, you must have the
auto_configure
,create_index
, ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
NOTE: Replica shards might not all be started when an indexing operation returns successfully.
By default, only the primary is required. Set wait_for_active_shards
to change this default behavior.
Automatically create data streams and indices
If the request's target doesn't exist and matches an index template with a data_stream
definition, the index operation automatically creates the data stream.
If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.
NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.
If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.
Automatic index creation is controlled by the action.auto_create_index
setting.
If it is true
, any index can be created automatically.
You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false
to turn off automatic index creation entirely.
Specify a comma-separated list of patterns you want to allow or prefix each pattern with +
or -
to indicate whether it should be allowed or blocked.
When a list is specified, the default behaviour is to disallow.
NOTE: The action.auto_create_index
setting affects the automatic creation of indices only.
It does not affect the creation of data streams.
Optimistic concurrency control
Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no
and if_primary_term
parameters.
If a mismatch is detected, the operation will result in a VersionConflictException
and a status code of 409
.
Routing
By default, shard placement — or routing — is controlled by using a hash of the document's ID value.
For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing
parameter.
When setting up explicit mapping, you can also use the _routing
field to direct the index operation to extract the routing value from the document itself.
This does come at the (very minimal) cost of an additional document parsing pass.
If the _routing
mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Distributed
The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.
Active shards
To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.
If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.
By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards
is 1
).
This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards
.
To alter this behavior per operation, use the wait_for_active_shards request
parameter.
Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas
+1).
Specifying a negative value or a number greater than the number of shard copies will throw an error.
For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).
If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.
This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.
If wait_for_active_shards
is set on the request to 3
(and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.
This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.
However, if you set wait_for_active_shards
to all
(or to 4
, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.
The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.
It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.
After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.
The _shards
section of the API response reveals the number of shard copies on which replication succeeded and failed.
No operation (noop) updates
When updating a document by using this API, a new version of the document is always created even if the document hasn't changed.
If this isn't acceptable use the _update
API with detect_noop
set to true
.
The detect_noop
option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.
There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.
Versioning
Each indexed document is given a version number.
By default, internal versioning is used that starts at 1 and increments with each update, deletes included.
Optionally, the version number can be set to an external value (for example, if maintained in a database).
To enable this functionality, version_type
should be set to external
.
The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18
.
NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks.
When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:
PUT my-index-000001/_doc/1?version=2&version_type=external
{
"user": {
"id": "elkbee"
}
}
In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
Path parameters
-
The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (
*
) pattern of an index template with adata_stream
definition, this request creates the data stream. If the target doesn't exist and doesn't match a data stream template, this request creates the index. You can check for existing targets with the resolve index API. -
A unique identifier for the document. To automatically generate a document ID, use the
POST /<target>/_doc/
request format and omit this parameter.
Query parameters
-
if_primary_term number
Only perform the operation if the document has this primary term.
-
if_seq_no number
Only perform the operation if the document has this sequence number.
-
include_source_on_error boolean
True or false if to include the document source in the error message in case of parsing errors.
-
op_type string
Set to
create
to only index the document if it does not already exist (put if absent). If a document with the specified_id
already exists, the indexing operation will fail. The behavior is the same as using the<index>/_create
endpoint. If a document ID is specified, this paramater defaults toindex
. Otherwise, it defaults tocreate
. If the request targets a data stream, anop_type
ofcreate
is required.Values are
index
orcreate
. -
pipeline string
The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to
_none
disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. -
refresh string
If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, it waits for a refresh to make this operation visible to search. Iffalse
, it does nothing with refreshes.Values are
true
,false
, orwait_for
. -
routing string
A custom value that is used to route operations to a specific shard.
-
timeout string
The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.
-
version number
An explicit version number for concurrency control. It must be a non-negative long number.
-
version_type string
The version type.
Values are
internal
,external
,external_gte
, orforce
. -
wait_for_active_shards number | string
The number of shard copies that must be active before proceeding with the operation. You can set it to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default value of1
means it waits for each primary shard to be active. -
require_alias boolean
If
true
, the destination must be an index alias.
curl \
--request POST http://api.example.com/{index}/_doc/{id} \
--header "Content-Type: application/json" \
--data '"{\n \"@timestamp\": \"2099-11-15T13:12:00\",\n \"message\": \"GET /search HTTP/1.1 200 1070000\",\n \"user\": {\n \"id\": \"kimchy\"\n }\n}"'
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "W0tpsmIBdwcYyG50zbta",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"result": "created"
}
{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"result": "created"
}
Get a document's source
Get the source of a document. For example:
GET my-index-000001/_source/1
You can use the source filtering parameters to control which parts of the _source
are returned:
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
Path parameters
-
The name of the index that contains the document.
-
A unique document identifier.
Query parameters
-
preference string
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
-
realtime boolean
If
true
, the request is real-time as opposed to near-real-time. -
refresh boolean
If
true
, the request refreshes the relevant shards before retrieving the document. Setting it totrue
should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). -
routing string
A custom value used to route operations to a specific shard.
-
_source boolean | string | array[string]
Indicates whether to return the
_source
field (true
orfalse
) or lists the fields to return. -
_source_excludes string | array[string]
A comma-separated list of source fields to exclude in the response.
-
_source_includes string | array[string]
A comma-separated list of source fields to include in the response.
-
stored_fields string | array[string]
A comma-separated list of stored fields to return as part of a hit.
-
version number
The version number for concurrency control. It must match the current version of the document for the request to succeed.
-
version_type string
The version type.
Values are
internal
,external
,external_gte
, orforce
.
curl \
--request GET http://api.example.com/{index}/_source/{id}
{}
Get multiple documents Added in 1.3.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.
Query parameters
-
force_synthetic_source boolean
Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.
-
preference string
Specifies the node or shard the operation should be performed on. Random by default.
-
realtime boolean
If
true
, the request is real-time as opposed to near-real-time. -
refresh boolean
If
true
, the request refreshes relevant shards before retrieving documents. -
routing string
Custom value used to route operations to a specific shard.
-
_source boolean | string | array[string]
True or false to return the
_source
field or not, or a list of fields to return. -
_source_excludes string | array[string]
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. -
_source_includes string | array[string]
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 isfalse
, this parameter is ignored. -
stored_fields string | array[string]
If
true
, retrieves the document fields stored in the index rather than the document_source
.
Body Required
curl \
--request POST http://api.example.com/_mget \
--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 documents Added in 1.3.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.
Path parameters
-
Name of the index to retrieve documents from when
ids
are specified, or when a document in thedocs
array does not specify an index.
Query parameters
-
force_synthetic_source boolean
Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.
-
preference string
Specifies the node or shard the operation should be performed on. Random by default.
-
realtime boolean
If
true
, the request is real-time as opposed to near-real-time. -
refresh boolean
If
true
, the request refreshes relevant shards before retrieving documents. -
routing string
Custom value used to route operations to a specific shard.
-
_source boolean | string | array[string]
True or false to return the
_source
field or not, or a list of fields to return. -
_source_excludes string | array[string]
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. -
_source_includes string | array[string]
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 isfalse
, this parameter is ignored. -
stored_fields string | array[string]
If
true
, retrieves the document fields stored in the index rather than the document_source
.
Body Required
curl \
--request GET http://api.example.com/{index}/_mget \
--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 term vector information
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
- term frequency in the field (always returned)
- term positions (
positions: true
) - start and end offsets (
offsets: true
) - term payloads (
payloads: true
), as base64 encoded bytes
If 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.
Path parameters
-
The name of the index that contains the document.
Query parameters
-
fields string | array[string]
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
orfielddata_fields
parameters. -
field_statistics boolean
If
true
, the response includes:- The document count (how many documents contain this field).
- The sum of document frequencies (the sum of document frequencies for all terms in this field).
- The sum of total term frequencies (the sum of total term frequencies of each term in this field).
-
offsets boolean
If
true
, the response includes term offsets. -
payloads boolean
If
true
, the response includes term payloads. -
positions boolean
If
true
, the response includes term positions. -
preference string
The node or shard the operation should be performed on. It is random by default.
-
realtime boolean
If true, the request is real-time as opposed to near-real-time.
-
routing string
A custom value that is used to route operations to a specific shard.
-
term_statistics boolean
If
true
, the response includes:- The total term frequency (how often a term occurs in all documents).
- The document frequency (the number of documents containing the current term).
By default these values are not returned since term statistics can have a serious performance impact.
-
version number
If
true
, returns the document version as part of a hit. -
version_type string
The version type.
Values are
internal
,external
,external_gte
, orforce
.
Body
-
doc object
An artificial document (a document not present in the index) for which you want to retrieve term vectors.
Additional properties are allowed.
-
filter object
Additional properties are allowed.
-
per_field_analyzer object
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.
curl \
--request POST http://api.example.com/{index}/_termvectors \
--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 enrich stats Added in 7.5.0
Returns enrich coordinator statistics and information about enrich policies that are currently executing.
Query parameters
-
master_timeout string
Period to wait for a connection to the master node.
curl \
--request GET http://api.example.com/_enrich/_stats
{
"coordinator_stats": [
{
"executed_searches_total": 42.0,
"node_id": "string",
"queue_size": 42.0,
"remote_requests_current": 42.0,
"remote_requests_total": 42.0
}
],
"executing_policies": [
{
"name": "string",
"additionalProperty1": {
"action": "string",
"cancelled": true,
"cancellable": true,
"description": "string",
"headers": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"id": 42.0,
"node": "string",
"running_time": "string",
"": "string",
"status": {},
"type": "string"
},
"additionalProperty2": {
"action": "string",
"cancelled": true,
"cancellable": true,
"description": "string",
"headers": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"id": 42.0,
"node": "string",
"running_time": "string",
"": "string",
"status": {},
"type": "string"
}
}
],
"cache_stats": [
{
"node_id": "string",
"count": 42.0,
"hits": 42.0,
"": 42.0,
"misses": 42.0,
"evictions": 42.0,
"size_in_bytes": 42.0
}
]
}
Get component templates Added in 7.8.0
Get information about component templates.
Path parameters
-
Comma-separated list of component template names used to limit the request. Wildcard (
*
) expressions are supported.
Query parameters
-
flat_settings boolean
If
true
, returns settings in flat format. -
include_defaults boolean
Return all default configurations for the component template (default: false)
-
local boolean
If
true
, the request retrieves information from the local node only. Iffalse
, information is retrieved from the master node. -
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET http://api.example.com/_component_template/{name}
{
"component_templates": [
{
"name": "string",
"component_template": {
"template": {
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"version": 42.0,
"settings": {
"*": {}
},
"mappings": {
"all_field": {},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {},
"index_field": {},
"_meta": {},
"numeric_detection": true,
"properties": {},
"_routing": {},
"_size": {},
"_source": {},
"runtime": {},
"enabled": true,
"subobjects": true,
"_data_stream_timestamp": {}
},
"aliases": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": {}
},
"version": 42.0,
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"deprecated": true
}
}
]
}
Add an index block Added in 7.9.0
Add an index block to an index. Index blocks limit the operations allowed on an index by blocking specific operation types.
Path parameters
-
A comma-separated list or wildcard expression of index names used to limit the request. By default, you must explicitly name the indices you are adding blocks to. To allow the adding of blocks to indices with
_all
,*
, or other wildcard expressions, change theaction.destructive_requires_name
setting tofalse
. You can update this setting in theelasticsearch.yml
file or by using the cluster update settings API. -
The block type to add to the index.
Values are
metadata
,read
,read_only
, orwrite
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. -
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as
open,hidden
. -
master_timeout string
The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. It can also be set to
-1
to indicate that the request should never timeout. -
timeout string
The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. It can also be set to
-1
to indicate that the request should never timeout.
curl \
--request PUT http://api.example.com/{index}/_block/{block}
{
"acknowledged" : true,
"shards_acknowledged" : true,
"indices" : [ {
"name" : "my-index-000001",
"blocked" : true
} ]
}
Delete indices
Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.
You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. You can then use the delete index API to delete the previous write index.
Path parameters
-
Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (
*
) or_all
. To use wildcards or_all
, set theaction.destructive_requires_name
cluster setting tofalse
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request DELETE http://api.example.com/{index}
{
"acknowledged": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
}
}
Path parameters
-
Comma-separated list of data streams or indices used to limit the request. Supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
. -
Comma-separated list of aliases to check. Supports wildcards (
*
).
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request HEAD http://api.example.com/{index}/_alias/{name}
Create or update an index template
Index templates define settings, mappings, and aliases that can be applied automatically to new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.
IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.
Composable templates always take precedence over legacy templates. If no composable template matches a new index, matching legacy templates are applied according to their order.
Index templates are only applied during index creation. Changes to index templates do not affect existing indices. Settings and mappings specified in create index API requests override any settings or mappings specified in an index template.
You can use C-style /* *\/
block comments in index templates.
You can include comments anywhere in the request body, except before the opening curly bracket.
Indices matching multiple templates
Multiple index templates can potentially match an index, in this case, both the settings and mappings are merged into the final configuration of the index. The order of the merging can be controlled using the order parameter, with lower order being applied first, and higher orders overriding them. NOTE: Multiple matching templates with the same order value will result in a non-deterministic merging order.
Path parameters
-
The name of the template
Query parameters
-
create boolean
If true, this request cannot replace or update existing index templates.
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
order number
Order in which Elasticsearch applies this template if index matches multiple templates.
Templates with lower 'order' values are merged first. Templates with higher 'order' values are merged later, overriding templates with lower values.
-
cause string
Body Required
-
aliases object
Aliases for the index.
index_patterns string | array[string]
Array of wildcard expressions used to match the names of indices during creation.
-
mappings object
Additional properties are allowed.
-
order number
Order in which Elasticsearch applies this template if index matches multiple templates.
Templates with lower 'order' values are merged first. Templates with higher 'order' values are merged later, overriding templates with lower values.
-
settings object
Additional properties are allowed.
-
version number
curl \
--request PUT http://api.example.com/_template/{name} \
--header "Content-Type: application/json" \
--data '{"mappings":{"_source":{"enabled":false}},"settings":{"number_of_shards":1},"properties":{"host_name":{"type":"keyword"},"created_at":{"type":"date","format":"EEE MMM dd HH:mm:ss Z yyyy"}},"index_patterns":["te*","bar*"]}'
{
"mappings": {
"_source": {
"enabled": false
}
},
"settings": {
"number_of_shards": 1
},
"properties": {
"host_name": {
"type": "keyword"
},
"created_at": {
"type": "date",
"format": "EEE MMM dd HH:mm:ss Z yyyy"
}
},
"index_patterns": [
"te*",
"bar*"
]
}
{
"acknowledged": true
}
Flush data streams or indices
Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. When restarting, Elasticsearch replays any unflushed operations from the transaction log into the Lucene index to bring it back into the state that it was in before the restart. Elasticsearch automatically triggers flushes as needed, using heuristics that trade off the size of the unflushed transaction log against the cost of performing each flush.
After each operation has been flushed it is permanently stored in the Lucene index. This may mean that there is no need to maintain an additional copy of it in the transaction log. The transaction log is made up of multiple files, called generations, and Elasticsearch will delete any generation files when they are no longer needed, freeing up disk space.
It is also possible to trigger a flush on one or more indices using the flush API, although it is rare for users to need to call this API directly. If you call the flush API after indexing some documents then a successful response indicates that Elasticsearch has flushed all the documents that were indexed before the flush API was called.
Path parameters
-
Comma-separated list of data streams, indices, and aliases to flush. Supports wildcards (
*
). To flush all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
force boolean
If
true
, the request forces a flush even if there are no changes to commit to the index. -
wait_if_ongoing boolean
If
true
, the flush operation blocks until execution when another flush operation is running. Iffalse
, Elasticsearch returns an error if you request a flush when another flush operation is running.
curl \
--request POST http://api.example.com/{index}/_flush
{
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
}
}
Get mapping definitions
For data streams, the API retrieves mappings for the stream’s backing indices.
Path parameters
-
Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
local boolean
If
true
, the request retrieves information from the local node only. -
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET http://api.example.com/{index}/_mapping
{
"additionalProperty1": {
"item": {
"all_field": {
"analyzer": "string",
"enabled": true,
"omit_norms": true,
"search_analyzer": "string",
"similarity": "string",
"store": true,
"store_term_vector_offsets": true,
"store_term_vector_payloads": true,
"store_term_vector_positions": true,
"store_term_vectors": true
},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {
"enabled": true
},
"index_field": {
"enabled": true
},
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"numeric_detection": true,
"properties": {},
"_routing": {
"required": true
},
"_size": {
"enabled": true
},
"_source": {
"compress": true,
"compress_threshold": "string",
"enabled": true,
"excludes": [
"string"
],
"includes": [
"string"
],
"mode": "disabled"
},
"runtime": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
}
},
"enabled": true,
"subobjects": true,
"_data_stream_timestamp": {
"enabled": true
}
},
"mappings": {
"all_field": {
"analyzer": "string",
"enabled": true,
"omit_norms": true,
"search_analyzer": "string",
"similarity": "string",
"store": true,
"store_term_vector_offsets": true,
"store_term_vector_payloads": true,
"store_term_vector_positions": true,
"store_term_vectors": true
},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {
"enabled": true
},
"index_field": {
"enabled": true
},
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"numeric_detection": true,
"properties": {},
"_routing": {
"required": true
},
"_size": {
"enabled": true
},
"_source": {
"compress": true,
"compress_threshold": "string",
"enabled": true,
"excludes": [
"string"
],
"includes": [
"string"
],
"mode": "disabled"
},
"runtime": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
}
},
"enabled": true,
"subobjects": true,
"_data_stream_timestamp": {
"enabled": true
}
}
},
"additionalProperty2": {
"item": {
"all_field": {
"analyzer": "string",
"enabled": true,
"omit_norms": true,
"search_analyzer": "string",
"similarity": "string",
"store": true,
"store_term_vector_offsets": true,
"store_term_vector_payloads": true,
"store_term_vector_positions": true,
"store_term_vectors": true
},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {
"enabled": true
},
"index_field": {
"enabled": true
},
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"numeric_detection": true,
"properties": {},
"_routing": {
"required": true
},
"_size": {
"enabled": true
},
"_source": {
"compress": true,
"compress_threshold": "string",
"enabled": true,
"excludes": [
"string"
],
"includes": [
"string"
],
"mode": "disabled"
},
"runtime": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
}
},
"enabled": true,
"subobjects": true,
"_data_stream_timestamp": {
"enabled": true
}
},
"mappings": {
"all_field": {
"analyzer": "string",
"enabled": true,
"omit_norms": true,
"search_analyzer": "string",
"similarity": "string",
"store": true,
"store_term_vector_offsets": true,
"store_term_vector_payloads": true,
"store_term_vector_positions": true,
"store_term_vectors": true
},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {
"enabled": true
},
"index_field": {
"enabled": true
},
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"numeric_detection": true,
"properties": {},
"_routing": {
"required": true
},
"_size": {
"enabled": true
},
"_source": {
"compress": true,
"compress_threshold": "string",
"enabled": true,
"excludes": [
"string"
],
"includes": [
"string"
],
"mode": "disabled"
},
"runtime": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
}
},
"enabled": true,
"subobjects": true,
"_data_stream_timestamp": {
"enabled": true
}
}
}
}
Refresh an index
A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.
By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds.
You can change this default interval with the index.refresh_interval
setting.
Refresh requests are synchronous and do not return a response until the refresh operation completes.
Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.
If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for
query parameter option.
This option ensures the indexing operation waits for a periodic refresh before running the search.
Path parameters
-
Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
.
curl \
--request GET http://api.example.com/{index}/_refresh
{
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
}
}
Resolve the cluster Added in 8.13.0
Resolve the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. If no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.
This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.
You use the same index expression with this endpoint as you would for cross-cluster search. Index and cluster exclusions are also supported with this endpoint.
For each cluster in the index expression, information is returned about:
- Whether the querying ("local") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the
remote/info
endpoint. - Whether each remote cluster is configured with
skip_unavailable
astrue
orfalse
. - Whether there are any indices, aliases, or data streams on that cluster that match the index expression.
- Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).
- Cluster version information, including the Elasticsearch server version.
For example, GET /_resolve/cluster/my-index-*,cluster*:my-index-*
returns information about the local cluster and all remotely configured clusters that start with the alias cluster*
.
Each cluster returns information about whether it has any indices, aliases or data streams that match my-index-*
.
Note on backwards compatibility
The ability to query without an index expression was added in version 8.18, so when
querying remote clusters older than that, the local cluster will send the index
expression dummy*
to those remote clusters. Thus, if an errors occur, you may see a reference
to that index expression even though you didn't request it. If it causes a problem, you can
instead include an index expression like *:*
to bypass the issue.
Advantages of using this endpoint before a cross-cluster search
You may want to exclude a cluster or index from a search when:
- A remote cluster is not currently connected and is configured with
skip_unavailable=false
. Running a cross-cluster search under those conditions will cause the entire search to fail. - A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is
logs*,remote1:logs*
and the remote1 cluster has no indices, aliases or data streams that matchlogs*
. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search. - The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the
_resolve/cluster
response will be present. (This is also where security/permission errors will be shown.) - A remote cluster is an older version that does not support the feature you want to use in your search.
Test availability of remote clusters
The remote/info
endpoint is commonly used to test whether the "local" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not.
The remote cluster may be available, while the local cluster is not currently connected to it.
You can use the _resolve/cluster
API to attempt to reconnect to remote clusters.
For example with GET _resolve/cluster
or GET _resolve/cluster/*:*
.
The connected
field in the response will indicate whether it was successful.
If a connection was (re-)established, this will also cause the remote/info
endpoint to now indicate a connected status.
Path parameters
-
A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve. Resources on remote clusters can be specified using the
<cluster>
:<name>
syntax. Index and cluster exclusions (e.g.,-cluster1:*
) are also supported. If no index expression is specified, information about all remote clusters configured on the local cluster is returned without doing any index matching
Query parameters
-
allow_no_indices boolean
If false, the request returns an error if any wildcard expression, index alias, or
_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the_resolve/cluster
API endpoint that takes no index expression. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the_resolve/cluster
API endpoint that takes no index expression. -
If true, concrete, expanded, or aliased indices are ignored when frozen. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the
_resolve/cluster
API endpoint that takes no index expression. -
timeout string
The maximum time to wait for remote clusters to respond. If a remote cluster does not respond within this timeout period, the API response will show the cluster as not connected and include an error message that the request timed out.
The default timeout is unset and the query can take as long as the networking layer is configured to wait for remote clusters that are not responding (typically 30 seconds).
curl \
--request GET http://api.example.com/_resolve/cluster/{name}
{
"(local)": {
"connected": true,
"skip_unavailable": false,
"matching_indices": true,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
},
"cluster_one": {
"connected": true,
"skip_unavailable": true,
"matching_indices": true,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
},
"cluster_two": {
"connected": true,
"skip_unavailable": false,
"matching_indices": true,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
}
}
{
"(local)": {
"connected": true,
"skip_unavailable": false,
"error": "no such index [not_present]"
},
"cluster_one": {
"connected": true,
"skip_unavailable": true,
"matching_indices": false,
"version": {
"number": "8.13.0",
"build_flavor": "default",
"minimum_wire_compatibility_version": "7.17.0",
"minimum_index_compatibility_version": "7.0.0"
}
},
"cluster_two": {
"connected": false,
"skip_unavailable": false
},
"cluster_three": {
"connected": false,
"skip_unavailable": false,
"error": "Request timed out before receiving a response from the remote cluster"
},
"oldcluster": {
"connected": true,
"skip_unavailable": false,
"matching_indices": true
}
}
Resolve indices Added in 7.9.0
Resolve the names and/or index patterns for indices, aliases, and data streams. Multiple patterns and remote clusters are supported.
Path parameters
-
Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve. Resources on remote clusters can be specified using the
<cluster>
:<name>
syntax.
Query parameters
-
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
.
curl \
--request GET http://api.example.com/_resolve/index/{name}
{
"indices": [
{
"name": "foo_closed",
"attributes": [
"closed"
]
},
{
"name": "freeze-index",
"aliases": [
"f-alias"
],
"attributes": [
"open"
]
},
{
"name": "remoteCluster1:bar-01",
"attributes": [
"open"
]
}
],
"aliases": [
{
"name": "f-alias",
"indices": [
"freeze-index",
"my-index-000001"
]
}
],
"data_streams": [
{
"name": "foo",
"backing_indices": [
".ds-foo-2099.03.07-000001"
],
"timestamp_field": "@timestamp"
}
]
}
Split an index Added in 6.1.0
Split an index into a new index with more primary shards.
Before you can split an index:
The index must be read-only.
The cluster health status must be green.
You can do make an index read-only with the following request using the add index block API:
PUT /my_source_index/_block/write
The current write index on a data stream cannot be split. In order to split the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be split.
The number of times the index can be split (and the number of shards that each original shard can be split into) is determined by the index.number_of_routing_shards
setting.
The number of routing shards specifies the hashing space that is used internally to distribute documents across shards with consistent hashing.
For instance, a 5 shard index with number_of_routing_shards
set to 30 (5 x 2 x 3) could be split by a factor of 2 or 3.
A split operation:
- Creates a new target index with the same definition as the source index, but with a larger number of primary shards.
- Hard-links segments from the source index into the target index. If the file system doesn't support hard-linking, all segments are copied into the new index, which is a much more time consuming process.
- Hashes all documents again, after low level files are created, to delete documents that belong to a different shard.
- Recovers the target index as though it were a closed index which had just been re-opened.
IMPORTANT: Indices can only be split if they satisfy the following requirements:
- The target index must not exist.
- The source index must have fewer primary shards than the target index.
- The number of primary shards in the target index must be a multiple of the number of primary shards in the source index.
- The node handling the split process must have sufficient free disk space to accommodate a second copy of the existing index.
Path parameters
-
Name of the source index to split.
-
Name of the target index to create.
Query parameters
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
wait_for_active_shards number | string
The number of shard copies that must be active before proceeding with the operation. Set to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
).
curl \
--request POST http://api.example.com/{index}/_split/{target} \
--header "Content-Type: application/json" \
--data '"{\n \"settings\": {\n \"index.number_of_shards\": 2\n }\n}"'
{
"settings": {
"index.number_of_shards": 2
}
}
{
"acknowledged": true,
"shards_acknowledged": true,
"index": "string"
}
Get index statistics Added in 1.3.0
For data streams, the API retrieves statistics for the stream's backing indices.
By default, the returned statistics are index-level with primaries
and total
aggregations.
primaries
are the values for only the primary shards.
total
are the accumulated values for both primary and replica shards.
To get shard-level statistics, set the level
parameter to shards
.
NOTE: When moving to another node, the shard-level statistics for a shard are cleared. Although the shard is no longer part of the node, that node retains any node-level statistics to which the shard contributed.
Path parameters
-
A comma-separated list of index names; use
_all
or empty string to perform the operation on all indices -
Limit the information returned the specific metrics.
Query parameters
-
completion_fields string | array[string]
Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.
-
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. -
fielddata_fields string | array[string]
Comma-separated list or wildcard expressions of fields to include in fielddata statistics.
-
fields string | array[string]
Comma-separated list or wildcard expressions of fields to include in the statistics.
-
forbid_closed_indices boolean
If true, statistics are not collected from closed indices.
-
groups string | array[string]
Comma-separated list of search groups to include in the search statistics.
-
include_segment_file_sizes boolean
If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).
-
include_unloaded_segments boolean
If true, the response includes information from segments that are not loaded into memory.
-
level string
Indicates whether statistics are aggregated at the cluster, index, or shard level.
Values are
cluster
,indices
, orshards
.
curl \
--request GET http://api.example.com/{index}/_stats/{metric}
{
"indices": {
"additionalProperty1": {
"primaries": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"shards": {
"additionalProperty1": [
{
"commit": {},
"completion": {},
"docs": {},
"fielddata": {},
"flush": {},
"get": {},
"indexing": {},
"mappings": {},
"merges": {},
"shard_path": {},
"query_cache": {},
"recovery": {},
"refresh": {},
"request_cache": {},
"retention_leases": {},
"routing": {},
"search": {},
"segments": {},
"seq_no": {},
"store": {},
"translog": {},
"warmer": {},
"bulk": {},
"shards": {},
"shard_stats": {},
"additionalProperty1": {},
"additionalProperty2": {}
}
],
"additionalProperty2": [
{
"commit": {},
"completion": {},
"docs": {},
"fielddata": {},
"flush": {},
"get": {},
"indexing": {},
"mappings": {},
"merges": {},
"shard_path": {},
"query_cache": {},
"recovery": {},
"refresh": {},
"request_cache": {},
"retention_leases": {},
"routing": {},
"search": {},
"segments": {},
"seq_no": {},
"store": {},
"translog": {},
"warmer": {},
"bulk": {},
"shards": {},
"shard_stats": {},
"additionalProperty1": {},
"additionalProperty2": {}
}
]
},
"total": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"shards": {
"additionalProperty1": [
{
"commit": {},
"completion": {},
"docs": {},
"fielddata": {},
"flush": {},
"get": {},
"indexing": {},
"mappings": {},
"merges": {},
"shard_path": {},
"query_cache": {},
"recovery": {},
"refresh": {},
"request_cache": {},
"retention_leases": {},
"routing": {},
"search": {},
"segments": {},
"seq_no": {},
"store": {},
"translog": {},
"warmer": {},
"bulk": {},
"shards": {},
"shard_stats": {},
"additionalProperty1": {},
"additionalProperty2": {}
}
],
"additionalProperty2": [
{
"commit": {},
"completion": {},
"docs": {},
"fielddata": {},
"flush": {},
"get": {},
"indexing": {},
"mappings": {},
"merges": {},
"shard_path": {},
"query_cache": {},
"recovery": {},
"refresh": {},
"request_cache": {},
"retention_leases": {},
"routing": {},
"search": {},
"segments": {},
"seq_no": {},
"store": {},
"translog": {},
"warmer": {},
"bulk": {},
"shards": {},
"shard_stats": {},
"additionalProperty1": {},
"additionalProperty2": {}
}
]
},
"total": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"uuid": "string",
"health": "green",
"status": "open"
}
},
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
},
"additionalProperty1": {
"primaries": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {
"size_in_bytes": 42.0
},
"additionalProperty2": {
"size_in_bytes": 42.0
}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {
"memory_size_in_bytes": 42.0
},
"additionalProperty2": {
"memory_size_in_bytes": 42.0
}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
},
"additionalProperty2": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"shards": {
"additionalProperty1": [
{
"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
},
"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": {},
"additionalProperty2": {}
}
],
"additionalProperty2": [
{
"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
},
"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": {},
"additionalProperty2": {}
}
]
},
"total": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {
"size_in_bytes": 42.0
},
"additionalProperty2": {
"size_in_bytes": 42.0
}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {
"memory_size_in_bytes": 42.0
},
"additionalProperty2": {
"memory_size_in_bytes": 42.0
}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
},
"additionalProperty2": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {
"size_in_bytes": 42.0
},
"additionalProperty2": {
"size_in_bytes": 42.0
}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {
"memory_size_in_bytes": 42.0
},
"additionalProperty2": {
"memory_size_in_bytes": 42.0
}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
},
"additionalProperty2": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"shards": {
"additionalProperty1": [
{
"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
},
"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": {},
"additionalProperty2": {}
}
],
"additionalProperty2": [
{
"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
},
"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": {},
"additionalProperty2": {}
}
]
},
"total": {
"completion": {
"size_in_bytes": 42.0,
"": 42.0,
"fields": {
"additionalProperty1": {
"size_in_bytes": 42.0
},
"additionalProperty2": {
"size_in_bytes": 42.0
}
}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {
"additionalProperty1": {
"memory_size_in_bytes": 42.0
},
"additionalProperty2": {
"memory_size_in_bytes": 42.0
}
}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string",
"": 42.0
},
"get": {
"current": 42.0,
"exists_time": "string",
"": 42.0,
"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",
"": 42.0,
"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
},
"additionalProperty1": {},
"additionalProperty2": {},
"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",
"": 42.0,
"total_throttled_time": "string",
"total_time": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"": 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",
"": 42.0
},
"refresh": {
"external_total": 42.0,
"": 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
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"": 42.0,
"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,
"": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {
"additionalProperty1": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
},
"additionalProperty2": {
"description": "string",
"size_in_bytes": 42.0,
"min_size_in_bytes": 42.0,
"max_size_in_bytes": 42.0,
"average_size_in_bytes": 42.0,
"count": 42.0
}
},
"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
},
"store": {
"": 42.0,
"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",
"": 42.0
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"": 42.0,
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shard_stats": {
"total_count": 42.0
}
},
"uuid": "string",
"health": "green",
"status": "open"
}
}
Remove policies from an index Added in 6.6.0
Remove the assigned lifecycle policies from an index or a data stream's backing indices. It also stops managing the indices.
Path parameters
-
The name of the index to remove policy on
curl \
--request POST http://api.example.com/{index}/_ilm/remove
{
"has_failures" : false,
"failed_indexes" : []
}
Stop the ILM plugin Added in 6.6.0
Halt all lifecycle management operations and stop the index lifecycle management plugin. This is useful when you are performing maintenance on the cluster and need to prevent ILM from performing any actions on your indices.
The API returns as soon as the stop request has been acknowledged, but the plugin might continue to run until in-progress operations complete and the plugin can be safely stopped. Use the get ILM status API to check whether ILM is running.
Query parameters
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request POST http://api.example.com/_ilm/stop
{
"acknowledged": true
}
Update an inference endpoint Added in 8.17.0
Modify task_settings
, secrets (within service_settings
), or num_allocations
for an inference endpoint, depending on the specific endpoint service and task_type
.
IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
Path parameters
-
The type of inference task that the model performs.
Values are
sparse_embedding
,text_embedding
,rerank
, orcompletion
. -
The unique identifier of the inference endpoint.
Body Required
-
The service type
-
Additional properties are allowed.
-
task_settings object
Additional properties are allowed.
curl \
--request POST http://api.example.com/_inference/{task_type}/{inference_id}/_update \
--header "Content-Type: application/json" \
--data '{"service":"string","service_settings":{},"task_settings":{}}'
{
"service": "string",
"service_settings": {},
"task_settings": {}
}
{
"service": "string",
"service_settings": {},
"task_settings": {},
"inference_id": "string",
"task_type": "sparse_embedding"
}
Path parameters
-
Pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of
*
.
Query parameters
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request DELETE http://api.example.com/_ingest/pipeline/{id}
{
"acknowledged": true
}
Simulate a pipeline Added in 5.0.0
Run an ingest pipeline against a set of provided documents. You can either specify an existing pipeline to use with the provided documents or supply a pipeline definition in the body of the request.
Path parameters
-
The pipeline to test. If you don't specify a
pipeline
in the request body, this parameter is required.
Query parameters
-
verbose boolean
If
true
, the response includes output data for each processor in the executed pipeline.
curl \
--request POST http://api.example.com/_ingest/pipeline/{id}/_simulate \
--header "Content-Type: application/json" \
--data '"{\n \"pipeline\" :\n {\n \"description\": \"_description\",\n \"processors\": [\n {\n \"set\" : {\n \"field\" : \"field2\",\n \"value\" : \"_value\"\n }\n }\n ]\n },\n \"docs\": [\n {\n \"_index\": \"index\",\n \"_id\": \"id\",\n \"_source\": {\n \"foo\": \"bar\"\n }\n },\n {\n \"_index\": \"index\",\n \"_id\": \"id\",\n \"_source\": {\n \"foo\": \"rab\"\n }\n }\n ]\n}"'
{
"pipeline" :
{
"description": "_description",
"processors": [
{
"set" : {
"field" : "field2",
"value" : "_value"
}
}
]
},
"docs": [
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "bar"
}
},
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "rab"
}
}
]
}
{
"docs": [
{
"doc": {
"_id": "id",
"_index": "index",
"_version": "-3",
"_source": {
"field2": "_value",
"foo": "bar"
},
"_ingest": {
"timestamp": "2017-05-04T22:30:03.187Z"
}
}
},
{
"doc": {
"_id": "id",
"_index": "index",
"_version": "-3",
"_source": {
"field2": "_value",
"foo": "rab"
},
"_ingest": {
"timestamp": "2017-05-04T22:30:03.188Z"
}
}
}
]
}
Start a basic license Added in 6.3.0
Start an indefinite basic license, which gives access to all the basic features.
NOTE: In order to start a basic license, you must not currently have a basic license.
If the basic license does not support all of the features that are available with your current license, however, you are notified in the response.
You must then re-submit the API request with the acknowledge
parameter set to true
.
To check the status of your basic license, use the get basic license API.
Query parameters
-
acknowledge boolean
whether the user has acknowledged acknowledge messages (default: false)
-
master_timeout string
Period to wait for a connection to the master node.
-
timeout string
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/_license/start_basic
{
"acknowledged": true,
"basic_was_started": true
}
Logstash
Logstash APIs enable you to manage pipelines that are used by Logstash Central Management.
Create a calendar Added in 6.2.0
Path parameters
-
A string that uniquely identifies a calendar.
Body
-
job_ids array[string]
An array of anomaly detection job identifiers.
-
description string
A description of the calendar.
curl \
--request PUT http://api.example.com/_ml/calendars/{calendar_id} \
--header "Content-Type: application/json" \
--data '{"job_ids":["string"],"description":"string"}'
{
"job_ids": [
"string"
],
"description": "string"
}
{
"calendar_id": "string",
"description": "string",
"": "string"
}
Get calendar configuration info Added in 6.2.0
Path parameters
-
A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using
_all
or*
or by omitting the calendar identifier.
curl \
--request POST http://api.example.com/_ml/calendars/{calendar_id} \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'
{
"page": {
"from": 42.0,
"size": 42.0
}
}
{
"calendars": [
{
"calendar_id": "string",
"description": "string",
"job_ids": [
"string"
]
}
],
"count": 42.0
}
Get anomaly detection job results for categories Added in 5.4.0
Path parameters
-
Identifier for the anomaly detection job.
Query parameters
-
from number
Skips the specified number of categories.
-
partition_field_value string
Only return categories for the specified partition.
-
size number
Specifies the maximum number of categories to obtain.
curl \
--request GET http://api.example.com/_ml/anomaly_detectors/{job_id}/results/categories \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'
{
"page": {
"from": 42.0,
"size": 42.0
}
}
{
"categories": [
{
"category_id": 42.0,
"examples": [
"string"
],
"grok_pattern": "string",
"job_id": "string",
"max_matching_length": 42.0,
"partition_field_name": "string",
"partition_field_value": "string",
"regex": "string",
"terms": "string",
"num_matches": 42.0,
"preferred_to_categories": [
"string"
],
"p": "string",
"result_type": "string",
"mlcategory": "string"
}
],
"count": 42.0
}
Get anomaly detection job results for categories Added in 5.4.0
Path parameters
-
Identifier for the anomaly detection job.
Query parameters
-
from number
Skips the specified number of categories.
-
partition_field_value string
Only return categories for the specified partition.
-
size number
Specifies the maximum number of categories to obtain.
curl \
--request POST http://api.example.com/_ml/anomaly_detectors/{job_id}/results/categories \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'
{
"page": {
"from": 42.0,
"size": 42.0
}
}
{
"categories": [
{
"category_id": 42.0,
"examples": [
"string"
],
"grok_pattern": "string",
"job_id": "string",
"max_matching_length": 42.0,
"partition_field_name": "string",
"partition_field_value": "string",
"regex": "string",
"terms": "string",
"num_matches": 42.0,
"preferred_to_categories": [
"string"
],
"p": "string",
"result_type": "string",
"mlcategory": "string"
}
],
"count": 42.0
}
Get anomaly detection job model snapshot upgrade usage info Added in 7.16.0
Path parameters
-
Identifier for the anomaly detection job.
-
A numerical character string that uniquely identifies the model snapshot. You can get information for multiple snapshots by using a comma-separated list or a wildcard expression. You can get all snapshots by using
_all
, by specifying*
as the snapshot ID, or by omitting the snapshot ID.
Query parameters
-
allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs that match.
- Contains the _all string or no identifiers and there are no matches.
- Contains wildcard expressions and there are only partial matches.
The default value is true, which returns an empty jobs array when there are no matches and the subset of results when there are partial matches. If this parameter is false, the request returns a 404 status code when there are no matches or only partial matches.
curl \
--request GET http://api.example.com/_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_upgrade/_stats
{
"count": 42.0,
"model_snapshot_upgrades": [
{
"job_id": "string",
"snapshot_id": "string",
"state": "loading_old_state",
"node": {
"additionalProperty1": {
"name": "string",
"ephemeral_id": "string",
"transport_address": "string",
"external_id": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"roles": [
"string"
],
"version": "string",
"min_index_version": 42.0,
"max_index_version": 42.0
},
"additionalProperty2": {
"name": "string",
"ephemeral_id": "string",
"transport_address": "string",
"external_id": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"roles": [
"string"
],
"version": "string",
"min_index_version": 42.0,
"max_index_version": 42.0
}
},
"assignment_explanation": "string"
}
]
}
Open anomaly detection jobs Added in 5.4.0
An anomaly detection job must be opened to be ready to receive and analyze data. It can be opened and closed multiple times throughout its lifecycle. When you open a new job, it starts with an empty model. When you open an existing job, the most recent model state is automatically loaded. The job is ready to resume its analysis from where it left off, once new data is received.
Path parameters
-
Identifier for the anomaly detection job.
Query parameters
-
timeout string
Controls the time to wait until a job has opened.
curl \
--request POST http://api.example.com/_ml/anomaly_detectors/{job_id}/_open \
--header "Content-Type: application/json" \
--data '{"timeout":"35m"}'
{
"timeout": "35m"
}
{
"node": "node-1",
"opened": true
}
Reset an anomaly detection job Added in 7.14.0
All model state and results are deleted. The job is ready to start over as if it had just been created. It is not currently possible to reset multiple jobs using wildcards or a comma separated list.
Path parameters
-
The ID of the job to reset.
Query parameters
-
wait_for_completion boolean
Should this request wait until the operation has completed before returning.
-
delete_user_annotations boolean
Specifies whether annotations that have been added by the user should be deleted along with any auto-generated annotations when the job is reset.
curl \
--request POST http://api.example.com/_ml/anomaly_detectors/{job_id}/_reset
{
"acknowledged": true
}
Start datafeeds Added in 5.5.0
A datafeed must be started in order to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.
Before you can start a datafeed, the anomaly detection job must be open. Otherwise, an error occurs.
If you restart a stopped datafeed, it continues processing input data from the next millisecond after it was stopped. If new data was indexed for that exact millisecond between stopping and starting, it will be ignored.
When Elasticsearch security features are enabled, your datafeed remembers which roles the last user to create or update it had at the time of creation or update and runs the query using those same roles. If you provided secondary authorization headers when you created or updated the datafeed, those credentials are used instead.
Path parameters
-
A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.
Query parameters
-
end string | number
The time that the datafeed should end, which can be specified by using one of the following formats:
- ISO 8601 format with milliseconds, for example
2017-01-22T06:00:00.000Z
- ISO 8601 format without milliseconds, for example
2017-01-22T06:00:00+00:00
- Milliseconds since the epoch, for example
1485061200000
Date-time arguments using either of the ISO 8601 formats must have a time zone designator, where
Z
is accepted as an abbreviation for UTC time. When a URL is expected (for example, in browsers), the+
used in time zone designators must be encoded as%2B
. The end time value is exclusive. If you do not specify an end time, the datafeed runs continuously. - ISO 8601 format with milliseconds, for example
-
start string | number
The time that the datafeed should begin, which can be specified by using the same formats as the
end
parameter. This value is inclusive. If you do not specify a start time and the datafeed is associated with a new anomaly detection job, the analysis starts from the earliest time for which data is available. If you restart a stopped datafeed and specify a start value that is earlier than the timestamp of the latest processed record, the datafeed continues from 1 millisecond after the timestamp of the latest processed record. -
timeout string
Specifies the amount of time to wait until a datafeed starts.
Body
end string | number
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
start string | number
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
-
timeout string
A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
curl \
--request POST http://api.example.com/_ml/datafeeds/{datafeed_id}/_start \
--header "Content-Type: application/json" \
--data '{"":"string","timeout":"string"}'
{
"": "string",
"timeout": "string"
}
{
"node": "string",
"started": true
}
Get data frame analytics job configuration info Added in 7.3.0
You can get information for multiple data frame analytics jobs in a single API request by using a comma-separated list of data frame analytics jobs or a wildcard expression.
Query parameters
-
allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no data frame analytics jobs that match.
- Contains the
_all
string or no identifiers and there are no matches. - Contains wildcard expressions and there are only partial matches.
The default value returns an empty data_frame_analytics array when there are no matches and the subset of results when there are partial matches. If this parameter is
false
, the request returns a 404 status code when there are no matches or only partial matches. -
from number
Skips the specified number of data frame analytics jobs.
-
size number
Specifies the maximum number of data frame analytics jobs to obtain.
-
exclude_generated boolean
Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.
curl \
--request GET http://api.example.com/_ml/data_frame/analytics
{
"count": 42.0,
"data_frame_analytics": [
{
"allow_lazy_start": true,
"analysis": {
"": {
"alpha": 42.0,
"dependent_variable": "string",
"downsample_factor": 42.0,
"early_stopping_enabled": true,
"eta": 42.0,
"eta_growth_rate_per_tree": 42.0,
"feature_bag_fraction": 42.0,
"feature_processors": [
{}
],
"gamma": 42.0,
"lambda": 42.0,
"max_optimization_rounds_per_hyperparameter": 42.0,
"max_trees": 42.0,
"num_top_feature_importance_values": 42.0,
"prediction_field_name": "string",
"randomize_seed": 42.0,
"soft_tree_depth_limit": 42.0,
"soft_tree_depth_tolerance": 42.0,
"loss_function": "string",
"loss_function_parameter": 42.0
},
"outlier_detection": {
"compute_feature_influence": true,
"feature_influence_threshold": 42.0,
"method": "string",
"n_neighbors": 42.0,
"outlier_fraction": 42.0,
"standardization_enabled": true
}
},
"analyzed_fields": {
"includes": [
"string"
],
"excludes": [
"string"
]
},
"authorization": {
"api_key": {
"id": "string",
"name": "string"
},
"roles": [
"string"
],
"service_account": "string"
},
"": 42.0,
"description": "string",
"dest": {
"index": "string",
"results_field": "string"
},
"id": "string",
"max_num_threads": 42.0,
"model_memory_limit": "string",
"source": {
"index": "string",
"runtime_mappings": {
"additionalProperty1": {
"fields": {},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {},
"type": "boolean"
},
"additionalProperty2": {
"fields": {},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {},
"type": "boolean"
}
},
"_source": {
"includes": [
"string"
],
"excludes": [
"string"
]
},
"query": {}
},
"version": "string",
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
]
}
Prepare a node to be shut down Added in 7.13.0
NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
If you specify a node that is offline, it will be prepared for shut down when it rejoins the cluster.
If the operator privileges feature is enabled, you must be an operator to use this API.
The API migrates ongoing tasks and index shards to other nodes as needed to prepare a node to be restarted or shut down and removed from the cluster. This ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.
You must specify the type of shutdown: restart
, remove
, or replace
.
If a node is already being prepared for shutdown, you can use this API to change the shutdown type.
IMPORTANT: This API does NOT terminate the Elasticsearch process. Monitor the node shutdown status to determine when it is safe to stop Elasticsearch.
Path parameters
-
The node identifier. This parameter is not validated against the cluster's active nodes. This enables you to register a node for shut down while it is offline. No error is thrown if you specify an invalid node ID.
Query parameters
-
master_timeout string
The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
. -
timeout string
The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
Body Required
-
Values are
restart
,remove
, orreplace
. -
A human-readable reason that the node is being shut down. This field provides information for other cluster operators; it does not affect the shut down process.
-
allocation_delay string
Only valid if type is restart. Controls how long Elasticsearch will wait for the node to restart and join the cluster before reassigning its shards to other nodes. This works the same as delaying allocation with the index.unassigned.node_left.delayed_timeout setting. If you specify both a restart allocation delay and an index-level allocation delay, the longer of the two is used.
-
target_node_name string
Only valid if type is replace. Specifies the name of the node that is replacing the node being shut down. Shards from the shut down node are only allowed to be allocated to the target node, and no other data will be allocated to the target node. During relocation of data certain allocation rules are ignored, such as disk watermarks or user attribute filtering rules.
curl \
--request PUT http://api.example.com/_nodes/{node_id}/shutdown \
--header "Content-Type: application/json" \
--data '{"type":"restart","reason":"string","allocation_delay":"string","target_node_name":"string"}'
{
"type": "restart",
"reason": "string",
"allocation_delay": "string",
"target_node_name": "string"
}
{
"acknowledged": true
}
Delete a query ruleset Added in 8.10.0
Remove a query ruleset and its associated data. This is a destructive action that is not recoverable.
Path parameters
-
The unique identifier of the query ruleset to delete
curl \
--request DELETE http://api.example.com/_query_rules/{ruleset_id}
{
"acknowledged": true
}
Create a rollup job Deprecated Technical preview
WARNING: From 8.15.0, calling this API in a cluster with no rollup usage will fail with a message about the deprecation and planned removal of rollup features. A cluster needs to contain either a rollup job or a rollup index in order for this API to be allowed to run.
The rollup job configuration contains all the details about how the job should run, when it indexes documents, and what future queries will be able to run against the rollup index.
There are three main sections to the job configuration: the logistical details about the job (for example, the cron schedule), the fields that are used for grouping, and what metrics to collect for each group.
Jobs are created in a STOPPED
state. You can start them with the start rollup jobs API.
Path parameters
-
Identifier for the rollup job. This can be any alphanumeric string and uniquely identifies the data that is associated with the rollup job. The ID is persistent; it is stored with the rolled up data. If you create a job, let it run for a while, then delete the job, the data that the job rolled up is still be associated with this job ID. You cannot create a new job with the same ID since that could lead to problems with mismatched job configurations.
Body Required
-
A cron string which defines the intervals when the rollup job should be executed. When the interval triggers, the indexer attempts to rollup the data in the index pattern. The cron pattern is unrelated to the time interval of the data being rolled up. For example, you may wish to create hourly rollups of your document but to only run the indexer on a daily basis at midnight, as defined by the cron. The cron pattern is defined just like a Watcher cron schedule.
-
Additional properties are allowed.
-
The index or index pattern to roll up. Supports wildcard-style patterns (
logstash-*
). The job attempts to rollup the entire index or index-pattern. -
metrics array[object]
Defines the metrics to collect for each grouping tuple. By default, only the doc_counts are collected for each group. To make rollup useful, you will often add metrics like averages, mins, maxes, etc. Metrics are defined on a per-field basis and for each field you configure which metric should be collected.
-
The number of bucket results that are processed on each iteration of the rollup indexer. A larger value tends to execute faster, but requires more memory during processing. This value has no effect on how the data is rolled up; it is merely used for tweaking the speed or memory cost of the indexer.
-
timeout string
A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. -
headers object
curl \
--request PUT http://api.example.com/_rollup/job/{id} \
--header "Content-Type: application/json" \
--data '{"cron":"string","groups":{"date_histogram":{"delay":"string","field":"string","format":"string","interval":"string","calendar_interval":"string","fixed_interval":"string","time_zone":"string"},"histogram":{"fields":"string","interval":42.0},"terms":{"fields":"string"}},"index_pattern":"string","metrics":[{"field":"string","metrics":["min"]}],"page_size":42.0,"rollup_index":"string","timeout":"string","headers":{}}'
{
"cron": "string",
"groups": {
"date_histogram": {
"delay": "string",
"field": "string",
"format": "string",
"interval": "string",
"calendar_interval": "string",
"fixed_interval": "string",
"time_zone": "string"
},
"histogram": {
"fields": "string",
"interval": 42.0
},
"terms": {
"fields": "string"
}
},
"index_pattern": "string",
"metrics": [
{
"field": "string",
"metrics": [
"min"
]
}
],
"page_size": 42.0,
"rollup_index": "string",
"timeout": "string",
"headers": {}
}
{
"acknowledged": true
}
Run a script Technical preview
Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.
Each context requires a script, but additional parameters depend on the context you're using for that script.
Body
-
context string
Values are
painless_test
,filter
,score
,boolean_field
,date_field
,double_field
,geo_point_field
,ip_field
,keyword_field
,long_field
, orcomposite_field
. -
context_setup object
Additional properties are allowed.
-
script object
Additional properties are allowed.
curl \
--request GET http://api.example.com/_scripts/painless/_execute \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"source\": \"params.count / params.total\",\n \"params\": {\n \"count\": 100.0,\n \"total\": 1000.0\n }\n }\n}"'
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
{
"script": {
"source": "doc['field'].value.length() <= params.max_length",
"params": {
"max_length": 4
}
},
"context": "filter",
"context_setup": {
"index": "my-index-000001",
"document": {
"field": "four"
}
}
}
{
"script": {
"source": "doc['rank'].value / params.max_rank",
"params": {
"max_rank": 5.0
}
},
"context": "score",
"context_setup": {
"index": "my-index-000001",
"document": {
"rank": 4
}
}
}
{
"result": "0.1"
}
{
"result": true
}
{
"result": 0.8
}
Run a script Technical preview
Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.
Each context requires a script, but additional parameters depend on the context you're using for that script.
Body
-
context string
Values are
painless_test
,filter
,score
,boolean_field
,date_field
,double_field
,geo_point_field
,ip_field
,keyword_field
,long_field
, orcomposite_field
. -
context_setup object
Additional properties are allowed.
-
script object
Additional properties are allowed.
curl \
--request POST http://api.example.com/_scripts/painless/_execute \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"source\": \"params.count / params.total\",\n \"params\": {\n \"count\": 100.0,\n \"total\": 1000.0\n }\n }\n}"'
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
{
"script": {
"source": "doc['field'].value.length() <= params.max_length",
"params": {
"max_length": 4
}
},
"context": "filter",
"context_setup": {
"index": "my-index-000001",
"document": {
"field": "four"
}
}
}
{
"script": {
"source": "doc['rank'].value / params.max_rank",
"params": {
"max_rank": 5.0
}
},
"context": "score",
"context_setup": {
"index": "my-index-000001",
"document": {
"rank": 4
}
}
}
{
"result": "0.1"
}
{
"result": true
}
{
"result": 0.8
}
Clear a scrolling search
Clear the search context and results for a scrolling search.
curl \
--request DELETE http://api.example.com/_search/scroll \
--header "Content-Type: application/json" \
--data '"{\n \"scroll_id\": \"DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==\"\n}"'
{
"scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}
{
"succeeded": true,
"num_freed": 42.0
}
Run a scrolling search
IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the search_after
parameter with a point in time (PIT).
The scroll API gets large sets of results from a single scrolling search request.
To get the necessary scroll ID, submit a search API request that includes an argument for the scroll
query parameter.
The scroll
parameter indicates how long Elasticsearch should retain the search context for the request.
The search response returns a scroll ID in the _scroll_id
response body parameter.
You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request.
If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.
You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.
IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.
Path parameters
-
The scroll ID
Query parameters
-
scroll string
The period to retain the search context for scrolling.
-
The scroll ID for scrolled search
-
rest_total_hits_as_int boolean
If true, the API response’s hit.total property is returned as an integer. If false, the API response’s hit.total property is returned as an object.
curl \
--request POST http://api.example.com/_search/scroll/{scroll_id} \
--header "Content-Type: application/json" \
--data '"{\n \"scroll_id\" : \"DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==\"\n}"'
{
"scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}
{
"took": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
},
"hits": {
"total": {
"relation": "eq",
"value": 42.0
},
"hits": [
{
"_index": "string",
"_id": "string",
"_score": 42.0,
"_explanation": {
"description": "string",
"details": [
{}
],
"value": 42.0
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"highlight": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"inner_hits": {
"additionalProperty1": {
"hits": {}
},
"additionalProperty2": {
"hits": {}
}
},
"matched_queries": [
"string"
],
"_nested": {
"field": "string",
"offset": 42.0,
"_nested": {}
},
"_ignored": [
"string"
],
"ignored_field_values": {
"additionalProperty1": [
{}
],
"additionalProperty2": [
{}
]
},
"_shard": "string",
"_node": "string",
"_routing": "string",
"_source": {},
"_rank": 42.0,
"_seq_no": 42.0,
"_primary_term": 42.0,
"_version": 42.0,
"sort": [
42.0
]
}
],
"max_score": 42.0
},
"aggregations": {},
"_clusters": {
"skipped": 42.0,
"successful": 42.0,
"total": 42.0,
"running": 42.0,
"partial": 42.0,
"failed": 42.0,
"details": {
"additionalProperty1": {
"status": "running",
"indices": "string",
"": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{}
],
"skipped": 42.0
},
"failures": [
{
"index": "string",
"node": "string",
"reason": {},
"shard": 42.0,
"status": "string"
}
]
},
"additionalProperty2": {
"status": "running",
"indices": "string",
"": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{}
],
"skipped": 42.0
},
"failures": [
{
"index": "string",
"node": "string",
"reason": {},
"shard": 42.0,
"status": "string"
}
]
}
}
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"max_score": 42.0,
"num_reduce_phases": 42.0,
"profile": {
"shards": [
{
"aggregations": [
{
"breakdown": {},
"description": "string",
"type": "string",
"debug": {},
"children": [
{}
]
}
],
"cluster": "string",
"dfs": {
"statistics": {
"type": "string",
"description": "string",
"time": "string",
"breakdown": {},
"debug": {},
"children": [
{}
]
},
"knn": [
{}
]
},
"fetch": {
"type": "string",
"description": "string",
"": 42.0,
"breakdown": {
"load_source": 42.0,
"load_source_count": 42.0,
"load_stored_fields": 42.0,
"load_stored_fields_count": 42.0,
"next_reader": 42.0,
"next_reader_count": 42.0,
"process_count": 42.0,
"process": 42.0
},
"debug": {
"stored_fields": [
"string"
],
"fast_path": 42.0
},
"children": [
{}
]
},
"id": "string",
"index": "string",
"node_id": "string",
"searches": [
{
"collector": [
{}
],
"query": [
{}
],
"rewrite_time": 42.0
}
],
"shard_id": 42.0
}
]
},
"pit_id": "string",
"_scroll_id": "string",
"suggest": {
"additionalProperty1": [
{
"length": 42.0,
"offset": 42.0,
"text": "string"
}
],
"additionalProperty2": [
{
"length": 42.0,
"offset": 42.0,
"text": "string"
}
]
},
"terminated_early": true
}
Count search results
Get the number of documents matching a query.
The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.
The query is optional. When no query is provided, the API uses match_all
to count all the documents.
The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.
The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. -
analyzer string
The analyzer to use for the query string. This parameter can be used only when the
q
query string parameter is specified. -
analyze_wildcard boolean
If
true
, wildcard and prefix queries are analyzed. This parameter can be used only when theq
query string parameter is specified. -
default_operator string
The default operator for query string query:
AND
orOR
. This parameter can be used only when theq
query string parameter is specified.Values are
and
,AND
,or
, orOR
. -
df string
The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the
q
query string parameter is specified. -
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as
open,hidden
. -
If
true
, concrete, expanded, or aliased indices are ignored when frozen. -
lenient boolean
If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theq
query string parameter is specified. -
min_score number
The minimum
_score
value that documents must have to be included in the result. -
preference string
The node or shard the operation should be performed on. By default, it is random.
-
routing string
A custom value used to route operations to a specific shard.
-
terminate_after number
The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
-
q string
The query in Lucene query string syntax. This parameter cannot be used with a request body.
curl \
--request POST http://api.example.com/_count \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"term\" : { \"user.id\" : \"kimchy\" }\n }\n}"'
{
"query" : {
"term" : { "user.id" : "kimchy" }
}
}
{
"count": 1,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
}
}
Count search results
Get the number of documents matching a query.
The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.
The query is optional. When no query is provided, the API uses match_all
to count all the documents.
The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.
The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count.
Path parameters
-
A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (
*
). To search all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. -
analyzer string
The analyzer to use for the query string. This parameter can be used only when the
q
query string parameter is specified. -
analyze_wildcard boolean
If
true
, wildcard and prefix queries are analyzed. This parameter can be used only when theq
query string parameter is specified. -
default_operator string
The default operator for query string query:
AND
orOR
. This parameter can be used only when theq
query string parameter is specified.Values are
and
,AND
,or
, orOR
. -
df string
The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the
q
query string parameter is specified. -
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as
open,hidden
. -
If
true
, concrete, expanded, or aliased indices are ignored when frozen. -
lenient boolean
If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theq
query string parameter is specified. -
min_score number
The minimum
_score
value that documents must have to be included in the result. -
preference string
The node or shard the operation should be performed on. By default, it is random.
-
routing string
A custom value used to route operations to a specific shard.
-
terminate_after number
The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
-
q string
The query in Lucene query string syntax. This parameter cannot be used with a request body.
curl \
--request GET http://api.example.com/{index}/_count \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"term\" : { \"user.id\" : \"kimchy\" }\n }\n}"'
{
"query" : {
"term" : { "user.id" : "kimchy" }
}
}
{
"count": 1,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
}
}
Explain a document match result
Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.
Path parameters
-
Index names that are used to limit the request. Only a single index name can be provided to this parameter.
-
The document identifier.
Query parameters
-
analyzer string
The analyzer to use for the query string. This parameter can be used only when the
q
query string parameter is specified. -
analyze_wildcard boolean
If
true
, wildcard and prefix queries are analyzed. This parameter can be used only when theq
query string parameter is specified. -
default_operator string
The default operator for query string query:
AND
orOR
. This parameter can be used only when theq
query string parameter is specified.Values are
and
,AND
,or
, orOR
. -
df string
The field to use as default where no field prefix is given in the query string. This parameter can be used only when the
q
query string parameter is specified. -
lenient boolean
If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theq
query string parameter is specified. -
preference string
The node or shard the operation should be performed on. It is random by default.
-
routing string
A custom value used to route operations to a specific shard.
-
_source boolean | string | array[string]
True
orfalse
to return the_source
field or not or a list of fields to return. -
_source_excludes string | array[string]
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 isfalse
, this parameter is ignored. -
_source_includes string | array[string]
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 isfalse
, this parameter is ignored. -
stored_fields string | array[string]
A comma-separated list of stored fields to return in the response.
-
q string
The query in the Lucene query string syntax.
curl \
--request GET http://api.example.com/{index}/_explain/{id} \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"match\" : { \"message\" : \"elasticsearch\" }\n }\n}"'
{
"query" : {
"match" : { "message" : "elasticsearch" }
}
}
{
"_index":"my-index-000001",
"_id":"0",
"matched":true,
"explanation":{
"value":1.6943598,
"description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
"details":[
{
"value":1.6943598,
"description":"score(freq=1.0), computed as boost * idf * tf from:",
"details":[
{
"value":2.2,
"description":"boost",
"details":[]
},
{
"value":1.3862944,
"description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
"details":[
{
"value":1,
"description":"n, number of documents containing term",
"details":[]
},
{
"value":5,
"description":"N, total number of documents with field",
"details":[]
}
]
},
{
"value":0.5555556,
"description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
"details":[
{
"value":1.0,
"description":"freq, occurrences of term within document",
"details":[]
},
{
"value":1.2,
"description":"k1, term saturation parameter",
"details":[]
},
{
"value":0.75,
"description":"b, length normalization parameter",
"details":[]
},
{
"value":3.0,
"description":"dl, length of field",
"details":[]
},
{
"value":5.4,
"description":"avgdl, average length of field",
"details":[]
}
]
}
]
}
]
}
}
Run multiple searches Added in 1.3.0
The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. The structure is as follows:
header\n
body\n
header\n
body\n
This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.
IMPORTANT: The final line of data must end with a newline character \n
.
Each newline character may be preceded by a carriage return \r
.
When sending requests to this endpoint the Content-Type
header should be set to application/x-ndjson
.
Query parameters
-
allow_no_indices boolean
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
-
ccs_minimize_roundtrips boolean
If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
-
expand_wildcards string | array[string]
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
-
ignore_throttled boolean
If true, concrete, expanded or aliased indices are ignored when frozen.
-
include_named_queries_score boolean
Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
-
max_concurrent_searches number
Maximum number of concurrent searches the multi search API can execute.
-
Maximum number of concurrent shard requests that each sub-search request executes per node.
-
pre_filter_shard_size number
Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
-
rest_total_hits_as_int boolean
If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
-
routing string
Custom routing value used to route search operations to a specific shard.
-
search_type string
Indicates whether global term and document frequencies should be used when scoring returned documents.
Values are
query_then_fetch
ordfs_query_then_fetch
. -
typed_keys boolean
Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
Body object Required
-
allow_no_indices boolean
-
expand_wildcards string | array[string]
-
index string | array[string]
-
preference string
-
request_cache boolean
-
routing string
-
search_type string
Values are
query_then_fetch
ordfs_query_then_fetch
. -
ccs_minimize_roundtrips boolean
-
allow_partial_search_results boolean
-
ignore_throttled boolean
curl \
--request POST http://api.example.com/_msearch \
--header "Content-Type: application/json" \
--data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'
[
{
"allow_no_indices": true,
"expand_wildcards": "string",
"ignore_unavailable": true,
"index": "string",
"preference": "string",
"request_cache": true,
"routing": "string",
"search_type": "query_then_fetch",
"ccs_minimize_roundtrips": true,
"allow_partial_search_results": true,
"ignore_throttled": true
}
]
{
"took": 42.0,
"responses": [
{
"took": 42.0,
"timed_out": true,
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{}
],
"skipped": 42.0
},
"hits": {
"hits": [
{}
]
},
"aggregations": {},
"_clusters": {
"skipped": 42.0,
"successful": 42.0,
"total": 42.0,
"running": 42.0,
"partial": 42.0,
"failed": 42.0,
"details": {}
},
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"max_score": 42.0,
"num_reduce_phases": 42.0,
"profile": {
"shards": [
{}
]
},
"pit_id": "string",
"_scroll_id": "string",
"suggest": {
"additionalProperty1": [
{}
],
"additionalProperty2": [
{}
]
},
"terminated_early": true,
"status": 42.0
}
]
}
Get search application details Beta
Path parameters
-
The name of the search application
curl \
--request GET http://api.example.com/_application/search_application/{name}
{
"name": "my-app",
"indices": [ "index1", "index2" ],
"updated_at_millis": 1682105622204,
"template": {
"script": {
"source": {
"query": {
"query_string": {
"query": "{{query_string}}",
"default_field": "{{default_field}}"
}
}
},
"lang": "mustache",
"options": {
"content_type": "application/json;charset=utf-8"
},
"params": {
"query_string": "*",
"default_field": "*"
}
}
}
}
Get search applications Beta
Get information about search applications.
curl \
--request GET http://api.example.com/_application/search_application
{
"count": 2,
"results": [
{
"name": "app-1",
"updated_at_millis": 1690981129366
},
{
"name": "app-2",
"updated_at_millis": 1691501823939
}
]
}
Authenticate a user Added in 5.5.0
Authenticates a user and returns information about the authenticated user. Include the user information in a basic auth header. A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user. If the user cannot be authenticated, this API returns a 401 status code.
curl \
--request GET http://api.example.com/_security/_authenticate
{
"api_key": {
"id": "string",
"name": "string"
},
"authentication_realm": {
"name": "string",
"type": "string"
},
"email": "string",
"full_name": "string",
"lookup_realm": {
"name": "string",
"type": "string"
},
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"roles": [
"string"
],
"username": "string",
"enabled": true,
"authentication_type": "string",
"token": {
"name": "string",
"type": "string"
}
}
Get roles
Get roles in the native realm. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The get roles API cannot retrieve roles that are defined in roles files.
curl \
--request GET http://api.example.com/_security/role
{
"additionalProperty1": {
"cluster": [
"string"
],
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_cluster": [
{
"clusters": "string",
"privileges": [
"monitor_enrich"
]
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"role_templates": [
{
"format": "string",
"template": {
"source": "string",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": "painless",
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
}
}
],
"global": {
"additionalProperty1": {
"additionalProperty1": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"additionalProperty2": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
}
},
"additionalProperty2": {
"additionalProperty1": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"additionalProperty2": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
}
}
}
},
"additionalProperty2": {
"cluster": [
"string"
],
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_cluster": [
{
"clusters": "string",
"privileges": [
"monitor_enrich"
]
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"role_templates": [
{
"format": "string",
"template": {
"source": "string",
"id": "string",
"params": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"": "painless",
"options": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
}
}
],
"global": {
"additionalProperty1": {
"additionalProperty1": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"additionalProperty2": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
}
},
"additionalProperty2": {
"additionalProperty1": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
},
"additionalProperty2": {
"additionalProperty1": [
"string"
],
"additionalProperty2": [
"string"
]
}
}
}
}
}
Create an API key Added in 6.7.0
Create an API key for access without requiring basic authentication.
IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error.
A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds.
NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.
The API keys are created by the Elasticsearch API key service, which is automatically enabled. To configure or turn off the API key service, refer to API key service setting documentation.
Query parameters
-
refresh string
If
true
(the default) then refresh the affected shards to make this operation visible to search, ifwait_for
then wait for a refresh to make this operation visible to search, iffalse
then do nothing with refreshes.Values are
true
,false
, orwait_for
.
Body Required
-
expiration string
A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. -
name string
-
role_descriptors object
An array of role descriptors for this API key. When it is not specified or it is an empty array, the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the authenticated user's permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for the create role API. For more details, refer to the create or update roles API.
NOTE: Due to the way in which this permission intersection is calculated, it is not possible to create an API key that is a child of another API key, unless the derived key is created without any privileges. In this case, you must explicitly specify a role descriptor with no privileges. The derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.
-
metadata object
curl \
--request PUT http://api.example.com/_security/api_key \
--header "Content-Type: application/json" \
--data '{"expiration":"string","name":"string","role_descriptors":{"additionalProperty1":{"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_indices":[{"clusters":"string","field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_cluster":[{"clusters":"string","privileges":["monitor_enrich"]}],"global":[{"application":{"manage":{}}}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","restriction":{"workflows":["string"]},"transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}},"additionalProperty2":{"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_indices":[{"clusters":"string","field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_cluster":[{"clusters":"string","privileges":["monitor_enrich"]}],"global":[{"application":{"manage":{}}}],"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","restriction":{"workflows":["string"]},"transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}}},"metadata":{"additionalProperty1":{},"additionalProperty2":{}}}'
{
"expiration": "string",
"name": "string",
"role_descriptors": {
"additionalProperty1": {
"cluster": [
"string"
],
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_cluster": [
{
"clusters": "string",
"privileges": [
"monitor_enrich"
]
}
],
"global": [
{
"application": {
"manage": {}
}
}
],
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"description": "string",
"restriction": {
"workflows": [
"string"
]
},
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"cluster": [
"string"
],
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_cluster": [
{
"clusters": "string",
"privileges": [
"monitor_enrich"
]
}
],
"global": [
{
"application": {
"manage": {}
}
}
],
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"description": "string",
"restriction": {
"workflows": [
"string"
]
},
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
},
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
{
"api_key": "string",
"expiration": 42.0,
"id": "string",
"name": "string",
"encoded": "string"
}
Create a service account token
Create a service accounts token for access without requiring basic authentication.
NOTE: Service account tokens never expire. You must actively delete them if they are no longer needed.
Path parameters
-
The name of the namespace, which is a top-level grouping of service accounts.
-
The name of the service.
-
The name for the service account token. If omitted, a random name will be generated.
Token names must be at least one and no more than 256 characters. They can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (
-
), and underscores (_
), but cannot begin with an underscore.NOTE: Token names must be unique in the context of the associated service account. They must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as
<namespace>/<service>/<token-name>
.
Query parameters
-
refresh string
If
true
then refresh the affected shards to make this operation visible to search, ifwait_for
(the default) then wait for a refresh to make this operation visible to search, iffalse
then do nothing with refreshes.Values are
true
,false
, orwait_for
.
curl \
--request PUT http://api.example.com/_security/service/{namespace}/{service}/credential/token/{name}
{
"created": true,
"token": {
"name": "string",
"value": "string"
}
}
Create or update users
Add and update users in the native realm. A password is required for adding a new user but is optional when updating an existing user. To change a user's password without updating any other fields, use the change password API.
Path parameters
-
An identifier for the user.
NOTE: Usernames must be at least 1 and no more than 507 characters. They can contain alphanumeric characters (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic Latin (ASCII) block. Leading or trailing whitespace is not allowed.
Query parameters
-
refresh string
Valid values are
true
,false
, andwait_for
. These values have the same meaning as in the index API, but the default value for this API is true.Values are
true
,false
, orwait_for
.
Body Required
-
username string
-
metadata object
-
password string
-
password_hash string
A hash of the user's password. This must be produced using the same hashing algorithm as has been configured for password storage. For more details, see the explanation of the
xpack.security.authc.password_hashing.algorithm
setting in the user cache and password hash algorithm documentation. Using this parameter allows the client to pre-hash the password for performance and/or confidentiality reasons. Thepassword
parameter and thepassword_hash
parameter cannot be used in the same request. -
roles array[string]
A set of roles the user has. The roles determine the user's access permissions. To create a user without any roles, specify an empty list (
[]
). -
enabled boolean
Specifies whether the user is enabled.
curl \
--request POST http://api.example.com/_security/user/{username} \
--header "Content-Type: application/json" \
--data '{"username":"string","email":"string","full_name":"string","metadata":{"additionalProperty1":{},"additionalProperty2":{}},"password":"string","password_hash":"string","roles":["string"],"enabled":true}'
{
"username": "string",
"email": "string",
"full_name": "string",
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"password": "string",
"password_hash": "string",
"roles": [
"string"
],
"enabled": true
}
{
"created": true
}
Get application privileges Added in 6.4.0
To use this API, you must have one of the following privileges:
- The
read_security
cluster privilege (or a greater privilege such asmanage_security
orall
). - The "Manage Application Privileges" global privilege for the application being referenced in the request.
curl \
--request GET http://api.example.com/_security/privilege
{
"additionalProperty1": {
"additionalProperty1": {
"actions": [
"string"
],
"application": "string",
"name": "string",
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"actions": [
"string"
],
"application": "string",
"name": "string",
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
},
"additionalProperty2": {
"additionalProperty1": {
"actions": [
"string"
],
"application": "string",
"name": "string",
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"actions": [
"string"
],
"application": "string",
"name": "string",
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
}
}
Get service accounts Added in 7.13.0
Get a list of service accounts that match the provided path parameters.
NOTE: Currently, only the elastic/fleet-server
service account is available.
curl \
--request GET http://api.example.com/_security/service
{
"additionalProperty1": {
"role_descriptor": {
"cluster": [
"string"
],
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_cluster": [
{
"clusters": "string",
"privileges": [
"monitor_enrich"
]
}
],
"global": [
{
"application": {}
}
],
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"description": "string",
"restriction": {
"workflows": [
"string"
]
},
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
},
"additionalProperty2": {
"role_descriptor": {
"cluster": [
"string"
],
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_cluster": [
{
"clusters": "string",
"privileges": [
"monitor_enrich"
]
}
],
"global": [
{
"application": {}
}
],
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"description": "string",
"restriction": {
"workflows": [
"string"
]
},
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
}
}
Invalidate SAML Added in 7.5.0
Submit a SAML LogoutRequest message to Elasticsearch for consumption.
NOTE: This API is intended for use by custom web applications other than Kibana. If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
The logout request comes from the SAML IdP during an IdP initiated Single Logout.
The custom web application can use this API to have Elasticsearch process the LogoutRequest
.
After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message.
Thus the user can be redirected back to their IdP.
Body Required
-
acs string
The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the
realm
parameter. -
The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. This query should include a single parameter named
SAMLRequest
that contains a SAML logout request that is deflated and Base64 encoded. If the SAML IdP has signed the logout request, the URL should include two extra parameters namedSigAlg
andSignature
that contain the algorithm used for the signature and the signature value itself. In order for Elasticsearch to be able to verify the IdP's signature, the value of thequery_string
field must be an exact match to the string provided by the browser. The client application must not attempt to parse or process the string in any way. -
realm string
The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the
acs
parameter.
curl \
--request POST http://api.example.com/_security/saml/invalidate \
--header "Content-Type: application/json" \
--data '{"acs":"string","query_string":"string","realm":"string"}'
{
"acs": "string",
"query_string": "string",
"realm": "string"
}
{
"invalidated": 42.0,
"realm": "string",
"redirect": "string"
}
Suggest a user profile Added in 8.2.0
Get suggestions for user profiles that match specified search criteria.
NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.
Query parameters
-
data string | array[string]
A comma-separated list of filters for the
data
field of the profile document. To return all content usedata=*
. To return a subset of content, usedata=<key>
to retrieve content nested under the specified<key>
. By default, the API returns nodata
content. It is an error to specifydata
as both the query parameter and the request body field.
Body
-
name string
A query string used to match name-related fields in user profile documents. Name-related fields are the user's
username
,full_name
, andemail
. -
size number
The number of profiles to return.
data string | array[string]
A comma-separated list of filters for the
data
field of the profile document. To return all content usedata=*
. To return a subset of content, usedata=<key>
to retrieve content nested under the specified<key>
. By default, the API returns nodata
content. It is an error to specifydata
as both the query parameter and the request body field.-
hint object
Additional properties are allowed.
curl \
--request GET http://api.example.com/_security/profile/_suggest \
--header "Content-Type: application/json" \
--data '{"name":"string","size":42.0,"data":"string","hint":{"uids":["string"],"labels":{}}}'
{
"name": "string",
"size": 42.0,
"data": "string",
"hint": {
"uids": [
"string"
],
"labels": {}
}
}
{
"total": {
"value": 42.0,
"relation": "string"
},
"took": 42.0,
"profiles": [
{
"uid": "string",
"user": {
"email": "string",
"full_name": "string",
"realm_name": "string",
"realm_domain": "string",
"roles": [
"string"
],
"username": "string"
},
"data": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"labels": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"enabled": true
}
]
}
Delete snapshots
Path parameters
-
The name of the repository to delete a snapshot from.
-
A comma-separated list of snapshot names to delete. It also accepts wildcards (
*
).
Query parameters
-
master_timeout string
The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1
.
curl \
--request DELETE http://api.example.com/_snapshot/{repository}/{snapshot}
{
"acknowledged": true
}
Create or update a snapshot repository Added in 0.0.0
IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.
To register a snapshot repository, the cluster's global metadata must be writeable.
Ensure there are no cluster blocks (for example, cluster.blocks.read_only
and clsuter.blocks.read_only_allow_delete
settings) that prevent write access.
Several options for this API can be specified using a query parameter or a request body parameter. If both parameters are specified, only the query parameter is used.
Path parameters
-
The name of the snapshot repository to register or update.
Query parameters
-
master_timeout string
The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1
. -
timeout string
The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. To indicate that the request should never timeout, set it to
-1
. -
verify boolean
If
true
, the request verifies the repository is functional on all master and data nodes in the cluster. Iffalse
, this verification is skipped. You can also perform this verification with the verify snapshot repository API.
curl \
--request POST http://api.example.com/_snapshot/{repository} \
--header "Content-Type: application/json" \
--data '{"uuid":"string","type":"azure","":{"":42.0,"compress":true,"base_path":"string","client":"string","container":"string","delete_objects_max_size":42.0,"location_mode":"string","max_concurrent_batch_deletes":42.0,"readonly":true}}'
{
"uuid": "string",
"type": "azure",
"": {
"": 42.0,
"compress": true,
"base_path": "string",
"client": "string",
"container": "string",
"delete_objects_max_size": 42.0,
"location_mode": "string",
"max_concurrent_batch_deletes": 42.0,
"readonly": true
}
}
{
"uuid": "string",
"type": "gcs",
"": {
"": 42.0,
"compress": true,
"bucket": "string",
"application_name": "string",
"base_path": "string",
"client": "string",
"readonly": true
}
}
{
"uuid": "string",
"type": "s3",
"": {
"": 42.0,
"compress": true,
"bucket": "string",
"base_path": "string",
"canned_acl": "string",
"client": "string",
"delete_objects_max_size": 42.0,
"get_register_retry_delay": "string",
"max_multipart_parts": 42.0,
"max_multipart_upload_cleanup_size": 42.0,
"readonly": true,
"server_side_encryption": true,
"storage_class": "string",
"throttled_delete_retry.delay_increment": "string",
"throttled_delete_retry.maximum_delay": "string",
"throttled_delete_retry.maximum_number_of_retries": 42.0
}
}
{
"uuid": "string",
"type": "fs",
"": {
"": 42.0,
"compress": true,
"location": "string",
"max_number_of_snapshots": 42.0,
"readonly": true
}
}
{
"uuid": "string",
"type": "url",
"": {
"": 42.0,
"compress": true,
"http_max_retries": 42.0,
"http_socket_timeout": "string",
"max_number_of_snapshots": 42.0,
"url": "string"
}
}
{
"uuid": "string",
"type": "source",
"": {
"": 42.0,
"compress": true,
"delegate_type": "string",
"max_number_of_snapshots": 42.0,
"read_only": true
}
}
{
"acknowledged": true
}
Get the snapshot status Added in 7.8.0
Get a detailed description of the current state for each shard participating in the snapshot.
Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.
If you omit the <snapshot>
request path parameter, the request retrieves information only for currently running snapshots.
This usage is preferred.
If needed, you can specify <repository>
and <snapshot>
to retrieve information for specific snapshots, even if they're not currently running.
WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).
Depending on the latency of your storage, such requests can take an extremely long time to return results. These requests can also tax machine resources and, when using cloud storage, incur high processing costs.
Path parameters
-
The snapshot repository name used to limit the request. It supports wildcards (
*
) if<snapshot>
isn't specified.
Query parameters
-
master_timeout string
The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1
.
curl \
--request GET http://api.example.com/_snapshot/{repository}/_status
{
"snapshots": [
{
"include_global_state": true,
"indices": {
"additionalProperty1": {
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shards_stats": {
"done": 42.0,
"failed": 42.0,
"finalizing": 42.0,
"initializing": 42.0,
"started": 42.0,
"total": 42.0
},
"stats": {
"incremental": {},
"time": "string",
"total": {}
}
},
"additionalProperty2": {
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shards_stats": {
"done": 42.0,
"failed": 42.0,
"finalizing": 42.0,
"initializing": 42.0,
"started": 42.0,
"total": 42.0
},
"stats": {
"incremental": {},
"time": "string",
"total": {}
}
}
},
"repository": "string",
"shards_stats": {
"done": 42.0,
"failed": 42.0,
"finalizing": 42.0,
"initializing": 42.0,
"started": 42.0,
"total": 42.0
},
"snapshot": "string",
"state": "string",
"stats": {
"incremental": {
"file_count": 42.0,
"size_in_bytes": 42.0
},
"": 42.0,
"time": "string",
"total": {
"file_count": 42.0,
"size_in_bytes": 42.0
}
},
"uuid": "string"
}
]
}
Get policy information Added in 7.4.0
Get snapshot lifecycle policy definitions and information about the latest snapshot attempts.
Query parameters
-
master_timeout string
The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET http://api.example.com/_slm/policy
{
"additionalProperty1": {
"in_progress": {
"name": "string",
"": 42.0,
"state": "string",
"uuid": "string"
},
"last_failure": {
"snapshot_name": "string",
"": "string"
},
"last_success": {
"snapshot_name": "string",
"": "string"
},
"": 42.0,
"policy": {
"config": {
"ignore_unavailable": true,
"indices": "string",
"include_global_state": true,
"feature_states": [
"string"
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"partial": true
},
"name": "string",
"repository": "string",
"retention": {
"expire_after": "string",
"max_count": 42.0,
"min_count": 42.0
},
"schedule": "string"
},
"version": 42.0,
"stats": {
"retention_deletion_time": "string",
"": 42.0,
"retention_failed": 42.0,
"retention_runs": 42.0,
"retention_timed_out": 42.0,
"policy": "string",
"total_snapshots_deleted": 42.0,
"total_snapshot_deletion_failures": 42.0,
"total_snapshots_failed": 42.0,
"total_snapshots_taken": 42.0
}
},
"additionalProperty2": {
"in_progress": {
"name": "string",
"": 42.0,
"state": "string",
"uuid": "string"
},
"last_failure": {
"snapshot_name": "string",
"": "string"
},
"last_success": {
"snapshot_name": "string",
"": "string"
},
"": 42.0,
"policy": {
"config": {
"ignore_unavailable": true,
"indices": "string",
"include_global_state": true,
"feature_states": [
"string"
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"partial": true
},
"name": "string",
"repository": "string",
"retention": {
"expire_after": "string",
"max_count": 42.0,
"min_count": 42.0
},
"schedule": "string"
},
"version": 42.0,
"stats": {
"retention_deletion_time": "string",
"": 42.0,
"retention_failed": 42.0,
"retention_runs": 42.0,
"retention_timed_out": 42.0,
"policy": "string",
"total_snapshots_deleted": 42.0,
"total_snapshot_deletion_failures": 42.0,
"total_snapshots_failed": 42.0,
"total_snapshots_taken": 42.0
}
}
}
Synonyms
The synonyms management API provides a convenient way to define and manage synonyms in an internal system index. Related synonyms can be grouped in a "synonyms set". Create as many synonym sets as you need.
Test a Grok pattern Added in 8.13.0
Test a Grok pattern on one or more lines of text. The API indicates whether the lines match the pattern together with the offsets and lengths of the matched substrings.
Query parameters
-
ecs_compatibility string
The mode of compatibility with ECS compliant Grok patterns. Use this parameter to specify whether to use ECS Grok patterns instead of legacy ones when the structure finder creates a Grok pattern. Valid values are
disabled
andv1
.
Body Required
-
The lines of text to run the Grok pattern on.
curl \
--request GET http://api.example.com/_text_structure/test_grok_pattern \
--header "Content-Type: application/json" \
--data '{"grok_pattern":"string","text":["string"]}'
{
"grok_pattern": "string",
"text": [
"string"
]
}
{
"matches": [
{
"matched": true,
"fields": {
"additionalProperty1": [
{
"match": "string",
"offset": 42.0,
"length": 42.0
}
],
"additionalProperty2": [
{
"match": "string",
"offset": 42.0,
"length": 42.0
}
]
}
}
]
}
Get usage information
Get information about the features that are currently enabled and available under the current license. The API also provides some usage statistics.
Query parameters
-
master_timeout string
The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1
.
curl \
--request GET http://api.example.com/_xpack/usage
{
"aggregate_metric": {
"available": true,
"enabled": true
},
"": {
"available": true,
"enabled": true,
"dense_vector_dims_avg_count": 42.0,
"dense_vector_fields_count": 42.0,
"sparse_vector_fields_count": 42.0
},
"data_frame": {
"available": true,
"enabled": true
},
"data_science": {
"available": true,
"enabled": true
},
"enrich": {
"available": true,
"enabled": true
},
"graph": {
"available": true,
"enabled": true
},
"ilm": {
"policy_count": 42.0,
"policy_stats": [
{
"indices_managed": 42.0,
"phases": {
"cold": {
"actions": [
"string"
]
},
"delete": {
"actions": [
"string"
]
},
"frozen": {
"actions": [
"string"
]
},
"hot": {
"actions": [
"string"
]
},
"warm": {
"actions": [
"string"
]
}
}
}
]
},
"logstash": {
"available": true,
"enabled": true
},
"rollup": {
"available": true,
"enabled": true
},
"spatial": {
"available": true,
"enabled": true
},
"transform": {
"available": true,
"enabled": true
},
"voting_only": {
"available": true,
"enabled": true
}
}
Watcher
You can use Watcher to watch for changes or anomalies in your data and perform the necessary actions in response.
Acknowledge a watch
Acknowledging a watch enables you to manually throttle the execution of the watch's actions.
The acknowledgement state of an action is stored in the status.actions.<id>.ack.state
structure.
IMPORTANT: If the specified watch is currently being executed, this API will return an error The reason for this behavior is to prevent overwriting the watch status from a watch execution.
Acknowledging an action throttles further executions of that action until its ack.state
is reset to awaits_successful_execution
.
This happens when the condition of the watch is not met (the condition evaluates to false).
Path parameters
-
The watch identifier.
curl \
--request PUT http://api.example.com/_watcher/watch/{watch_id}/_ack
{
"status": {
"actions": {
"additionalProperty1": {
"ack": {
"state": "awaits_successful_execution",
"": "string"
},
"last_execution": {
"successful": true,
"": "string",
"reason": "string"
},
"last_successful_execution": {
"successful": true,
"": "string",
"reason": "string"
},
"last_throttle": {
"reason": "string",
"": "string"
}
},
"additionalProperty2": {
"ack": {
"state": "awaits_successful_execution",
"": "string"
},
"last_execution": {
"successful": true,
"": "string",
"reason": "string"
},
"last_successful_execution": {
"successful": true,
"": "string",
"reason": "string"
},
"last_throttle": {
"reason": "string",
"": "string"
}
}
},
"": "string",
"state": {
"active": true,
"": "string"
},
"version": 42.0,
"execution_state": "string"
}
}
Get Watcher index settings
Get settings for the Watcher internal index (.watches
).
Only a subset of settings are shown, for example index.auto_expand_replicas
and index.number_of_replicas
.
Query parameters
-
master_timeout string
The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET http://api.example.com/_watcher/settings
{
"index": {
"number_of_replicas": 0,
"auto_expand_replicas": "0-4"
}
}
Update Watcher index settings
Update settings for the Watcher internal index (.watches
).
Only a subset of settings can be modified.
This includes index.auto_expand_replicas
and index.number_of_replicas
.
Query parameters
-
master_timeout string
The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Body Required
-
index.auto_expand_replicas string
-
index.number_of_replicas number
curl \
--request PUT http://api.example.com/_watcher/settings \
--header "Content-Type: application/json" \
--data '{"index.auto_expand_replicas":"0-4"}'
{
"index.auto_expand_replicas": "0-4"
}
{
"acknowledged": true
}