http://api.example.comElasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.
This documentation is derived from the 8.18 branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.
This documentation contains work-in-progress information for future Elastic Stack releases.
Last update on Jul 9, 2025.
This API is provided under license Apache 2.0.
The API accepts 3 different authentication methods:
Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
DELETE /_autoscaling/policy/*
resp = client.autoscaling.delete_autoscaling_policy(
name="*",
)const response = await client.autoscaling.deleteAutoscalingPolicy({
name: "*",
});response = client.autoscaling.delete_autoscaling_policy(
name: "*"
)$resp = $client->autoscaling()->deleteAutoscalingPolicy([
"name" => "*",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_autoscaling/policy/*"{
"acknowledged": true
}NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
This API gets the current autoscaling capacity based on the configured autoscaling policy. It will return information to size the cluster appropriately to the current workload.
The required_capacity is calculated as the maximum of the required_capacity result of all individual deciders that are enabled for the policy.
The operator should verify that the current_nodes match the operator’s knowledge of the cluster to avoid making autoscaling decisions based on stale or incomplete information.
The response contains decider-specific information you can use to diagnose how and why autoscaling determined a certain capacity was required. This information is provided for diagnosis only. Do not use this information to make autoscaling decisions.
GET /_autoscaling/capacity
resp = client.autoscaling.get_autoscaling_capacity()const response = await client.autoscaling.getAutoscalingCapacity();response = client.autoscaling.get_autoscaling_capacity$resp = $client->autoscaling()->getAutoscalingCapacity();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_autoscaling/capacity"{
policies: {}
}PUT _application/analytics/my_analytics_collection
resp = client.search_application.put_behavioral_analytics(
name="my_analytics_collection",
)const response = await client.searchApplication.putBehavioralAnalytics({
name: "my_analytics_collection",
});response = client.search_application.put_behavioral_analytics(
name: "my_analytics_collection"
)$resp = $client->searchApplication()->putBehavioralAnalytics([
"name" => "my_analytics_collection",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection"All methods and paths for this operation:
Get the amount of heap memory currently used by the field data cache on every data node in the cluster.
IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes stats API.
monitorComma-separated list of fields used to limit returned information. To retrieve all fields, omit this parameter.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
Comma-separated list of fields used to limit returned information.
List of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
GET /_cat/fielddata?v=true&fields=body&format=json
resp = client.cat.fielddata(
v=True,
fields="body",
format="json",
)const response = await client.cat.fielddata({
v: "true",
fields: "body",
format: "json",
});response = client.cat.fielddata(
v: "true",
fields: "body",
format: "json"
)$resp = $client->cat()->fielddata([
"v" => "true",
"fields" => "body",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/fielddata?v=true&fields=body&format=json"client.cat().fielddata();
[
{
"id": "Nqk-6inXQq-OxUfOUI8jNQ",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "Nqk-6in",
"field": "body",
"size": "544b"
}
][
{
"id": "Nqk-6inXQq-OxUfOUI8jNQ",
"host": "1127.0.0.1",
"ip": "127.0.0.1",
"node": "Nqk-6in",
"field": "body",
"size": "544b"
},
{
"id": "Nqk-6inXQq-OxUfOUI8jNQ",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "Nqk-6in",
"field": "soul",
"size": "480b"
}
]curl \
--request GET 'http://api.example.com/_cat' \
--header "Authorization: $API_KEY"All methods and paths for this operation:
Get configuration and usage information about data frame analytics jobs.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API.
monitor_mlWhether to ignore if a wildcard expression matches no configs. (This includes _all string or when no configs have been specified)
The unit in which to display byte values
Values are b, kb, mb, gb, tb, or pb.
Comma-separated list of column names to display.
Supported values include:
assignment_explanation (or ae): Contains messages relating to the selection of a node.create_time (or ct, createTime): The time when the data frame analytics job was created.description (or d): A description of a job.dest_index (or di, destIndex): Name of the destination index.failure_reason (or fr, failureReason): Contains messages about the reason why a data frame analytics job failed.id: Identifier for the data frame analytics job.model_memory_limit (or mml, modelMemoryLimit): The approximate maximum amount of memory resources that are permitted for
the data frame analytics job.node.address (or na, nodeAddress): The network address of the node that the data frame analytics job is
assigned to.node.ephemeral_id (or ne, nodeEphemeralId): The ephemeral ID of the node that the data frame analytics job is assigned
to.node.id (or ni, nodeId): The unique identifier of the node that the data frame analytics job is
assigned to.node.name (or nn, nodeName): The name of the node that the data frame analytics job is assigned to.progress (or p): The progress report of the data frame analytics job by phase.source_index (or si, sourceIndex): Name of the source index.state (or s): Current state of the data frame analytics job.type (or t): The type of analysis that the data frame analytics job performs.version (or v): The Elasticsearch version number in which the data frame analytics job was
created.Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
assignment_explanation (or ae): Contains messages relating to the selection of a node.create_time (or ct, createTime): The time when the data frame analytics job was created.description (or d): A description of a job.dest_index (or di, destIndex): Name of the destination index.failure_reason (or fr, failureReason): Contains messages about the reason why a data frame analytics job failed.id: Identifier for the data frame analytics job.model_memory_limit (or mml, modelMemoryLimit): The approximate maximum amount of memory resources that are permitted for
the data frame analytics job.node.address (or na, nodeAddress): The network address of the node that the data frame analytics job is
assigned to.node.ephemeral_id (or ne, nodeEphemeralId): The ephemeral ID of the node that the data frame analytics job is assigned
to.node.id (or ni, nodeId): The unique identifier of the node that the data frame analytics job is
assigned to.node.name (or nn, nodeName): The name of the node that the data frame analytics job is assigned to.progress (or p): The progress report of the data frame analytics job by phase.source_index (or si, sourceIndex): Name of the source index.state (or s): Current state of the data frame analytics job.type (or t): The type of analysis that the data frame analytics job performs.version (or v): The Elasticsearch version number in which the data frame analytics job was
created.Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/ml/data_frame/analytics?v=true&format=json
resp = client.cat.ml_data_frame_analytics(
v=True,
format="json",
)const response = await client.cat.mlDataFrameAnalytics({
v: "true",
format: "json",
});response = client.cat.ml_data_frame_analytics(
v: "true",
format: "json"
)$resp = $client->cat()->mlDataFrameAnalytics([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/data_frame/analytics?v=true&format=json"client.cat().mlDataFrameAnalytics();
[
{
"id": "classifier_job_1",
"type": "classification",
"create_time": "2020-02-12T11:49:09.594Z",
"state": "stopped"
},
{
"id": "classifier_job_2",
"type": "classification",
"create_time": "2020-02-12T11:49:14.479Z",
"state": "stopped"
},
{
"id": "classifier_job_3",
"type": "classification",
"create_time": "2020-02-12T11:49:16.928Z",
"state": "stopped"
},
{
"id": "classifier_job_4",
"type": "classification",
"create_time": "2020-02-12T11:49:19.127Z",
"state": "stopped"
},
{
"id": "classifier_job_5",
"type": "classification",
"create_time": "2020-02-12T11:49:21.349Z",
"state": "stopped"
}
]List of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
Values are -1 or 0.
GET /_cat/nodeattrs?v=true&format=json
resp = client.cat.nodeattrs(
v=True,
format="json",
)const response = await client.cat.nodeattrs({
v: "true",
format: "json",
});response = client.cat.nodeattrs(
v: "true",
format: "json"
)$resp = $client->cat()->nodeattrs([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/nodeattrs?v=true&format=json"client.cat().nodeattrs();
[
{
"node": "node-0",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"attr": "testattr",
"value": "test"
}
][
{
"name": "node-0",
"pid": "19566",
"attr": "testattr",
"value": "test"
}
]The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
If true, return the full node ID. If false, return the shortened node ID.
If true, the response includes information from segments that are not loaded into memory.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
build (or b): The Elasticsearch build hash. For example: 5c03844.completion.size (or cs, completionSize): The size of completion. For example: 0b.cpu: The percentage of recent system CPU used.disk.avail (or d, disk, diskAvail): The available disk space. For example: 198.4gb.disk.total (or dt, diskTotal): The total disk space. For example: 458.3gb.disk.used (or du, diskUsed): The used disk space. For example: 259.8gb.disk.used_percent (or dup, diskUsedPercent): The percentage of disk space used.fielddata.evictions (or fe, fielddataEvictions): The number of fielddata cache evictions.fielddata.memory_size (or fm, fielddataMemory): The fielddata cache memory used. For example: 0b.file_desc.current (or fdc, fileDescriptorCurrent): The number of file descriptors used.file_desc.max (or fdm, fileDescriptorMax): The maximum number of file descriptors.file_desc.percent (or fdp, fileDescriptorPercent): The percentage of file descriptors used.flush.total (or ft, flushTotal): The number of flushes.flush.total_time (or ftt, flushTotalTime): The amount of time spent in flush.get.current (or gc, getCurrent): The number of current get operations.get.exists_time (or geti, getExistsTime): The time spent in successful get operations. For example: 14ms.get.exists_total (or geto, getExistsTotal): The number of successful get operations.get.missing_time (or gmti, getMissingTime): The time spent in failed get operations. For example: 0s.get.missing_total (or gmto, getMissingTotal): The number of failed get operations.get.time (or gti, getTime): The amount of time spent in get operations. For example: 14ms.get.total (or gto, getTotal): The number of get operations.heap.current (or hc, heapCurrent): The used heap size. For example: 311.2mb.heap.max (or hm, heapMax): The total heap size. For example: 4gb.heap.percent (or hp, heapPercent): The used percentage of total allocated Elasticsearch JVM heap.
This value reflects only the Elasticsearch process running within the operating system and is the most direct indicator of its JVM, heap, or memory resource performance.http_address (or http): The bound HTTP address.id (or nodeId): The identifier for the node.indexing.delete_current (or idc, indexingDeleteCurrent): The number of current deletion operations.indexing.delete_time (or idti, indexingDeleteTime): The time spent in deletion operations. For example: 2ms.indexing.delete_total (or idto, indexingDeleteTotal): The number of deletion operations.indexing.index_current (or iic, indexingIndexCurrent): The number of current indexing operations.indexing.index_failed (or iif, indexingIndexFailed): The number of failed indexing operations.indexing.index_failed_due_to_version_conflict (or iifvc, indexingIndexFailedDueToVersionConflict): The number of indexing operations that failed due to version conflict.indexing.index_time (or iiti, indexingIndexTime): The time spent in indexing operations. For example: 134ms.indexing.index_total (or iito, indexingIndexTotal): The number of indexing operations.ip (or i): The IP address.jdk (or j): The Java version. For example: 1.8.0.load_1m (or l): The most recent load average. For example: 0.22.load_5m (or l): The load average for the last five minutes. For example: 0.78.load_15m (or l): The load average for the last fifteen minutes. For example: 1.24.mappings.total_count (or mtc, mappingsTotalCount): The number of mappings, including runtime and object fields.mappings.total_estimated_overhead_in_bytes (or mteo, mappingsTotalEstimatedOverheadInBytes): The estimated heap overhead, in bytes, of mappings on this node, which allows for 1KiB of heap for every mapped field.master (or m): Indicates whether the node is the elected master node.
Returned values include * (elected master) and - (not elected master).merges.current (or mc, mergesCurrent): The number of current merge operations.merges.current_docs (or mcd, mergesCurrentDocs): The number of current merging documents.merges.current_size (or mcs, mergesCurrentSize): The size of current merges. For example: 0b.merges.total (or mt, mergesTotal): The number of completed merge operations.merges.total_docs (or mtd, mergesTotalDocs): The number of merged documents.merges.total_size (or mts, mergesTotalSize): The total size of merges. For example: 0b.merges.total_time (or mtt, mergesTotalTime): The time spent merging documents. For example: 0s.name (or n): The node name.node.role (or r, role, nodeRole): The roles of the node.
Returned values include c (cold node), d (data node), f (frozen node), h (hot node), i (ingest node), l (machine learning node), m (master-eligible node), r (remote cluster client node), s (content node), t (transform node), v (voting-only node), w (warm node), and - (coordinating node only).
For example, dim indicates a master-eligible data and ingest node.pid (or p): The process identifier.port (or po): The bound transport port number.query_cache.memory_size (or qcm, queryCacheMemory): The used query cache memory. For example: 0b.query_cache.evictions (or qce, queryCacheEvictions): The number of query cache evictions.query_cache.hit_count (or qchc, queryCacheHitCount): The query cache hit count.query_cache.miss_count (or qcmc, queryCacheMissCount): The query cache miss count.ram.current (or rc, ramCurrent): The used total memory. For example: 513.4mb.ram.max (or rm, ramMax): The total memory. For example: 2.9gb.ram.percent (or rp, ramPercent): The used percentage of the total operating system memory.
This reflects all processes running on the operating system instead of only Elasticsearch and is not guaranteed to correlate to its performance.refresh.total (or rto, refreshTotal): The number of refresh operations.refresh.time (or rti, refreshTime): The time spent in refresh operations. For example: 91ms.request_cache.memory_size (or rcm, requestCacheMemory): The used request cache memory. For example: 0b.request_cache.evictions (or rce, requestCacheEvictions): The number of request cache evictions.request_cache.hit_count (or rchc, requestCacheHitCount): The request cache hit count.request_cache.miss_count (or rcmc, requestCacheMissCount): The request cache miss count.script.compilations (or scrcc, scriptCompilations): The number of total script compilations.script.cache_evictions (or scrce, scriptCacheEvictions): The number of total compiled scripts evicted from cache.search.fetch_current (or sfc, searchFetchCurrent): The number of current fetch phase operations.search.fetch_time (or sfti, searchFetchTime): The time spent in fetch phase. For example: 37ms.search.fetch_total (or sfto, searchFetchTotal): The number of fetch operations.search.open_contexts (or so, searchOpenContexts): The number of open search contexts.search.query_current (or sqc, searchQueryCurrent): The number of current query phase operations.search.query_time (or sqti, searchQueryTime): The time spent in query phase. For example: 43ms.search.query_total (or sqto, searchQueryTotal): The number of query operations.search.scroll_current (or scc, searchScrollCurrent): The number of open scroll contexts.search.scroll_time (or scti, searchScrollTime): The amount of time scroll contexts were held open. For example: 2m.search.scroll_total (or scto, searchScrollTotal): The number of completed scroll contexts.segments.count (or sc, segmentsCount): The number of segments.segments.fixed_bitset_memory (or sfbm, fixedBitsetMemory): The memory used by fixed bit sets for nested object field types and type filters for types referred in join fields.
For example: 1.0kb.segments.index_writer_memory (or siwm, segmentsIndexWriterMemory): The memory used by the index writer. For example: 18mb.segments.memory (or sm, segmentsMemory): The memory used by segments. For example: 1.4kb.segments.version_map_memory (or svmm, segmentsVersionMapMemory): The memory used by the version map. For example: 1.0kb.shard_stats.total_count (or sstc, shards, shardStatsTotalCount): The number of shards assigned.suggest.current (or suc, suggestCurrent): The number of current suggest operations.suggest.time (or suti, suggestTime): The time spent in suggest operations.suggest.total (or suto, suggestTotal): The number of suggest operations.uptime (or u): The amount of node uptime. For example: 17.3m.version (or v): The Elasticsearch version. For example: 9.0.0.A comma-separated list of column names or aliases that determines the sort order.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The period to wait for a connection to the master node.
Values are -1 or 0.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET /_cat/nodes?v=true&h=id,ip,port,v,m&format=json
resp = client.cat.nodes(
v=True,
h="id,ip,port,v,m",
format="json",
)const response = await client.cat.nodes({
v: "true",
h: "id,ip,port,v,m",
format: "json",
});response = client.cat.nodes(
v: "true",
h: "id,ip,port,v,m",
format: "json"
)$resp = $client->cat()->nodes([
"v" => "true",
"h" => "id,ip,port,v,m",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/nodes?v=true&h=id,ip,port,v,m&format=json"client.cat().nodes();
[
{
"ip": "127.0.0.1",
"heap.percent": "65",
"ram.percent": "99",
"cpu": "42",
"load_1m": "3.07",
"load_5m": null,
"load_15m": null,
"node.role": "cdfhilmrstw",
"master": "*",
"name": "mJw06l1"
}
][
{
"id": "veJR",
"ip": "127.0.0.1",
"port": "59938",
"v": "9.0.0",
"m": "*"
}
]Get information about cluster-level changes that have not yet taken effect. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the pending cluster tasks API.
monitorList of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
Values are -1 or 0.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET /_cat/pending_tasks?v=trueh=insertOrder,timeInQueue,priority,source&format=json
resp = client.cat.pending_tasks(
v="trueh=insertOrder,timeInQueue,priority,source",
format="json",
)const response = await client.cat.pendingTasks({
v: "trueh=insertOrder,timeInQueue,priority,source",
format: "json",
});response = client.cat.pending_tasks(
v: "trueh=insertOrder,timeInQueue,priority,source",
format: "json"
)$resp = $client->cat()->pendingTasks([
"v" => "trueh=insertOrder,timeInQueue,priority,source",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/pending_tasks?v=trueh=insertOrder,timeInQueue,priority,source&format=json"client.cat().pendingTasks();
[
{ "insertOrder": "1685", "timeInQueue": "855ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1686", "timeInQueue": "843ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1693", "timeInQueue": "753ms", "priority": "HIGH", "source": "refresh-mapping [foo][[t]]"},
{ "insertOrder": "1688", "timeInQueue": "816ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1689", "timeInQueue": "802ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1690", "timeInQueue": "787ms", "priority": "HIGH", "source": "update-mapping [foo][t]"},
{ "insertOrder": "1691", "timeInQueue": "773ms", "priority": "HIGH", "source": "update-mapping [foo][t]"}
]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.
monitorList of columns to appear in the response. Supports simple wildcards.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
Include bootstrap plugins in the response
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
Period to wait for a connection to the master node.
Values are -1 or 0.
GET /_cat/plugins?v=true&s=component&h=name,component,version,description&format=json
resp = client.cat.plugins(
v=True,
s="component",
h="name,component,version,description",
format="json",
)const response = await client.cat.plugins({
v: "true",
s: "component",
h: "name,component,version,description",
format: "json",
});response = client.cat.plugins(
v: "true",
s: "component",
h: "name,component,version,description",
format: "json"
)$resp = $client->cat()->plugins([
"v" => "true",
"s" => "component",
"h" => "name,component,version,description",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/plugins?v=true&s=component&h=name,component,version,description&format=json"client.cat().plugins();
[
{ "name": "U7321H6", "component": "analysis-icu", "version": "8.17.0", "description": "The ICU Analysis plugin integrates the Lucene ICU module into Elasticsearch, adding ICU-related analysis components."},
{"name": "U7321H6", "component": "analysis-kuromoji", "verison": "8.17.0", description: "The Japanese (kuromoji) Analysis plugin integrates Lucene kuromoji analysis module into elasticsearch."},
{"name" "U7321H6", "component": "analysis-nori", "version": "8.17.0", "description": "The Korean (nori) Analysis plugin integrates Lucene nori analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-phonetic", "verison": "8.17.0", "description": "The Phonetic Analysis plugin integrates phonetic token filter analysis with elasticsearch."},
{"name": "U7321H6", "component": "analysis-smartcn", "verison": "8.17.0", "description": "Smart Chinese Analysis plugin integrates Lucene Smart Chinese analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-stempel", "verison": "8.17.0", "description": "The Stempel (Polish) Analysis plugin integrates Lucene stempel (polish) analysis module into elasticsearch."},
{"name": "U7321H6", "component": "analysis-ukrainian", "verison": "8.17.0", "description": "The Ukrainian Analysis plugin integrates the Lucene UkrainianMorfologikAnalyzer into elasticsearch."},
{"name": "U7321H6", "component": "discovery-azure-classic", "verison": "8.17.0", "description": "The Azure Classic Discovery plugin allows to use Azure Classic API for the unicast discovery mechanism"},
{"name": "U7321H6", "component": "discovery-ec2", "verison": "8.17.0", "description": "The EC2 discovery plugin allows to use AWS API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "discovery-gce", "verison": "8.17.0", "description": "The Google Compute Engine (GCE) Discovery plugin allows to use GCE API for the unicast discovery mechanism."},
{"name": "U7321H6", "component": "mapper-annotated-text", "verison": "8.17.0", "description": "The Mapper Annotated_text plugin adds support for text fields with markup used to inject annotation tokens into the index."},
{"name": "U7321H6", "component": "mapper-murmur3", "verison": "8.17.0", "description": "The Mapper Murmur3 plugin allows to compute hashes of a field's values at index-time and to store them in the index."},
{"name": "U7321H6", "component": "mapper-size", "verison": "8.17.0", "description": "The Mapper Size plugin allows document to record their uncompressed size at index time."},
{"name": "U7321H6", "component": "store-smb", "verison": "8.17.0", "description": "The Store SMB plugin adds support for SMB stores."}
]All methods and paths for this operation:
Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API.
monitormonitorA 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.
If true, the response only includes ongoing shard recoveries.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
If true, the response includes detailed information about shard recoveries.
Comma-separated list or wildcard expression of index names to limit the returned information
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
index (or i, idx): The name of the index.shard (or s, sh): The name of the shard.time (or t, ti, primaryOrReplica): The recovery time elasped.type: The type of recovery, from a peer or a snapshot.stage (or st): The stage of the recovery. Returned values are: INIT, INDEX: recovery of lucene files, either reusing local ones are copying new ones, VERIFY_INDEX: potentially running check index, TRANSLOG: starting up the engine, replaying the translog, FINALIZE: performing final task after all translog ops have been done, DONEsource_host (or shost): The host address the index is moving from.source_node (or snode): The node name the index is moving from.target_host (or thost): The host address the index is moving to.target_node (or tnode): The node name the index is moving to.repository (or tnode): The name of the repository being used. if not relevant 'n/a'.snapshot (or snap): The name of the snapshot being used. if not relevant 'n/a'.files (or f): The total number of files to recover.files_recovered (or fr): The number of files currently recovered.files_percent (or fp): The percentage of files currently recovered.files_total (or tf): The total number of files.bytes (or b): The total number of bytes to recover.bytes_recovered (or br): Total number of bytes currently recovered.bytes_percent (or bp): The percentage of bytes currently recovered.bytes_total (or tb): The total number of bytes.translog_ops (or to): The total number of translog ops to recover.translog_ops_recovered (or tor): The total number of translog ops currently recovered.translog_ops_percent (or top): The percentage of translog ops currently recovered.start_time (or start): The start time of the recovery operation.start_time_millis (or start_millis): The start time of the recovery operation in eopch milliseconds.stop_time (or stop): The end time of the recovery operation. If ongoing '1970-01-01T00:00:00.000Z'stop_time_millis (or stop_millis): The end time of the recovery operation in eopch milliseconds. If ongoing '0'Values are index, i, idx, shard, s, sh, time, t, ti, primaryOrReplica, type, stage, st, source_host, shost, source_node, snode, target_host, thost, target_node, tnode, repository, snapshot, snap, files, f, files_recovered, fr, files_percent, fp, files_total, tf, bytes, b, bytes_recovered, br, bytes_percent, bp, bytes_total, tb, translog_ops, to, translog_ops_recovered, tor, translog_ops_percent, top, start_time, start, start_time_millis, start_millis, stop_time, stop, stop_time_millis, or stop_millis.
A comma-separated list of column names or aliases that determines the sort order.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/recovery?v=true&format=json
resp = client.cat.recovery(
v=True,
format="json",
)const response = await client.cat.recovery({
v: "true",
format: "json",
});response = client.cat.recovery(
v: "true",
format: "json"
)$resp = $client->cat()->recovery([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/recovery?v=true&format=json"client.cat().recovery();
[
{
"index": "my-index-000001 ",
"shard": "0",
"time": "13ms",
"type": "store",
"stage": "done",
"source_host": "n/a",
"source_node": "n/a",
"target_host": "127.0.0.1",
"target_node": "node-0",
"repository": "n/a",
"snapshot": "n/a",
"files": "0",
"files_recovered": "0",
"files_percent": "100.0%",
"files_total": "13",
"bytes": "0b",
"bytes_recovered": "0b",
"bytes_percent": "100.0%",
"bytes_total": "9928b",
"translog_ops": "0",
"translog_ops_recovered": "0",
"translog_ops_percent": "100.0%"
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1252ms",
"ty": "peer",
"st": "done",
"shost": "192.168.1.1",
"thost": "192.168.1.1",
"f": "0",
"fp": "100.0%",
"b": "0b",
"bp": "100.0%",
}
][
{
"i": "my-index-000001",
"s": "0",
"t": "1978ms",
"ty": "snapshot",
"st": "done",
"rep": "my-repo",
"snap": "snap-1",
"f": "79",
"fp": "8.0%",
"b": "12086",
"bp": "9.0%"
}
]All methods and paths for this operation:
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.
monitormonitorA 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.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
List of columns to appear in the response. Supports simple wildcards.
Supported values include:
completion.size (or cs, completionSize): Size of completion. For example: 0b.dataset.size: Disk space used by the shard’s dataset, which may or may not be the size on
disk, but includes space used by the shard on object storage. Reported as a size value for example: 5kb.dense_vector.value_count (or dvc, denseVectorCount): Number of indexed dense vectors.docs (or d, dc): Number of documents in shard, for example: 25.fielddata.evictions (or fe, fielddataEvictions): Fielddata cache evictions, for example: 0.fielddata.memory_size (or fm, fielddataMemory): Used fielddata cache memory, for example: 0b.flush.total (or ft, flushTotal): Number of flushes, for example: 1.flush.total_time (or ftt, flushTotalTime): Time spent in flush, for example: 1.get.current (or gc, getCurrent): Number of current get operations, for example: 0.get.exists_time (or geti, getExistsTime): Time spent in successful gets, for example: 14ms.get.exists_total (or geto, getExistsTotal): Number of successful get operations, for example: 2.get.missing_time (or gmti, getMissingTime): Time spent in failed gets, for example: 0s.get.missing_total (or gmto, getMissingTotal): Number of failed get operations, for example: 1.get.time (or gti, getTime): Time spent in get, for example: 14ms.get.total (or gto, getTotal): Number of get operations, for example: 2.id: ID of the node, for example: k0zy.index (or i, idx): Name of the index.indexing.delete_current (or idc, indexingDeleteCurrent): Number of current deletion operations, for example: 0.indexing.delete_time (or idti, indexingDeleteTime): Time spent in deletions, for example: 2ms.indexing.delete_total (or idto, indexingDeleteTotal): Number of deletion operations, for example: 2.indexing.index_current (or iic, indexingIndexCurrent): Number of current indexing operations, for example: 0.indexing.index_failed_due_to_version_conflict (or iifvc, indexingIndexFailedDueToVersionConflict): Number of failed indexing operations due to version conflict, for example: 0.indexing.index_failed (or iif, indexingIndexFailed): Number of failed indexing operations, for example: 0.indexing.index_time (or iiti, indexingIndexTime): Time spent in indexing, such as for example: 134ms.indexing.index_total (or iito, indexingIndexTotal): Number of indexing operations, for example: 1.ip: IP address of the node, for example: 127.0.1.1.merges.current (or mc, mergesCurrent): Number of current merge operations, for example: 0.merges.current_docs (or mcd, mergesCurrentDocs): Number of current merging documents, for example: 0.merges.current_size (or mcs, mergesCurrentSize): Size of current merges, for example: 0b.merges.total (or mt, mergesTotal): Number of completed merge operations, for example: 0.merges.total_docs (or mtd, mergesTotalDocs): Number of merged documents, for example: 0.merges.total_size (or mts, mergesTotalSize): Size of current merges, for example: 0b.merges.total_time (or mtt, mergesTotalTime): Time spent merging documents, for example: 0s.node (or n): Node name, for example: I8hydUG.prirep (or p, pr, primaryOrReplica): Shard type. Returned values are primary or replica.query_cache.evictions (or qce, queryCacheEvictions): Query cache evictions, for example: 0.query_cache.memory_size (or qcm, queryCacheMemory): Used query cache memory, for example: 0b.recoverysource.type (or rs): Type of recovery source.refresh.time (or rti, refreshTime): Time spent in refreshes, for example: 91ms.refresh.total (or rto, refreshTotal): Number of refreshes, for example: 16.search.fetch_current (or sfc, searchFetchCurrent): Current fetch phase operations, for example: 0.search.fetch_time (or sfti, searchFetchTime): Time spent in fetch phase, for example: 37ms.search.fetch_total (or sfto, searchFetchTotal): Number of fetch operations, for example: 7.search.open_contexts (or so, searchOpenContexts): Open search contexts, for example: 0.search.query_current (or sqc, searchQueryCurrent): Current query phase operations, for example: 0.search.query_time (or sqti, searchQueryTime): Time spent in query phase, for example: 43ms.search.query_total (or sqto, searchQueryTotal): Number of query operations, for example: 9.search.scroll_current (or scc, searchScrollCurrent): Open scroll contexts, for example: 2.search.scroll_time (or scti, searchScrollTime): Time scroll contexts held open, for example: 2m.search.scroll_total (or scto, searchScrollTotal): Completed scroll contexts, for example: 1.segments.count (or sc, segmentsCount): Number of segments, for example: 4.segments.fixed_bitset_memory (or sfbm, fixedBitsetMemory): Memory used by fixed bit sets for nested object field types and type filters for types referred in join fields, for example: 1.0kb.segments.index_writer_memory (or siwm, segmentsIndexWriterMemory): Memory used by index writer, for example: 18mb.segments.memory (or sm, segmentsMemory): Memory used by segments, for example: 1.4kb.segments.version_map_memory (or svmm, segmentsVersionMapMemory): Memory used by version map, for example: 1.0kb.seq_no.global_checkpoint (or sqg, globalCheckpoint): Global checkpoint.seq_no.local_checkpoint (or sql, localCheckpoint): Local checkpoint.seq_no.max (or sqm, maxSeqNo): Maximum sequence number.shard (or s, sh): Name of the shard.dsparse_vector.value_count (or svc, sparseVectorCount): Number of indexed sparse vectors.state (or st): State of the shard. Returned values are:
INITIALIZING: The shard is recovering from a peer shard or gateway.RELOCATING: The shard is relocating.STARTED: The shard has started.UNASSIGNED: The shard is not assigned to any node.store (or sto): Disk space used by the shard, for example: 5kb.suggest.current (or suc, suggestCurrent): Number of current suggest operations, for example: 0.suggest.time (or suti, suggestTime): Time spent in suggest, for example: 0.suggest.total (or suto, suggestTotal): Number of suggest operations, for example: 0.sync_id: Sync ID of the shard.unassigned.at (or ua): Time at which the shard became unassigned in Coordinated Universal Time (UTC).unassigned.details (or ud): Details about why the shard became unassigned. This does not explain why the shard is currently unassigned. To understand why a shard
is not assigned, use the Cluster allocation explain API.unassigned.for (or uf): Time at which the shard was requested to be unassigned in Coordinated Universal Time (UTC).unassigned.reason (or ur): Indicates the reason for the last change to the state of this unassigned shard. This does not explain why the shard is currently unassigned.
To understand why a shard is not assigned, use the Cluster allocation explain API. Returned values include:
ALLOCATION_FAILED: Unassigned as a result of a failed allocation of the shard.CLUSTER_RECOVERED: Unassigned as a result of a full cluster recovery.DANGLING_INDEX_IMPORTED: Unassigned as a result of importing a dangling index.EXISTING_INDEX_RESTORED: Unassigned as a result of restoring into a closed index.FORCED_EMPTY_PRIMARY: The shard’s allocation was last modified by forcing an empty primary using the Cluster reroute API.INDEX_CLOSED: Unassigned because the index was closed.INDEX_CREATED: Unassigned as a result of an API creation of an index.INDEX_REOPENED: Unassigned as a result of opening a closed index.MANUAL_ALLOCATION: The shard’s allocation was last modified by the Cluster reroute API.NEW_INDEX_RESTORED: Unassigned as a result of restoring into a new index.NODE_LEFT: Unassigned as a result of the node hosting it leaving the cluster.NODE_RESTARTING: Similar to NODE_LEFT, except that the node was registered as restarting using the Node shutdown API.PRIMARY_FAILED: The shard was initializing as a replica, but the primary shard failed before the initialization completed.REALLOCATED_REPLICA: A better replica location is identified and causes the existing replica allocation to be cancelled.REINITIALIZED: When a shard moves from started back to initializing.REPLICA_ADDED: Unassigned as a result of explicit addition of a replica.REROUTE_CANCELLED: Unassigned as a result of explicit cancel reroute command.Values are completion.size, cs, completionSize, dataset.size, dense_vector.value_count, dvc, denseVectorCount, docs, d, dc, fielddata.evictions, fe, fielddataEvictions, fielddata.memory_size, fm, fielddataMemory, flush.total, ft, flushTotal, flush.total_time, ftt, flushTotalTime, get.current, gc, getCurrent, get.exists_time, geti, getExistsTime, get.exists_total, geto, getExistsTotal, get.missing_time, gmti, getMissingTime, get.missing_total, gmto, getMissingTotal, get.time, gti, getTime, get.total, gto, getTotal, id, index, i, idx, indexing.delete_current, idc, indexingDeleteCurrent, indexing.delete_time, idti, indexingDeleteTime, indexing.delete_total, idto, indexingDeleteTotal, indexing.index_current, iic, indexingIndexCurrent, indexing.index_failed_due_to_version_conflict, iifvc, indexingIndexFailedDueToVersionConflict, indexing.index_failed, iif, indexingIndexFailed, indexing.index_time, iiti, indexingIndexTime, indexing.index_total, iito, indexingIndexTotal, ip, merges.current, mc, mergesCurrent, merges.current_docs, mcd, mergesCurrentDocs, merges.current_size, mcs, mergesCurrentSize, merges.total, mt, mergesTotal, merges.total_docs, mtd, mergesTotalDocs, merges.total_size, mts, mergesTotalSize, merges.total_time, mtt, mergesTotalTime, node, n, prirep, p, pr, primaryOrReplica, query_cache.evictions, qce, queryCacheEvictions, query_cache.memory_size, qcm, queryCacheMemory, recoverysource.type, rs, refresh.time, rti, refreshTime, refresh.total, rto, refreshTotal, search.fetch_current, sfc, searchFetchCurrent, search.fetch_time, sfti, searchFetchTime, search.fetch_total, sfto, searchFetchTotal, search.open_contexts, so, searchOpenContexts, search.query_current, sqc, searchQueryCurrent, search.query_time, sqti, searchQueryTime, search.query_total, sqto, searchQueryTotal, search.scroll_current, scc, searchScrollCurrent, search.scroll_time, scti, searchScrollTime, search.scroll_total, scto, searchScrollTotal, segments.count, sc, segmentsCount, segments.fixed_bitset_memory, sfbm, fixedBitsetMemory, segments.index_writer_memory, siwm, segmentsIndexWriterMemory, segments.memory, sm, segmentsMemory, segments.version_map_memory, svmm, segmentsVersionMapMemory, seq_no.global_checkpoint, sqg, globalCheckpoint, seq_no.local_checkpoint, sql, localCheckpoint, seq_no.max, sqm, maxSeqNo, shard, s, sh, dsparse_vector.value_count, svc, sparseVectorCount, state, st, store, sto, suggest.current, suc, suggestCurrent, suggest.time, suti, suggestTime, suggest.total, suto, suggestTotal, sync_id, unassigned.at, ua, unassigned.details, ud, unassigned.for, uf, unassigned.reason, or ur.
A comma-separated list of column names or aliases that determines the sort order.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The period to wait for a connection to the master node.
Values are -1 or 0.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/shards?format=json
resp = client.cat.shards(
format="json",
)const response = await client.cat.shards({
format: "json",
});response = client.cat.shards(
format: "json"
)$resp = $client->cat()->shards([
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/shards?format=json"client.cat().shards();
[
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "RELOCATING",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA -> -> 192.168.56.30 bGG90GE"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"docs": "3014",
"store": "31.1mb",
"dataset": "249b",
"ip": "192.168.56.10",
"node": "H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "INITIALIZING",
"docs": "0",
"store": "14.3mb",
"dataset": "249b",
"ip": "192.168.56.30",
"node": "bGG90GE"
}
][
{
"index": "my-index-000001",
"shard": "0",
"prirep": "p",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.10 H5dfFeA"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.30 bGG90GE"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "STARTED",
"unassigned.reason": "3014 31.1mb 192.168.56.20 I8hydUG"
},
{
"index": "my-index-000001",
"shard": "0",
"prirep": "r",
"state": "UNASSIGNED",
"unassigned.reason": "ALLOCATION_FAILED"
}
]All methods and paths for this operation:
You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.
The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.
One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.
monitor,manageComma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported. To target all data streams and indices in a cluster, omit this parameter or use _all or *.
Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Can be one of cluster, indices or shards. Controls the details level of the health information returned.
Values are cluster, indices, or shards.
If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.
Values are all or index-setting.
Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.
Values are immediate, urgent, high, normal, low, or languid.
The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.
A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.
A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.
One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.
Supported values include:
green (or GREEN): All shards are assigned.yellow (or YELLOW): All primary shards are assigned, but one or more replica shards are unassigned. If a node in the cluster fails, some data could be unavailable until that node is repaired.red (or RED): One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.Values are green, GREEN, yellow, YELLOW, red, or RED.
GET _cluster/health
resp = client.cluster.health()const response = await client.cluster.health();response = client.cluster.health$resp = $client->cluster()->health();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/health"{
"cluster_name" : "testcluster",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 1,
"active_shards" : 1,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 1,
"delayed_unassigned_shards": 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch": 0,
"task_max_waiting_in_queue_millis": 0,
"active_shards_percent_as_number": 50.0
}Returns basic information about the cluster.
GET /_info/_all
resp = client.cluster.info(
target="_all",
)const response = await client.cluster.info({
target: "_all",
});response = client.cluster.info(
target: "_all"
)$resp = $client->cluster()->info([
"target" => "_all",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_info/_all"Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.
NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.
monitorIf true, the request retrieves information from the local node only.
If false, information is retrieved from the master node.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
GET /_cluster/pending_tasks
resp = client.cluster.pending_tasks()const response = await client.cluster.pendingTasks();response = client.cluster.pending_tasks$resp = $client->cluster()->pendingTasks();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/pending_tasks"Manually change the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.
It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as cluster.routing.rebalance.enable) in order to remain in a balanced state.
For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.
The cluster can be set to disable allocations using the cluster.routing.allocation.enable setting.
If allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.
The cluster will attempt to allocate a shard a maximum of index.allocation.max_retries times in a row (defaults to 5), before giving up and leaving the shard unallocated.
This scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.
Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the ?retry_failed URI query parameter, which will attempt a single retry round for these shards.
If true, then the request simulates the operation. It will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes.
If true, then the response contains an explanation of why the commands can or cannot run.
Limits the information returned to the specified metrics.
If true, then retries allocation of shards that are blocked due to too many subsequent allocation failures.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST /_cluster/reroute?metric=none
{
"commands": [
{
"move": {
"index": "test", "shard": 0,
"from_node": "node1", "to_node": "node2"
}
},
{
"allocate_replica": {
"index": "test", "shard": 1,
"node": "node3"
}
}
]
}resp = client.cluster.reroute(
metric="none",
commands=[
{
"move": {
"index": "test",
"shard": 0,
"from_node": "node1",
"to_node": "node2"
}
},
{
"allocate_replica": {
"index": "test",
"shard": 1,
"node": "node3"
}
}
],
)const response = await client.cluster.reroute({
metric: "none",
commands: [
{
move: {
index: "test",
shard: 0,
from_node: "node1",
to_node: "node2",
},
},
{
allocate_replica: {
index: "test",
shard: 1,
node: "node3",
},
},
],
});response = client.cluster.reroute(
metric: "none",
body: {
"commands": [
{
"move": {
"index": "test",
"shard": 0,
"from_node": "node1",
"to_node": "node2"
}
},
{
"allocate_replica": {
"index": "test",
"shard": 1,
"node": "node3"
}
}
]
}
)$resp = $client->cluster()->reroute([
"metric" => "none",
"body" => [
"commands" => array(
[
"move" => [
"index" => "test",
"shard" => 0,
"from_node" => "node1",
"to_node" => "node2",
],
],
[
"allocate_replica" => [
"index" => "test",
"shard" => 1,
"node" => "node3",
],
],
),
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"commands":[{"move":{"index":"test","shard":0,"from_node":"node1","to_node":"node2"}},{"allocate_replica":{"index":"test","shard":1,"node":"node3"}}]}' "$ELASTICSEARCH_URL/_cluster/reroute?metric=none"{
"commands": [
{
"move": {
"index": "test", "shard": 0,
"from_node": "node1", "to_node": "node2"
}
},
{
"allocate_replica": {
"index": "test", "shard": 1,
"node": "node3"
}
}
]
}All methods and paths for this operation:
Get comprehensive information about the state of the cluster.
The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.
The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. You may need to consult the Elasticsearch source code to determine the precise meaning of the response.
By default the API will route requests to the elected master node since this node is the authoritative source of cluster states.
You can also retrieve the cluster state held on the node handling the API request by adding the ?local=true query parameter.
Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. If you use this API repeatedly, your cluster may become unstable.
WARNING: The response is a representation of an internal data structure. Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. Do not query this API using external monitoring tools. Instead, obtain the information you require using other more stable cluster APIs.
monitor,manageLimit the information returned to the specified metrics
A comma-separated list of index names; use _all or empty string to perform the operation on all indices
Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Return settings in flat format (default: false)
Return local information, do not retrieve the state from master node (default: false)
Specify timeout for connection to master
Values are -1 or 0.
Wait for the metadata version to be equal or greater than the specified metadata version
The maximum time to wait for wait_for_metadata_version before timing out
Values are -1 or 0.
GET /_cluster/state?filter_path=metadata.cluster_coordination.last_committed_config
resp = client.cluster.state(
filter_path="metadata.cluster_coordination.last_committed_config",
)const response = await client.cluster.state({
filter_path: "metadata.cluster_coordination.last_committed_config",
});response = client.cluster.state(
filter_path: "metadata.cluster_coordination.last_committed_config"
)$resp = $client->cluster()->state([
"filter_path" => "metadata.cluster_coordination.last_committed_config",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/state?filter_path=metadata.cluster_coordination.last_committed_config"All methods and paths for this operation:
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).
monitorComma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.
Include remote cluster data into the response
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.
Values are -1 or 0.
GET _cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size*
resp = client.cluster.stats(
human=True,
filter_path="indices.mappings.total_deduplicated_mapping_size*",
)const response = await client.cluster.stats({
human: "true",
filter_path: "indices.mappings.total_deduplicated_mapping_size*",
});response = client.cluster.stats(
human: "true",
filter_path: "indices.mappings.total_deduplicated_mapping_size*"
)$resp = $client->cluster()->stats([
"human" => "true",
"filter_path" => "indices.mappings.total_deduplicated_mapping_size*",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/stats?human&filter_path=indices.mappings.total_deduplicated_mapping_size*"curl \
--request DELETE 'http://api.example.com/_nodes/{node_id}/_repositories_metering/{max_archive_version}' \
--header "Authorization: $API_KEY"Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.
monitor,managecurl \
--request GET 'http://api.example.com/_nodes/{node_id}/_repositories_metering' \
--header "Authorization: $API_KEY"All methods and paths for this operation:
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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST _nodes/reload_secure_settings
{
"secure_settings_password": "keystore-password"
}resp = client.nodes.reload_secure_settings(
secure_settings_password="keystore-password",
)const response = await client.nodes.reloadSecureSettings({
secure_settings_password: "keystore-password",
});response = client.nodes.reload_secure_settings(
body: {
"secure_settings_password": "keystore-password"
}
)$resp = $client->nodes()->reloadSecureSettings([
"body" => [
"secure_settings_password" => "keystore-password",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"secure_settings_password":"keystore-password"}' "$ELASTICSEARCH_URL/_nodes/reload_secure_settings"client.nodes().reloadSecureSettings(r -> r
.secureSettingsPassword("keystore-password")
);
{
"secure_settings_password": "keystore-password"
}{
"_nodes": {
"total": 1,
"successful": 1,
"failed": 0
},
"cluster_name": "my_cluster",
"nodes": {
"pQHNt5rXTTWNvUgOrdynKg": {
"name": "node-0"
}
}
}All methods and paths for this operation:
Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.
monitor,manageComma-separated list of node IDs or names used to limit returned information.
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.
Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.
Comma-separated list or wildcard expressions of fields to include in fielddata statistics.
Comma-separated list or wildcard expressions of fields to include in the statistics.
Comma-separated list of search groups to include in the search statistics.
If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).
Indicates whether statistics are aggregated at the cluster, index, or shard level.
Values are cluster, indices, or shards.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
A comma-separated list of document types for the indexing index metric.
If true, the response includes information from segments that are not loaded into memory.
GET _nodes/stats/process?filter_path=**.max_file_descriptors
resp = client.nodes.stats(
metric="process",
filter_path="**.max_file_descriptors",
)const response = await client.nodes.stats({
metric: "process",
filter_path: "**.max_file_descriptors",
});response = client.nodes.stats(
metric: "process",
filter_path: "**.max_file_descriptors"
)$resp = $client->nodes()->stats([
"metric" => "process",
"filter_path" => "**.max_file_descriptors",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_nodes/stats/process?filter_path=**.max_file_descriptors"All methods and paths for this operation:
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.
GET _health_report
resp = client.health_report()const response = await client.healthReport();response = client.health_report$resp = $client->healthReport();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_health_report"The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index. Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure:
This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
Update the last_seen field in the connector and set it to the current timestamp.
PUT _connector/my-connector/_check_in
resp = client.connector.check_in(
connector_id="my-connector",
)const response = await client.connector.checkIn({
connector_id: "my-connector",
});response = client.connector.check_in(
connector_id: "my-connector"
)$resp = $client->connector()->checkIn([
"connector_id" => "my-connector",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector/_check_in"{
"result": "updated"
}Removes a connector and associated sync jobs. This is a destructive action that is not recoverable. NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector. These need to be removed manually.
DELETE _connector/my-connector-id&delete_sync_jobs=true
resp = client.connector.delete(
connector_id="my-connector-id&delete_sync_jobs=true",
)const response = await client.connector.delete({
connector_id: "my-connector-id&delete_sync_jobs=true",
});response = client.connector.delete(
connector_id: "my-connector-id&delete_sync_jobs=true"
)$resp = $client->connector()->delete([
"connector_id" => "my-connector-id&delete_sync_jobs=true",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/my-connector-id&delete_sync_jobs=true"{
"acknowledged": true
}Set the error field for a connector sync job and set its status to error.
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.
PUT _connector/_sync_job/my-connector-sync-job/_error
{
"error": "some-error"
}resp = client.connector.sync_job_error(
connector_sync_job_id="my-connector-sync-job",
error="some-error",
)const response = await client.connector.syncJobError({
connector_sync_job_id: "my-connector-sync-job",
error: "some-error",
});response = client.connector.sync_job_error(
connector_sync_job_id: "my-connector-sync-job",
body: {
"error": "some-error"
}
)$resp = $client->connector()->syncJobError([
"connector_sync_job_id" => "my-connector-sync-job",
"body" => [
"error" => "some-error",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"error":"some-error"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_error"client.connector().syncJobError(s -> s
.connectorSyncJobId("my-connector-sync-job")
.error("some-error")
);
{
"error": "some-error"
}curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_activate' \
--header "Authorization: $API_KEY"PUT _connector/my-connector/_name
{
"name": "Custom connector",
"description": "This is my customized connector"
}resp = client.connector.update_name(
connector_id="my-connector",
name="Custom connector",
description="This is my customized connector",
)const response = await client.connector.updateName({
connector_id: "my-connector",
name: "Custom connector",
description: "This is my customized connector",
});response = client.connector.update_name(
connector_id: "my-connector",
body: {
"name": "Custom connector",
"description": "This is my customized connector"
}
)$resp = $client->connector()->updateName([
"connector_id" => "my-connector",
"body" => [
"name" => "Custom connector",
"description" => "This is my customized connector",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"name":"Custom connector","description":"This is my customized connector"}' "$ELASTICSEARCH_URL/_connector/my-connector/_name"client.connector().updateName(u -> u
.connectorId("my-connector")
.description("This is my customized connector")
.name("Custom connector")
);
{
"name": "Custom connector",
"description": "This is my customized connector"
}{
"result": "updated"
}PUT _connector/my-connector/_scheduling
{
"scheduling": {
"access_control": {
"enabled": true,
"interval": "0 10 0 * * ?"
},
"full": {
"enabled": true,
"interval": "0 20 0 * * ?"
},
"incremental": {
"enabled": false,
"interval": "0 30 0 * * ?"
}
}
}resp = client.connector.update_scheduling(
connector_id="my-connector",
scheduling={
"access_control": {
"enabled": True,
"interval": "0 10 0 * * ?"
},
"full": {
"enabled": True,
"interval": "0 20 0 * * ?"
},
"incremental": {
"enabled": False,
"interval": "0 30 0 * * ?"
}
},
)const response = await client.connector.updateScheduling({
connector_id: "my-connector",
scheduling: {
access_control: {
enabled: true,
interval: "0 10 0 * * ?",
},
full: {
enabled: true,
interval: "0 20 0 * * ?",
},
incremental: {
enabled: false,
interval: "0 30 0 * * ?",
},
},
});response = client.connector.update_scheduling(
connector_id: "my-connector",
body: {
"scheduling": {
"access_control": {
"enabled": true,
"interval": "0 10 0 * * ?"
},
"full": {
"enabled": true,
"interval": "0 20 0 * * ?"
},
"incremental": {
"enabled": false,
"interval": "0 30 0 * * ?"
}
}
}
)$resp = $client->connector()->updateScheduling([
"connector_id" => "my-connector",
"body" => [
"scheduling" => [
"access_control" => [
"enabled" => true,
"interval" => "0 10 0 * * ?",
],
"full" => [
"enabled" => true,
"interval" => "0 20 0 * * ?",
],
"incremental" => [
"enabled" => false,
"interval" => "0 30 0 * * ?",
],
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"scheduling":{"access_control":{"enabled":true,"interval":"0 10 0 * * ?"},"full":{"enabled":true,"interval":"0 20 0 * * ?"},"incremental":{"enabled":false,"interval":"0 30 0 * * ?"}}}' "$ELASTICSEARCH_URL/_connector/my-connector/_scheduling"client.connector().updateScheduling(u -> u
.connectorId("my-connector")
.scheduling(s -> s
.accessControl(a -> a
.enabled(true)
.interval("0 10 0 * * ?")
)
.full(f -> f
.enabled(true)
.interval("0 20 0 * * ?")
)
.incremental(i -> i
.enabled(false)
.interval("0 30 0 * * ?")
)
)
);
{
"scheduling": {
"access_control": {
"enabled": true,
"interval": "0 10 0 * * ?"
},
"full": {
"enabled": true,
"interval": "0 20 0 * * ?"
},
"incremental": {
"enabled": false,
"interval": "0 30 0 * * ?"
}
}
}{
"scheduling": {
"full": {
"enabled": true,
"interval": "0 10 0 * * ?"
}
}
}{
"result": "updated"
}Get information about all cross-cluster replication follower indices. For example, the results include follower index names, leader index names, replication options, and whether the follower indices are active or paused.
monitorGET /follower_index/_ccr/info
resp = client.ccr.follow_info(
index="follower_index",
)const response = await client.ccr.followInfo({
index: "follower_index",
});response = client.ccr.follow_info(
index: "follower_index"
)$resp = $client->ccr()->followInfo([
"index" => "follower_index",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/follower_index/_ccr/info"{
"follower_indices": [
{
"follower_index": "follower_index",
"remote_cluster": "remote_cluster",
"leader_index": "leader_index",
"status": "active",
"parameters": {
"max_read_request_operation_count": 5120,
"max_read_request_size": "32mb",
"max_outstanding_read_requests": 12,
"max_write_request_operation_count": 5120,
"max_write_request_size": "9223372036854775807b",
"max_outstanding_write_requests": 9,
"max_write_buffer_count": 2147483647,
"max_write_buffer_size": "512mb",
"max_retry_delay": "500ms",
"read_poll_timeout": "1m"
}
}
]
}{
"follower_indices": [
{
"follower_index": "follower_index",
"remote_cluster": "remote_cluster",
"leader_index": "leader_index",
"status": "paused"
}
]
}Comma-separated list of data stream names used to limit the request.
Wildcard (*) expressions are supported. If omitted, all data streams are returned.
Type of data stream that wildcard patterns can match.
Supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
If true, returns all relevant default configurations for the index template.
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 -1 or 0.
Whether the maximum timestamp for each data stream should be calculated and returned.
GET _data_stream/my-data-stream
resp = client.indices.get_data_stream(
name="my-data-stream",
)const response = await client.indices.getDataStream({
name: "my-data-stream",
});response = client.indices.get_data_stream(
name: "my-data-stream"
)$resp = $client->indices()->getDataStream([
"name" => "my-data-stream",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream"{
"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
}
]
}Converts an index alias to a data stream.
You must have a matching index template that is data stream enabled.
The alias must meet the following criteria:
The alias must have a write index;
All indices for the alias must have a @timestamp field mapping of a date or date_nanos field type;
The alias must not have any filters;
The alias must not use custom routing.
If successful, the request removes the alias and creates a data stream with the same name.
The indices for the alias become hidden backing indices for the stream.
The write index for the alias becomes the write index for the stream.
managePeriod 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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST _data_stream/_migrate/my-time-series-data
resp = client.indices.migrate_to_data_stream(
name="my-time-series-data",
)const response = await client.indices.migrateToDataStream({
name: "my-time-series-data",
});response = client.indices.migrate_to_data_stream(
name: "my-time-series-data"
)$resp = $client->indices()->migrateToDataStream([
"name" => "my-time-series-data",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/_migrate/my-time-series-data"Performs one or more data stream modification actions in a single atomic operation.
POST _data_stream/_modify
{
"actions": [
{
"remove_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001"
}
},
{
"add_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001-downsample"
}
}
]
}resp = client.indices.modify_data_stream(
actions=[
{
"remove_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001"
}
},
{
"add_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001-downsample"
}
}
],
)const response = await client.indices.modifyDataStream({
actions: [
{
remove_backing_index: {
data_stream: "my-data-stream",
index: ".ds-my-data-stream-2023.07.26-000001",
},
},
{
add_backing_index: {
data_stream: "my-data-stream",
index: ".ds-my-data-stream-2023.07.26-000001-downsample",
},
},
],
});response = client.indices.modify_data_stream(
body: {
"actions": [
{
"remove_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001"
}
},
{
"add_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001-downsample"
}
}
]
}
)$resp = $client->indices()->modifyDataStream([
"body" => [
"actions" => array(
[
"remove_backing_index" => [
"data_stream" => "my-data-stream",
"index" => ".ds-my-data-stream-2023.07.26-000001",
],
],
[
"add_backing_index" => [
"data_stream" => "my-data-stream",
"index" => ".ds-my-data-stream-2023.07.26-000001-downsample",
],
],
),
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"actions":[{"remove_backing_index":{"data_stream":"my-data-stream","index":".ds-my-data-stream-2023.07.26-000001"}},{"add_backing_index":{"data_stream":"my-data-stream","index":".ds-my-data-stream-2023.07.26-000001-downsample"}}]}' "$ELASTICSEARCH_URL/_data_stream/_modify"client.indices().modifyDataStream(m -> m
.actions(List.of(Action.of(a -> a
.removeBackingIndex(r -> r
.dataStream("my-data-stream")
.index(".ds-my-data-stream-2023.07.26-000001")
)),Action.of(ac -> ac
.addBackingIndex(ad -> ad
.dataStream("my-data-stream")
.index(".ds-my-data-stream-2023.07.26-000001-downsample")
))))
);
{
"actions": [
{
"remove_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001"
}
},
{
"add_backing_index": {
"data_stream": "my-data-stream",
"index": ".ds-my-data-stream-2023.07.26-000001-downsample"
}
}
]
}All methods and paths for this operation:
Perform multiple index, create, delete, and update actions in a single request.
This reduces overhead and can greatly increase indexing speed.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
create action, you must have the create_doc, create, index, or write index privilege. Data streams support only the create action.index action, you must have the create, index, or write index privilege.delete action, you must have the delete or write index privilege.update action, you must have the index or write index privilege.auto_configure, create_index, or manage index privilege.refresh parameter, you must have the maintenance or manage index privilege.Automatic data stream creation requires a matching index template with data stream enabled.
The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:
action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n
The index and create actions expect a source on the next line and have the same semantics as the op_type parameter in the standard index API.
A create action fails if a document with the same ID already exists in the target
An index action adds or replaces a document as necessary.
NOTE: Data streams support only the create action.
To update or delete a document in a data stream, you must target the backing index containing the document.
An update action expects that the partial doc, upsert, and script and its options are specified on the next line.
A delete action does not expect a source on the next line and has the same semantics as the standard delete API.
NOTE: The final line of data must end with a newline character (\n).
Each newline character may be preceded by a carriage return (\r).
When sending NDJSON data to the _bulk endpoint, use a Content-Type header of application/json or application/x-ndjson.
Because this format uses literal newline characters (\n) as delimiters, make sure that the JSON actions and sources are not pretty printed.
If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index argument.
A note on the format: the idea here is to make processing as fast as possible.
As some of the actions are redirected to other shards on other nodes, only action_meta_data is parsed on the receiving node side.
Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.
There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.
Client suppport for bulk requests
Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:
esutil.BulkIndexerSearch::Elasticsearch::Client::5_0::Bulk and Search::Elasticsearch::Client::5_0::Scrollelasticsearch.helpers.*client.helpers.*BulkAllObservableSubmitting bulk requests with cURL
If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d.
The latter doesn't preserve newlines. For example:
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
Optimistic concurrency control
Each index and delete action within a bulk API call may include the if_seq_no and if_primary_term parameters in their respective action and meta data lines.
The if_seq_no and if_primary_term parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.
Versioning
Each bulk item can include the version value using the version field.
It automatically follows the behavior of the index or delete operation based on the _version mapping.
It also support the version_type.
Routing
Each bulk item can include the routing value using the routing field.
It automatically follows the behavior of the index or delete operation based on the _routing mapping.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.
Wait for active shards
When making bulk calls, you can set the wait_for_active_shards parameter to require a minimum number of shard copies to be active before starting to process the bulk request.
Refresh
Control when the changes made by this request are visible to search.
NOTE: Only the shards that receive the bulk request will be affected by refresh.
Imagine a _bulk?refresh=wait_for request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the _bulk request at all.
True or false if to include the document source in the error message in case of parsing errors.
If true, the response will include the ingest pipelines that were run for each index or create.
The pipeline identifier to use to preprocess incoming documents.
If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request.
If a final pipeline is configured, it will always run regardless of the value of this parameter.
If true, Elasticsearch refreshes the affected shards to make this operation visible to search.
If wait_for, wait for a refresh to make this operation visible to search.
If false, do nothing with refreshes.
Valid values: true, false, wait_for.
Values are true, false, or wait_for.
A custom value that is used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or contains a list of fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned.
You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards.
The default is 1m (one minute), which guarantees Elasticsearch waits for at least the timeout before failing.
The actual wait time could be longer, particularly when multiple waits occur.
Values are -1 or 0.
The number of shard copies that must be active before proceeding with the operation.
Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default is 1, which waits for each primary shard to be active.
Values are all or index-setting.
If true, the request's actions must target an index alias.
If true, the request's actions must target a data stream (existing or to be created).
POST _bulk
{ "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"} }resp = client.bulk(
operations=[
{
"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"
}
}
],
)const response = await client.bulk({
operations: [
{
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",
},
},
],
});response = client.bulk(
body: [
{
"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"
}
}
]
)$resp = $client->bulk([
"body" => array(
[
"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",
],
],
),
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '[{"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"}}]' "$ELASTICSEARCH_URL/_bulk"{ "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"
}
}
}
]
}All methods and paths for this operation:
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:
PUT /<target>/_create/<_id> or POST /<target>/_create/<_id> request formats, you must have the create_doc, create, index, or write index privilege.auto_configure, create_index, or manage index privilege.Automatic data stream creation requires a matching index template with data stream enabled.
Automatically create data streams and indices
If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.
If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.
NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.
If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.
Automatic index creation is controlled by the action.auto_create_index setting.
If it is true, any index can be created automatically.
You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely.
Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked.
When a list is specified, the default behaviour is to disallow.
NOTE: The action.auto_create_index setting affects the automatic creation of indices only.
It does not affect the creation of data streams.
Routing
By default, shard placement — or routing — is controlled by using a hash of the document's ID value.
For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.
When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself.
This does come at the (very minimal) cost of an additional document parsing pass.
If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.
Distributed
The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.
Active shards
To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.
If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.
By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1).
This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards.
To alter this behavior per operation, use the wait_for_active_shards request parameter.
Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1).
Specifying a negative value or a number greater than the number of shard copies will throw an error.
For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).
If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.
This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.
If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.
This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.
However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.
The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.
It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.
After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.
The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.
createThe name of the data stream or index to target.
If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream.
If the target doesn't exist and doesn’t match a data stream template, this request creates the index.
A unique identifier for the document.
To automatically generate a document ID, use the POST /<target>/_doc/ request format.
Only perform the operation if the document has this primary term.
Only perform the operation if the document has this sequence number.
True or false if to include the document source in the error message in case of parsing errors.
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 to index.
Otherwise, it defaults to create.
If the request targets a data stream, an op_type of create is required.
Supported values include:
index: Overwrite any documents that already exist.create: Only index documents that do not already exist.Values are index or create.
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.
If true, Elasticsearch refreshes the affected shards to make this operation visible to search.
If wait_for, it waits for a refresh to make this operation visible to search.
If false, it does nothing with refreshes.
Values are true, false, or wait_for.
If true, the destination must be an index alias.
If true, the request's actions must target a data stream (existing or to be created).
A custom value that is used to route operations to a specific shard.
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.
Values are -1 or 0.
The explicit version number for concurrency control. It must be a non-negative long number.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
The number of shard copies that must be active before proceeding with the operation.
You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default value of 1 means it waits for each primary shard to be active.
Values are all or index-setting.
PUT my-index-000001/_create/1
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}resp = client.create(
index="my-index-000001",
id="1",
document={
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
},
)const response = await client.create({
index: "my-index-000001",
id: 1,
document: {
"@timestamp": "2099-11-15T13:12:00",
message: "GET /search HTTP/1.1 200 1070000",
user: {
id: "kimchy",
},
},
});response = client.create(
index: "my-index-000001",
id: "1",
body: {
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
)$resp = $client->create([
"index" => "my-index-000001",
"id" => "1",
"body" => [
"@timestamp" => "2099-11-15T13:12:00",
"message" => "GET /search HTTP/1.1 200 1070000",
"user" => [
"id" => "kimchy",
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}' "$ELASTICSEARCH_URL/my-index-000001/_create/1"client.create(c -> c
.id("1")
.index("my-index-000001")
.document(JsonData.fromJson("{\"@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"
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1
}Get a document and its source or stored fields from an index.
By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search).
In the case where stored fields are requested with the stored_fields parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields.
To turn off realtime behavior, set the realtime parameter to false.
Source filtering
By default, the API returns the contents of the _source field unless you have used the stored_fields parameter or the _source field is turned off.
You can turn off _source retrieval by using the _source parameter:
GET my-index-000001/_doc/0?_source=false
If you only need one or two fields from the _source, use the _source_includes or _source_excludes parameters to include or filter out particular fields.
This can be helpful with large documents where partial retrieval can save on network overhead
Both parameters take a comma separated list of fields or wildcard expressions.
For example:
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
If you only want to specify includes, you can use a shorter notation:
GET my-index-000001/_doc/0?_source=*.id
Routing
If routing is used during indexing, the routing value also needs to be specified to retrieve a document. For example:
GET my-index-000001/_doc/2?routing=user1
This request gets the document with ID 2, but it is routed based on the user. The document is not fetched if the correct routing is not specified.
Distributed
The GET operation is hashed into a specific shard ID. It is then redirected to one of the replicas within that shard ID and returns the result. The replicas are the primary shard and its replicas within that shard ID group. This means that the more replicas you have, the better your GET scaling will be.
Versioning support
You can use the version parameter to retrieve the document only if its current version is equal to the specified one.
Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. The old version of the document doesn't disappear immediately, although you won't be able to access it. Elasticsearch cleans up deleted documents in the background as you continue to index more data.
readThe node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If it is set to _local, the operation will prefer to be run on a local allocated shard when possible.
If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.
This can help with "jumping values" when hitting different shards in different refresh states.
A sample value can be something like the web session ID or the user name.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned.
You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of stored fields to return as part of a hit.
If no fields are specified, no stored fields are included in the response.
If this field is specified, the _source parameter defaults to false.
Only leaf fields can be retrieved with the stored_field option.
Object fields can't be returned;if specified, the request fails.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
GET my-index-000001/_doc/1?stored_fields=tags,counter
resp = client.get(
index="my-index-000001",
id="1",
stored_fields="tags,counter",
)const response = await client.get({
index: "my-index-000001",
id: 1,
stored_fields: "tags,counter",
});response = client.get(
index: "my-index-000001",
id: "1",
stored_fields: "tags,counter"
)$resp = $client->get([
"index" => "my-index-000001",
"id" => "1",
"stored_fields" => "tags,counter",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_doc/1?stored_fields=tags,counter"{
"_index": "my-index-000001",
"_id": "0",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"found": true,
"_source": {
"@timestamp": "2099-11-15T14:12:12",
"http": {
"request": {
"method": "get"
},
"response": {
"status_code": 200,
"bytes": 1070000
},
"version": "1.1"
},
"source": {
"ip": "127.0.0.1"
},
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"_seq_no" : 22,
"_primary_term" : 1,
"found": true,
"fields": {
"tags": [
"production"
]
}
}{
"_index": "my-index-000001",
"_id": "2",
"_version": 1,
"_seq_no" : 13,
"_primary_term" : 1,
"_routing": "user1",
"found": true,
"fields": {
"tags": [
"env2"
]
}
}Deletes documents that match the specified query.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:
readdelete or writeYou can specify the query criteria in the request URI or the request body using the same syntax as the search API. When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails.
NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number.
While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. A bulk delete request is performed for each batch of matching documents. If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. Any delete requests that completed successfully still stick, they are not rolled back.
You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed.
Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than max_docs until it has successfully deleted max_docs documents, or it has gone through every document in the source query.
Throttling delete requests
To control the rate at which delete by query issues batches of delete operations, you can set requests_per_second to any positive decimal number.
This pads each batch with a wait time to throttle the rate.
Set requests_per_second to -1 to disable throttling.
Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account.
The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing.
By default the batch size is 1000, so if requests_per_second is set to 500:
target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set.
This is "bursty" instead of "smooth".
Slicing
Delete by query supports sliced scroll to parallelize the delete process. This can improve efficiency and provide a convenient way to break the request down into smaller parts.
Setting slices to auto lets Elasticsearch choose the number of slices to use.
This setting will use one slice per shard, up to a certain limit.
If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards.
Adding slices to the delete by query operation creates sub-requests which means it has some quirks:
slices will rethrottle the unfinished sub-request proportionally.slices will cancel each sub-request.slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being deleted.If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:
slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources.
Cancel a delete by query operation
Any delete by query can be canceled using the task cancel API. For example:
POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel
The task ID can be found by using the get tasks API.
Cancellation should happen quickly but might take a few seconds. The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.
read,deleteA comma-separated list of data streams, indices, and aliases to search.
It supports wildcards (*).
To search all data streams or indices, omit this parameter or use * or _all.
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices.
This behavior applies even if the request targets other open indices.
For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
Analyzer to use for the query string.
This parameter can be used only when the q query string parameter is specified.
If true, wildcard and prefix queries are analyzed.
This parameter can be used only when the q query string parameter is specified.
What to do if delete by query hits version conflicts: abort or proceed.
Supported values include:
abort: Stop reindexing if there are conflicts.proceed: Continue reindexing even if there are conflicts.Values are abort or proceed.
The default operator for query string query: AND or OR.
This parameter can be used only when the q query string parameter is specified.
Values are and, AND, or, or OR.
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.
The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
It supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Skips the specified number of documents.
If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
This parameter can be used only when the q query string parameter is specified.
The maximum number of documents to process.
Defaults to all documents.
When set to a value less then or equal to scroll_size, a scroll will not be used to retrieve the results for the operation.
The node or shard the operation should be performed on. It is random by default.
If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes.
This is different than the delete API's refresh parameter, which causes just the shard that received the delete request to be refreshed.
Unlike the delete API, it does not support wait_for.
If true, the request cache is used for this request.
Defaults to the index-level setting.
The throttle for this request in sub-requests per second.
A custom value used to route operations to a specific shard.
A query in the Lucene query string syntax.
The period to retain the search context for scrolling.
Values are -1 or 0.
The size of the scroll request that powers the operation.
The explicit timeout for each search request. It defaults to no timeout.
Values are -1 or 0.
The type of the search operation.
Available options include query_then_fetch and dfs_query_then_fetch.
Supported values include:
query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.Values are query_then_fetch or dfs_query_then_fetch.
The number of slices this task should be divided into.
Value is auto.
A comma-separated list of <field>:<direction> pairs.
The specific tag of the request for logging and statistical purposes.
The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
The period each deletion request waits for active shards.
Values are -1 or 0.
If true, returns the document version as part of a hit.
The number of shard copies that must be active before proceeding with the operation.
Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The timeout value controls how long each write request waits for unavailable shards to become available.
Values are all or index-setting.
If true, the request blocks until the operation is complete.
If false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at .tasks/task/${taskId}. When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space.
The maximum number of documents to delete.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
POST /my-index-000001,my-index-000002/_delete_by_query
{
"query": {
"match_all": {}
}
}resp = client.delete_by_query(
index="my-index-000001,my-index-000002",
query={
"match_all": {}
},
)const response = await client.deleteByQuery({
index: "my-index-000001,my-index-000002",
query: {
match_all: {},
},
});response = client.delete_by_query(
index: "my-index-000001,my-index-000002",
body: {
"query": {
"match_all": {}
}
}
)$resp = $client->deleteByQuery([
"index" => "my-index-000001,my-index-000002",
"body" => [
"query" => [
"match_all" => new ArrayObject([]),
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"match_all":{}}}' "$ELASTICSEARCH_URL/my-index-000001,my-index-000002/_delete_by_query"client.deleteByQuery(d -> d
.index(List.of("my-index-000001","my-index-000002"))
.query(q -> q
.matchAll(m -> m)
)
);
{
"query": {
"match_all": {}
}
}{
"query": {
"term": {
"user.id": "kimchy"
}
},
"max_docs": 1
}{
"slice": {
"id": 0,
"max": 2
},
"query": {
"range": {
"http.response.bytes": {
"lt": 2000000
}
}
}
}{
"query": {
"range": {
"http.response.bytes": {
"lt": 2000000
}
}
}
}{
"took" : 147,
"timed_out": false,
"total": 119,
"deleted": 119,
"batches": 1,
"version_conflicts": 0,
"noops": 0,
"retries": {
"bulk": 0,
"search": 0
},
"throttled_millis": 0,
"requests_per_second": -1.0,
"throttled_until_millis": 0,
"failures" : [ ]
}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
readThe node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
GET my-index-000001/_source/1
resp = client.get_source(
index="my-index-000001",
id="1",
)const response = await client.getSource({
index: "my-index-000001",
id: 1,
});response = client.get_source(
index: "my-index-000001",
id: "1"
)$resp = $client->getSource([
"index" => "my-index-000001",
"id" => "1",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_source/1"Check whether a document source exists in an index. For example:
HEAD my-index-000001/_source/1
A document's source is not available if it is disabled in the mapping.
readA comma-separated list of data streams, indices, and aliases.
It supports wildcards (*).
A unique identifier for the document.
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
HEAD my-index-000001/_source/1
resp = client.exists_source(
index="my-index-000001",
id="1",
)const response = await client.existsSource({
index: "my-index-000001",
id: 1,
});response = client.exists_source(
index: "my-index-000001",
id: "1"
)$resp = $client->existsSource([
"index" => "my-index-000001",
"id" => "1",
]);curl --head -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_source/1"Change the number of requests per second for a particular reindex operation. For example:
POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
Rethrottling that speeds up the query takes effect immediately. Rethrottling that slows down the query will take effect after completing the current batch. This behavior prevents scroll timeouts.
POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
resp = client.reindex_rethrottle(
task_id="r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second="-1",
)const response = await client.reindexRethrottle({
task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second: "-1",
});response = client.reindex_rethrottle(
task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second: "-1"
)$resp = $client->reindexRethrottle([
"task_id" => "r1A2WoRbTwKZ516z6NEs5A:36619",
"requests_per_second" => "-1",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1"All methods and paths for this operation:
Get information and statistics about terms in the fields of a particular document.
You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request.
You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body.
For example:
GET /my-index-000001/_termvectors/1?fields=message
Fields can be specified using wildcards, similar to the multi match query.
Term vectors are real-time by default, not near real-time.
This can be changed by setting realtime parameter to false.
You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.
Term information
positions: true)offsets: true)payloads: true), as base64 encoded bytesIf the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.
Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.
Behaviour
The term and field statistics are not accurate.
Deleted documents are not taken into account.
The information is only retrieved for the shard the requested document resides in.
The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
Use routing only to hit a particular shard.
readThe name of the index that contains the document.
A unique identifier for the document.
A comma-separated list or wildcard expressions of fields to include in the statistics.
It is used as the default list unless a specific field list is provided in the completion_fields or fielddata_fields parameters.
If true, the response includes:
If true, the response includes term offsets.
If true, the response includes term payloads.
If true, the response includes term positions.
The node or shard the operation should be performed on. It is random by default.
If true, the request is real-time as opposed to near-real-time.
A custom value that is used to route operations to a specific shard.
If true, the response includes:
By default these values are not returned since term statistics can have a serious performance impact.
If true, returns the document version as part of a hit.
The version type.
Supported values include:
internal: Use internal versioning that starts at 1 and increments with each update or delete.external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The external_gte version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.force: This option is deprecated because it can cause primary and replica shards to diverge.Values are internal, external, external_gte, or force.
An artificial document (a document not present in the index) for which you want to retrieve term vectors.
Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.
If true, the response includes:
Default value is true.
If true, the response includes term offsets.
Default value is true.
If true, the response includes term payloads.
Default value is true.
If true, the response includes term positions.
Default value is true.
If true, the response includes:
By default these values are not returned since term statistics can have a serious performance impact.
Default value is false.
Values are internal, external, external_gte, or force.
GET /my-index-000001/_termvectors/1
{
"fields" : ["text"],
"offsets" : true,
"payloads" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}resp = client.termvectors(
index="my-index-000001",
id="1",
fields=[
"text"
],
offsets=True,
payloads=True,
positions=True,
term_statistics=True,
field_statistics=True,
)const response = await client.termvectors({
index: "my-index-000001",
id: 1,
fields: ["text"],
offsets: true,
payloads: true,
positions: true,
term_statistics: true,
field_statistics: true,
});response = client.termvectors(
index: "my-index-000001",
id: "1",
body: {
"fields": [
"text"
],
"offsets": true,
"payloads": true,
"positions": true,
"term_statistics": true,
"field_statistics": true
}
)$resp = $client->termvectors([
"index" => "my-index-000001",
"id" => "1",
"body" => [
"fields" => array(
"text",
),
"offsets" => true,
"payloads" => true,
"positions" => true,
"term_statistics" => true,
"field_statistics" => true,
],
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"fields":["text"],"offsets":true,"payloads":true,"positions":true,"term_statistics":true,"field_statistics":true}' "$ELASTICSEARCH_URL/my-index-000001/_termvectors/1"client.termvectors(t -> t
.fieldStatistics(true)
.fields("text")
.id("1")
.index("my-index-000001")
.offsets(true)
.payloads(true)
.positions(true)
.termStatistics(true)
);
{
"fields" : ["text"],
"offsets" : true,
"payloads" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
},
"fields": ["fullname"],
"per_field_analyzer" : {
"fullname": "keyword"
}
}{
"doc": {
"plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
},
"term_statistics": true,
"field_statistics": true,
"positions": false,
"offsets": false,
"filter": {
"max_num_terms": 3,
"min_term_freq": 1,
"min_doc_freq": 1
}
}{
"fields" : ["text", "some_field_without_term_vectors"],
"offsets" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"found": true,
"took": 6,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 4,
"doc_count": 2,
"sum_ttf": 6
},
"terms": {
"test": {
"doc_freq": 2,
"ttf": 4,
"term_freq": 3,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 4,
"payload": "d29yZA=="
},
{
"position": 1,
"start_offset": 5,
"end_offset": 9,
"payload": "d29yZA=="
},
{
"position": 2,
"start_offset": 10,
"end_offset": 14,
"payload": "d29yZA=="
}
]
}
}
}
}
}{
"_index": "my-index-000001",
"_version": 0,
"found": true,
"took": 6,
"term_vectors": {
"fullname": {
"field_statistics": {
"sum_doc_freq": 2,
"doc_count": 4,
"sum_ttf": 4
},
"terms": {
"John Doe": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 8
}
]
}
}
}
}
}{
"_index": "imdb",
"_version": 0,
"found": true,
"term_vectors": {
"plot": {
"field_statistics": {
"sum_doc_freq": 3384269,
"doc_count": 176214,
"sum_ttf": 3753460
},
"terms": {
"armored": {
"doc_freq": 27,
"ttf": 27,
"term_freq": 1,
"score": 9.74725
},
"industrialist": {
"doc_freq": 88,
"ttf": 88,
"term_freq": 1,
"score": 8.590818
},
"stark": {
"doc_freq": 44,
"ttf": 47,
"term_freq": 1,
"score": 9.272792
}
}
}
}
}Update a document by running a script or passing a partial document.
If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.
The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:
The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.
The _source field must be enabled to use this API.
In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).
writeThe name of the target index. By default, the index is created automatically if it doesn't exist.
A unique identifier for the document to be updated.
Only perform the operation if the document has this primary term.
Only perform the operation if the document has this sequence number.
True or false if to include the document source in the error message in case of parsing errors.
The script language.
If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes.
Values are true, false, or wait_for.
If true, the destination must be an index alias.
The number of times the operation should be retried when a conflict occurs.
A custom value used to route operations to a specific shard.
The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
Values are -1 or 0.
The number of copies of each shard that must be active before proceeding with the operation.
Set to 'all' or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The default value of 1 means it waits for each primary shard to be active.
Values are all or index-setting.
If false, source retrieval is turned off.
You can also specify a comma-separated list of the fields you want to retrieve.
The source fields you want to exclude.
The source fields you want to retrieve.
If true, the result in the response is set to noop (no operation) when there are no changes to the document.
Default value is true.
A partial update to an existing document.
If both doc and script are specified, doc is ignored.
If true, use the contents of 'doc' as the value of 'upsert'.
NOTE: Using ingest pipelines with doc_as_upsert is not supported.
Default value is false.
If true, run the script whether or not the document exists.
Default value is false.
If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run.
POST test/_update/1
{
"script" : {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params" : {
"count" : 4
}
}
}resp = client.update(
index="test",
id="1",
script={
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params": {
"count": 4
}
},
)const response = await client.update({
index: "test",
id: 1,
script: {
source: "ctx._source.counter += params.count",
lang: "painless",
params: {
count: 4,
},
},
});response = client.update(
index: "test",
id: "1",
body: {
"script": {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params": {
"count": 4
}
}
}
)$resp = $client->update([
"index" => "test",
"id" => "1",
"body" => [
"script" => [
"source" => "ctx._source.counter += params.count",
"lang" => "painless",
"params" => [
"count" => 4,
],
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"script":{"source":"ctx._source.counter += params.count","lang":"painless","params":{"count":4}}}' "$ELASTICSEARCH_URL/test/_update/1"client.update(u -> u
.id("1")
.index("test")
.script(s -> s
.source("ctx._source.counter += params.count")
.params("count", JsonData.fromJson("4"))
.lang("painless")
)
,Void.class);
{
"script" : {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params" : {
"count" : 4
}
}
}{
"scripted_upsert": true,
"script": {
"source": """
if ( ctx.op == 'create' ) {
ctx._source.counter = params.count
} else {
ctx._source.counter += params.count
}
""",
"params": {
"count": 4
}
},
"upsert": {}
}{
"doc": {
"name": "new_name"
},
"doc_as_upsert": true
}{
"script": {
"source": "ctx._source.tags.add(params.tag)",
"lang": "painless",
"params": {
"tag": "blue"
}
}
}{
"script": {
"source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
"lang": "painless",
"params": {
"tag": "blue"
}
}
}{
"script" : "ctx._source.new_field = 'value_of_new_field'"
}{
"script" : "ctx._source.remove('new_field')"
}{
"script": "ctx._source['my-object'].remove('my-subfield')"
}{
"script": {
"source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
"lang": "painless",
"params": {
"tag": "green"
}
}
}{
"doc": {
"name": "new_name"
}
}{
"script": {
"source": "ctx._source.counter += params.count",
"lang": "painless",
"params": {
"count": 4
}
},
"upsert": {
"counter": 1
}
}{
"_shards": {
"total": 0,
"successful": 0,
"failed": 0
},
"_index": "test",
"_id": "1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 1,
"result": "noop"
}Updates documents that match the specified query. If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:
readindex or writeYou can specify the query criteria in the request URI or the request body using the same syntax as the search API.
When you submit an update by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and updates matching documents using internal versioning.
When the versions match, the document is updated and the version number is incremented.
If a document changes between the time that the snapshot is taken and the update operation is processed, it results in a version conflict and the operation fails.
You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed.
Note that if you opt to count version conflicts, the operation could attempt to update more documents from the source than max_docs until it has successfully updated max_docs documents or it has gone through every document in the source query.
NOTE: Documents with a version equal to 0 cannot be updated using update by query because internal versioning does not support 0 as a valid version number.
While processing an update by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents. A bulk update request is performed for each batch of matching documents. Any query or update failures cause the update by query request to fail and the failures are shown in the response. Any update requests that completed successfully still stick, they are not rolled back.
Throttling update requests
To control the rate at which update by query issues batches of update operations, you can set requests_per_second to any positive decimal number.
This pads each batch with a wait time to throttle the rate.
Set requests_per_second to -1 to turn off throttling.
Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account.
The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing.
By default the batch size is 1000, so if requests_per_second is set to 500:
target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. This is "bursty" instead of "smooth".
Slicing
Update by query supports sliced scroll to parallelize the update process. This can improve efficiency and provide a convenient way to break the request down into smaller parts.
Setting slices to auto chooses a reasonable number for most data streams and indices.
This setting will use one slice per shard, up to a certain limit.
If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards.
Adding slices to _update_by_query just automates the manual process of creating sub-requests, which means it has some quirks:
slices only contains the status of completed slices.slices will rethrottle the unfinished sub-request proportionally.requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the point above about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being updated.If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:
Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.
Update the document source
Update by query supports scripts to update the document source.
As with the update API, you can set ctx.op to change the operation that is performed.
Set ctx.op = "noop" if your script decides that it doesn't have to make any changes.
The update by query operation skips updating the document and increments the noop counter.
Set ctx.op = "delete" if your script decides that the document should be deleted.
The update by query operation deletes the document and increments the deleted counter.
Update by query supports only index, noop, and delete.
Setting ctx.op to anything else is an error.
Setting any other field in ctx is an error.
This API enables you to only modify the source of matching documents; you cannot move them.
read,writeA comma-separated list of data streams, indices, and aliases to search.
It supports wildcards (*).
To search all data streams or indices, omit this parameter or use * or _all.
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.
The analyzer to use for the query string.
This parameter can be used only when the q query string parameter is specified.
If true, wildcard and prefix queries are analyzed.
This parameter can be used only when the q query string parameter is specified.
The preferred behavior when update by query hits version conflicts: abort or proceed.
Supported values include:
abort: Stop reindexing if there are conflicts.proceed: Continue reindexing even if there are conflicts.Values are abort or proceed.
The default operator for query string query: AND or OR.
This parameter can be used only when the q query string parameter is specified.
Values are and, AND, or, or OR.
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.
The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
It supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Skips the specified number of documents.
If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
This parameter can be used only when the q query string parameter is specified.
The maximum number of documents to process.
It defaults to all documents.
When set to a value less then or equal to scroll_size then a scroll will not be used to retrieve the results for the operation.
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.
The node or shard the operation should be performed on. It is random by default.
A query in the Lucene query string syntax.
If true, Elasticsearch refreshes affected shards to make the operation visible to search after the request completes.
This is different than the update API's refresh parameter, which causes just the shard that received the request to be refreshed.
If true, the request cache is used for this request.
It defaults to the index-level setting.
The throttle for this request in sub-requests per second.
A custom value used to route operations to a specific shard.
The period to retain the search context for scrolling.
Values are -1 or 0.
The size of the scroll request that powers the operation.
An explicit timeout for each search request. By default, there is no timeout.
Values are -1 or 0.
The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.
Supported values include:
query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.Values are query_then_fetch or dfs_query_then_fetch.
The number of slices this task should be divided into.
Value is auto.
A comma-separated list of : pairs.
The specific tag of the request for logging and statistical purposes.
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.
The period each update request waits for the following operations: dynamic mapping updates, waiting for active shards. By default, it is one minute. This guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur.
Values are -1 or 0.
If true, returns the document version as part of a hit.
Should the document increment the version number (internal) on hit or not (reindex)
The number of shard copies that must be active before proceeding with the operation.
Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).
The timeout parameter controls how long each write request waits for unavailable shards to become available.
Both work exactly the way they work in the bulk API.
Values are all or index-setting.
If true, the request blocks until the operation is complete.
If false, Elasticsearch performs some preflight checks, launches the request, and returns a task ID that you can use to cancel or get the status of the task.
Elasticsearch creates a record of this task as a document at .tasks/task/${taskId}.
The maximum number of documents to update.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Values are abort or proceed.
POST my-index-000001/_update_by_query?conflicts=proceed
{
"query": {
"term": {
"user.id": "kimchy"
}
}
}resp = client.update_by_query(
index="my-index-000001",
conflicts="proceed",
query={
"term": {
"user.id": "kimchy"
}
},
)const response = await client.updateByQuery({
index: "my-index-000001",
conflicts: "proceed",
query: {
term: {
"user.id": "kimchy",
},
},
});response = client.update_by_query(
index: "my-index-000001",
conflicts: "proceed",
body: {
"query": {
"term": {
"user.id": "kimchy"
}
}
}
)$resp = $client->updateByQuery([
"index" => "my-index-000001",
"conflicts" => "proceed",
"body" => [
"query" => [
"term" => [
"user.id" => "kimchy",
],
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"term":{"user.id":"kimchy"}}}' "$ELASTICSEARCH_URL/my-index-000001/_update_by_query?conflicts=proceed"client.updateByQuery(u -> u
.conflicts(Conflicts.Proceed)
.index("my-index-000001")
.query(q -> q
.term(t -> t
.field("user.id")
.value(FieldValue.of("kimchy"))
)
)
);
{
"query": {
"term": {
"user.id": "kimchy"
}
}
}{
"script": {
"source": "ctx._source.count++",
"lang": "painless"
},
"query": {
"term": {
"user.id": "kimchy"
}
}
}{
"slice": {
"id": 0,
"max": 2
},
"script": {
"source": "ctx._source['extra'] = 'test'"
}
}{
"script": {
"source": "ctx._source['extra'] = 'test'"
}
}Change the number of requests per second for a particular update by query operation. Rethrottling that speeds up the query takes effect immediately but rethrotting that slows down the query takes effect after completing the current batch to prevent scroll timeouts.
POST _update_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
resp = client.update_by_query_rethrottle(
task_id="r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second="-1",
)const response = await client.updateByQueryRethrottle({
task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second: "-1",
});response = client.update_by_query_rethrottle(
task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second: "-1"
)$resp = $client->updateByQueryRethrottle([
"task_id" => "r1A2WoRbTwKZ516z6NEs5A:36619",
"requests_per_second" => "-1",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_update_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1"Deletes an existing enrich policy and its enrich index.
DELETE /_enrich/policy/my-policy
resp = client.enrich.delete_policy(
name="my-policy",
)const response = await client.enrich.deletePolicy({
name: "my-policy",
});response = client.enrich.delete_policy(
name: "my-policy"
)$resp = $client->enrich()->deletePolicy([
"name" => "my-policy",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy"Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.
The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.
readThe character to use between values within a CSV row. It is valid only for the CSV format.
Indicates whether columns that are entirely null will be removed from the columns and values portion of the results.
If true, the response will include an extra section under the name all_columns which has the name of all the columns.
A short version of the Accept header, for example json or yaml.
Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
A field value.
A field value.
If provided and true the response will include an extra profile object
with information on how the query was executed. This information is for human debugging
and its format can change at any time but it can give some insight into the performance
of each part of the query.
The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
When set to true and performing a cross-cluster query, the response will include an extra _clusters
object with information about the clusters that participated in the search along with info such as shards
count.
Default value is false.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
Indicates whether the query and its results are stored in the cluster.
If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.
Default value is false.
POST /_query/async
{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s",
"include_ccs_metadata": true
}resp = client.esql.async_query(
query="\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ",
wait_for_completion_timeout="2s",
include_ccs_metadata=True,
)const response = await client.esql.asyncQuery({
query:
"\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ",
wait_for_completion_timeout: "2s",
include_ccs_metadata: true,
});response = client.esql.async_query(
body: {
"query": "\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ",
"wait_for_completion_timeout": "2s",
"include_ccs_metadata": true
}
)$resp = $client->esql()->asyncQuery([
"body" => [
"query" => "\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ",
"wait_for_completion_timeout" => "2s",
"include_ccs_metadata" => true,
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n FROM library,remote-*:library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ","wait_for_completion_timeout":"2s","include_ccs_metadata":true}' "$ELASTICSEARCH_URL/_query/async"{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s",
"include_ccs_metadata": true
}Get the current status and available results or stored results for an ES|QL asynchronous query. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.
The unique identifier of the query.
A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.
A query ID is also provided when the request was submitted with the keep_on_completion parameter set to true.
Indicates whether columns that are entirely null will be removed from the columns and values portion of the results.
If true, the response will include an extra section under the name all_columns which has the name of all the columns.
A short version of the Accept header, for example json or yaml.
Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
The period for which the query and its results are stored in the cluster. When this period expires, the query and its results are deleted, even if the query is still ongoing.
Values are -1 or 0.
The period to wait for the request to finish.
By default, the request waits for complete query results.
If the request completes during the period specified in this parameter, complete query results are returned.
Otherwise, the response returns an is_running value of true and no results.
Values are -1 or 0.
GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s
resp = client.esql.async_query_get(
id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
wait_for_completion_timeout="30s",
)const response = await client.esql.asyncQueryGet({
id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
wait_for_completion_timeout: "30s",
});response = client.esql.async_query_get(
id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
wait_for_completion_timeout: "30s"
)$resp = $client->esql()->asyncQueryGet([
"id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
"wait_for_completion_timeout" => "30s",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s"This API interrupts the query execution and returns the results so far. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can stop it.
The unique identifier of the query.
A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time.
A query ID is also provided when the request was submitted with the keep_on_completion parameter set to true.
POST /_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=/stop
resp = client.esql.async_query_stop(
id="FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=",
)const response = await client.esql.asyncQueryStop({
id: "FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=",
});response = client.esql.async_query_stop(
id: "FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM="
)$resp = $client->esql()->asyncQueryStop([
"id" => "FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=/stop"A single target to search. If the target is an index alias, it must resolve to a single index.
Values are and, AND, or, or OR.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
Values are -1 or 0.
Supported values include:
query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.Values are query_then_fetch or dfs_query_then_fetch.
Specifies which field to use for suggestions.
Supported values include:
missing: Only generate suggestions for terms that are not in the shard.popular: Only suggest terms that occur in more docs on the shard than the original term.always: Suggest any matching suggestions based on terms in the suggest text.Values are missing, popular, or always.
The source text for which the suggestions should be returned.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
Values are -1 or 0.
Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
Used as a query parameter along with the _source_includes and _source_excludes parameters.
A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.
If true, returns partial results if there are shard request timeouts or shard failures. If false, returns
an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results
which is true by default.
If true, returns detailed information about score computation as part of a hit.
Default value is false.
Configuration of search extensions defined by Elasticsearch plugins.
Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
Default value is 0.
Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
Boosts the _score of documents from specified indices.
Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
A reference to a field with formatting instructions on how to return the value
Minimum _score for matching documents. Documents with a lower _score are not included in the search results.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Retrieve a script evaluation (based on different fields) for each hit.
A field value.
A field value.
The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
Default value is 10.
Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
A reference to a field with formatting instructions on how to return the value
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. Defaults to 0, which does not terminate query execution early.
Default value is 0.
Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
If true, calculate and return document scores, even if the scores are not used for sorting.
Default value is false.
If true, returns document version as part of a hit.
Default value is false.
If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
Stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
curl \
--request POST 'http://api.example.com/{index}/_fleet/_fleet_search' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"aggregations":{},"collapse":{},"explain":false,"ext":{"additionalProperty1":{},"additionalProperty2":{}},"from":0,"highlight":{"":"plain","boundary_chars":".,!? \\t\\n","boundary_max_scan":20,"boundary_scanner":"chars","boundary_scanner_locale":"Locale.ROOT","force_source":true,"fragmenter":"simple","fragment_size":100,"highlight_filter":true,"highlight_query":{},"max_fragment_length":42.0,"max_analyzed_offset":42.0,"no_match_size":0,"number_of_fragments":5,"options":{"additionalProperty1":{},"additionalProperty2":{}},"order":"score","phrase_limit":256,"post_tags":["string"],"pre_tags":["string"],"require_field_match":true,"tags_schema":"styled","encoder":"default","fields":{}},"track_total_hits":true,"indices_boost":[{"additionalProperty1":42.0,"additionalProperty2":42.0}],"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"min_score":42.0,"post_filter":{},"profile":true,"query":{},"rescore":{"window_size":42.0,"query":{"rescore_query":{},"query_weight":1,"rescore_query_weight":1,"score_mode":"avg"},"learning_to_rank":{"model_id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}}}},"script_fields":{"additionalProperty1":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"search_after":[42.0],"size":10,"slice":{"field":"string","id":"string","max":42.0},"":true,"fields":[{"field":"string","format":"string","include_unmapped":true}],"suggest":{"text":"string"},"terminate_after":0,"timeout":"string","track_scores":false,"version":false,"seq_no_primary_term":true,"stored_fields":"string","pit":{"id":"string","keep_alive":"string"},"runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"stats":["string"]}'The graph explore API enables you to extract and summarize information about the documents and terms in an Elasticsearch data stream or index.
Comma-separated list of component template names used to limit the request.
Wildcard (*) expressions are supported.
If true, returns settings in flat format.
Filter out results, for example to filter out sensitive information. Supports wildcards or full settings keys
Return all default configurations for the component template (default: false)
If true, the request retrieves information from the local node only.
If false, information is retrieved from the master node.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
GET /_component_template/template_1
resp = client.cluster.get_component_template(
name="template_1",
)const response = await client.cluster.getComponentTemplate({
name: "template_1",
});response = client.cluster.get_component_template(
name: "template_1"
)$resp = $client->cluster()->getComponentTemplate([
"name" => "template_1",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_component_template/template_1"All methods and paths for this operation:
Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
An index template can be composed of multiple component templates.
To use a component template, specify it in an index template’s composed_of list.
Component templates are only applied to new data streams and indices as part of a matching index template.
Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.
Component templates are only used during index creation. For data streams, this includes data stream creation and the creation of a stream’s backing indices. Changes to component templates do not affect existing indices, including a stream’s backing indices.
You can use C-style /* *\/ block comments in component templates.
You can include comments anywhere in the request body except before the opening curly bracket.
Applying component templates
You cannot directly apply a component template to a data stream or index.
To be applied, a component template must be included in an index template's composed_of list.
manage_index_templatesName of the component template to create.
Elasticsearch includes the following built-in component templates: logs-mappings; logs-settings; metrics-mappings; metrics-settings;synthetics-mapping; synthetics-settings.
Elastic Agent uses these templates to configure backing indices for its data streams.
If you use Elastic Agent and want to overwrite one of these templates, set the version for your replacement template higher than the current version.
If you don’t use Elastic Agent and want to disable all built-in component and index templates, set stack.templates.enabled to false using the cluster update settings API.
If true, this request cannot replace or update existing component templates.
User defined reason for create the component template.
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 -1 or 0.
PUT _component_template/template_1
{
"template": null,
"settings": {
"number_of_shards": 1
},
"mappings": {
"_source": {
"enabled": false
},
"properties": {
"host_name": {
"type": "keyword"
},
"created_at": {
"type": "date",
"format": "EEE MMM dd HH:mm:ss Z yyyy"
}
}
}
}resp = client.cluster.put_component_template(
name="template_1",
template=None,
settings={
"number_of_shards": 1
},
mappings={
"_source": {
"enabled": False
},
"properties": {
"host_name": {
"type": "keyword"
},
"created_at": {
"type": "date",
"format": "EEE MMM dd HH:mm:ss Z yyyy"
}
}
},
)const response = await client.cluster.putComponentTemplate({
name: "template_1",
template: null,
settings: {
number_of_shards: 1,
},
mappings: {
_source: {
enabled: false,
},
properties: {
host_name: {
type: "keyword",
},
created_at: {
type: "date",
format: "EEE MMM dd HH:mm:ss Z yyyy",
},
},
},
});response = client.cluster.put_component_template(
name: "template_1",
body: {
"template": nil,
"settings": {
"number_of_shards": 1
},
"mappings": {
"_source": {
"enabled": false
},
"properties": {
"host_name": {
"type": "keyword"
},
"created_at": {
"type": "date",
"format": "EEE MMM dd HH:mm:ss Z yyyy"
}
}
}
}
)$resp = $client->cluster()->putComponentTemplate([
"name" => "template_1",
"body" => [
"template" => null,
"settings" => [
"number_of_shards" => 1,
],
"mappings" => [
"_source" => [
"enabled" => false,
],
"properties" => [
"host_name" => [
"type" => "keyword",
],
"created_at" => [
"type" => "date",
"format" => "EEE MMM dd HH:mm:ss Z yyyy",
],
],
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"template":null,"settings":{"number_of_shards":1},"mappings":{"_source":{"enabled":false},"properties":{"host_name":{"type":"keyword"},"created_at":{"type":"date","format":"EEE MMM dd HH:mm:ss Z yyyy"}}}}' "$ELASTICSEARCH_URL/_component_template/template_1"{
"template": null,
"settings": {
"number_of_shards": 1
},
"mappings": {
"_source": {
"enabled": false
},
"properties": {
"host_name": {
"type": "keyword"
},
"created_at": {
"type": "date",
"format": "EEE MMM dd HH:mm:ss Z yyyy"
}
}
}
}{
"template": null,
"settings": {
"number_of_shards": 1
},
"aliases": {
"alias1": {},
"alias2": {
"filter": {
"term": {
"user.id": "kimchy"
}
},
"routing": "shard-1"
},
"{index}-alias": {}
}
}Returns information about whether a particular component template exists.
Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
curl \
--request HEAD 'http://api.example.com/_component_template/{name}' \
--header "Authorization: $API_KEY"If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling.
For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.
Use this API to list dangling indices, which you can then import or delete.
manageGET /_dangling
resp = client.dangling_indices.list_dangling_indices()const response = await client.danglingIndices.listDanglingIndices();response = client.dangling_indices.list_dangling_indices$resp = $client->danglingIndices()->listDanglingIndices();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_dangling"client.danglingIndices().listDanglingIndices();
{
"dangling_indices": [
{
"index_name": "my-index-000001",
"index_uuid": "zmM4e0JtBkeUjiHD-MihPQ",
"creation_date_millis": 1589414451372,
"node_ids": [
"pL47UN3dAb2d5RCWP6lQ3e"
]
}
]
}Add an index block to an index. Index blocks limit the operations allowed on an index by blocking specific operation types.
A comma-separated list or wildcard expression of index names used to limit the request.
By default, you must explicitly name the indices you are adding blocks to.
To allow the adding of blocks to indices with _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false.
You can update this setting in the elasticsearch.yml file or by using the cluster update settings API.
The block type to add to the index.
Supported values include:
metadata: Disable metadata changes, such as closing the index.read: Disable read operations.read_only: Disable write operations and metadata changes.write: Disable write operations. However, metadata changes are still allowed.Values are metadata, read, read_only, or write.
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.
The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
It supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
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.
Values are -1 or 0.
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.
Values are -1 or 0.
PUT /my-index-000001/_block/write
resp = client.indices.add_block(
index="my-index-000001",
block="write",
)const response = await client.indices.addBlock({
index: "my-index-000001",
block: "write",
});response = client.indices.add_block(
index: "my-index-000001",
block: "write"
)$resp = $client->indices()->addBlock([
"index" => "my-index-000001",
"block" => "write",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_block/write"{
"acknowledged" : true,
"shards_acknowledged" : true,
"indices" : [ {
"name" : "my-index-000001",
"blocked" : true
} ]
}All methods and paths for this operation:
The analyze API performs analysis on a text string and returns the resulting tokens.
Generating excessive amount of tokens may cause a node to run out of memory.
The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced.
If more than this limit of tokens gets generated, an error occurs.
The _analyze endpoint without a specified index will always use 10000 as its limit.
indexIndex used to derive the analyzer.
If specified, the analyzer or field parameter overrides this value.
If no index is specified or the index does not have a default analyzer, the analyze API uses the standard analyzer.
Index used to derive the analyzer.
If specified, the analyzer or field parameter overrides this value.
If no index is specified or the index does not have a default analyzer, the analyze API uses the standard analyzer.
The name of the analyzer that should be applied to the provided text.
This could be a built-in analyzer, or an analyzer that’s been configured in the index.
Array of token attributes used to filter the output of the explain parameter.
Array of character filters used to preprocess characters before the tokenizer.
If true, the response includes token attributes and additional details.
Default value is false.
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Array of token filters used to apply after the tokenizer.
Normalizer to use to convert text into a single token.
GET /_analyze
{
"analyzer": "standard",
"text": "this is a test"
}resp = client.indices.analyze(
analyzer="standard",
text="this is a test",
)const response = await client.indices.analyze({
analyzer: "standard",
text: "this is a test",
});response = client.indices.analyze(
body: {
"analyzer": "standard",
"text": "this is a test"
}
)$resp = $client->indices()->analyze([
"body" => [
"analyzer" => "standard",
"text" => "this is a test",
],
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"analyzer":"standard","text":"this is a test"}' "$ELASTICSEARCH_URL/_analyze"client.indices().analyze(a -> a
.analyzer("standard")
.text("this is a test")
);
{
"analyzer": "standard",
"text": "this is a test"
}{
"analyzer": "standard",
"text": [
"this is a test",
"the second text"
]
}{
"tokenizer": "keyword",
"filter": [
"lowercase"
],
"char_filter": [
"html_strip"
],
"text": "this is a <b>test</b>"
}{
"tokenizer": "whitespace",
"filter": [
"lowercase",
{
"type": "stop",
"stopwords": [
"a",
"is",
"this"
]
}
],
"text": "this is a test"
}{
"field": "obj1.field1",
"text": "this is a test"
}{
"normalizer": "my_normalizer",
"text": "BaR"
}{
"tokenizer": "standard",
"filter": [
"snowball"
],
"text": "detailed output",
"explain": true,
"attributes": [
"keyword"
]
}{
"detail": {
"custom_analyzer": true,
"charfilters": [],
"tokenizer": {
"name": "standard",
"tokens": [
{
"token": "detailed",
"start_offset": 0,
"end_offset": 8,
"type": "<ALPHANUM>",
"position": 0
},
{
"token": "output",
"start_offset": 9,
"end_offset": 15,
"type": "<ALPHANUM>",
"position": 1
}
]
},
"tokenfilters": [
{
"name": "snowball",
"tokens": [
{
"token": "detail",
"start_offset": 0,
"end_offset": 8,
"type": "<ALPHANUM>",
"position": 0,
"keyword": false
},
{
"token": "output",
"start_offset": 9,
"end_offset": 15,
"type": "<ALPHANUM>",
"position": 1,
"keyword": false
}
]
}
]
}
}A closed index is blocked for read or write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. Closed indices do not have to maintain internal data structures for indexing or searching documents, which results in a smaller overhead on the cluster.
When opening or closing an index, the master node is responsible for restarting the index shards to reflect the new state of the index. The shards will then go through the normal recovery process. The data of opened and closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.
You can open and close multiple indices.
An error is thrown if the request explicitly refers to a missing index.
This behaviour can be turned off using the ignore_unavailable=true parameter.
By default, you must explicitly name the indices you are opening or closing.
To open or close indices with _all, *, or other wildcard expressions, change theaction.destructive_requires_name setting to false. This setting can also be changed with the cluster update settings API.
Closed indices consume a significant amount of disk-space which can cause problems in managed environments.
Closing indices can be turned off with the cluster settings API by setting cluster.indices.close.enable to false.
manageComma-separated list or wildcard expression of index names used to limit the request.
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.
Type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
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).
Values are all or index-setting.
POST /my-index-00001/_close
resp = client.indices.close(
index="my-index-00001",
)const response = await client.indices.close({
index: "my-index-00001",
});response = client.indices.close(
index: "my-index-00001"
)$resp = $client->indices()->close([
"index" => "my-index-00001",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-00001/_close"{
"acknowledged": true,
"shards_acknowledged": true,
"indices": {
"my-index-000001": {
"closed": true
}
}
}Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported.
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.
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. Supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
If true, returns settings in flat format.
If true, return all default settings in the response.
If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
Return only information on specified index features
Supported values include: aliases, mappings, settings
Values are aliases, mappings, or settings.
GET /my-index-000001
resp = client.indices.get(
index="my-index-000001",
)const response = await client.indices.get({
index: "my-index-000001",
});response = client.indices.get(
index: "my-index-000001"
)$resp = $client->indices()->get([
"index" => "my-index-000001",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001"Get information about whether index templates exist. Index templates define settings, mappings, and aliases that can be applied automatically to new indices.
IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.
manage_index_templatesA comma-separated list of index template names used to limit the request.
Wildcard (*) expressions are supported.
Indicates whether to use a flat format for the response.
Indicates whether to get information from the local node only.
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.
Values are -1 or 0.
HEAD /_template/template_1
resp = client.indices.exists_template(
name="template_1",
)const response = await client.indices.existsTemplate({
name: "template_1",
});response = client.indices.exists_template(
name: "template_1"
)$resp = $client->indices()->existsTemplate([
"name" => "template_1",
]);curl --head -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_template/template_1"Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use.
The response body reports the per-shard usage count of the data structures that back the fields in the index. A given request will increment each count by a maximum value of 1, even if the request accesses the same field multiple times.
manageComma-separated list or wildcard expression of index names used to limit the request.
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.
Type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supports comma-separated values, such as open,hidden.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Comma-separated list or wildcard expressions of fields to include in the statistics.
GET /my-index-000001/_field_usage_stats
resp = client.indices.field_usage_stats(
index="my-index-000001",
)const response = await client.indices.fieldUsageStats({
index: "my-index-000001",
});response = client.indices.field_usage_stats(
index: "my-index-000001"
)$resp = $client->indices()->fieldUsageStats([
"index" => "my-index-000001",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_field_usage_stats"{
"_shards": {
"total": 1,
"successful": 1,
"failed": 0
},
"my-index-000001": {
"shards": [
{
"tracking_id": "MpOl0QlTQ4SYYhEe6KgJoQ",
"tracking_started_at_millis": 1625558985010,
"routing": {
"state": "STARTED",
"primary": true,
"node": "gA6KeeVzQkGURFCUyV-e8Q",
"relocating_node": null
},
"stats": {
"all_fields": {
"any": "6",
"inverted_index": {
"terms": 1,
"postings": 1,
"proximity": 1,
"positions": 0,
"term_frequencies": 1,
"offsets": 0,
"payloads": 0
},
"stored_fields": 2,
"doc_values": 1,
"points": 0,
"norms": 1,
"term_vectors": 0,
"knn_vectors": 0
},
"fields": {
"_id": {
"any": 1,
"inverted_index": {
"terms": 1,
"postings": 1,
"proximity": 1,
"positions": 0,
"term_frequencies": 1,
"offsets": 0,
"payloads": 0
},
"stored_fields": 1,
"doc_values": 0,
"points": 0,
"norms": 0,
"term_vectors": 0,
"knn_vectors": 0
},
"_source": {},
"context": {},
"message.keyword": {}
}
}
}
]
}
}All methods and paths for this operation:
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:
IMPORTANT: Indices can only be split if they satisfy the following requirements:
managePeriod 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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
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).
Values are all or index-setting.
POST /my-index-000001/_split/split-my-index-000001
{
"settings": {
"index.number_of_shards": 2
}
}resp = client.indices.split(
index="my-index-000001",
target="split-my-index-000001",
settings={
"index.number_of_shards": 2
},
)const response = await client.indices.split({
index: "my-index-000001",
target: "split-my-index-000001",
settings: {
"index.number_of_shards": 2,
},
});response = client.indices.split(
index: "my-index-000001",
target: "split-my-index-000001",
body: {
"settings": {
"index.number_of_shards": 2
}
}
)$resp = $client->indices()->split([
"index" => "my-index-000001",
"target" => "split-my-index-000001",
"body" => [
"settings" => [
"index.number_of_shards" => 2,
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"index.number_of_shards":2}}' "$ELASTICSEARCH_URL/my-index-000001/_split/split-my-index-000001"client.indices().split(s -> s
.index("my-index-000001")
.settings("index.number_of_shards", JsonData.fromJson("2"))
.target("split-my-index-000001")
);
{
"settings": {
"index.number_of_shards": 2
}
}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.
Type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supports comma-separated values, such as open,hidden.
Valid values are: all, open, closed, hidden, none.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
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}/_unfreeze' \
--header "Authorization: $API_KEY"Adds a data stream or index to an alias.
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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST _aliases
{
"actions": [
{
"add": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
]
}resp = client.indices.update_aliases(
actions=[
{
"add": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
],
)const response = await client.indices.updateAliases({
actions: [
{
add: {
index: "logs-nginx.access-prod",
alias: "logs",
},
},
],
});response = client.indices.update_aliases(
body: {
"actions": [
{
"add": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
]
}
)$resp = $client->indices()->updateAliases([
"body" => [
"actions" => array(
[
"add" => [
"index" => "logs-nginx.access-prod",
"alias" => "logs",
],
],
),
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"actions":[{"add":{"index":"logs-nginx.access-prod","alias":"logs"}}]}' "$ELASTICSEARCH_URL/_aliases"client.indices().updateAliases(u -> u
.actions(a -> a
.add(ad -> ad
.alias("logs")
.index("logs-nginx.access-prod")
)
)
);
{
"actions": [
{
"add": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
}
]
}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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
DELETE _ilm/policy/my_policy
resp = client.ilm.delete_lifecycle(
name="my_policy",
)const response = await client.ilm.deleteLifecycle({
name: "my_policy",
});response = client.ilm.delete_lifecycle(
policy: "my_policy"
)$resp = $client->ilm()->deleteLifecycle([
"policy" => "my_policy",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ilm/policy/my_policy"{
"acknowledged": true
}Switch the indices, ILM policies, and legacy, composable, and component templates from using custom node attributes and attribute-based allocation filters to using data tiers. Optionally, delete one legacy index template. Using node roles enables ILM to automatically move the indices between data tiers.
Migrating away from custom node attributes routing can be manually performed. This API provides an automated way of performing three out of the four manual steps listed in the migration guide:
ILM must be stopped before performing the migration.
Use the stop ILM and get ILM status APIs to wait until the reported operation mode is STOPPED.
If true, simulates the migration from node attributes based allocation filters to data tiers, but does not perform the migration. This provides a way to retrieve the indices and ILM policies that need to be migrated.
POST /_ilm/migrate_to_data_tiers
{
"legacy_template_to_delete": "global-template",
"node_attribute": "custom_attribute_name"
}resp = client.ilm.migrate_to_data_tiers(
legacy_template_to_delete="global-template",
node_attribute="custom_attribute_name",
)const response = await client.ilm.migrateToDataTiers({
legacy_template_to_delete: "global-template",
node_attribute: "custom_attribute_name",
});response = client.ilm.migrate_to_data_tiers(
body: {
"legacy_template_to_delete": "global-template",
"node_attribute": "custom_attribute_name"
}
)$resp = $client->ilm()->migrateToDataTiers([
"body" => [
"legacy_template_to_delete" => "global-template",
"node_attribute" => "custom_attribute_name",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"legacy_template_to_delete":"global-template","node_attribute":"custom_attribute_name"}' "$ELASTICSEARCH_URL/_ilm/migrate_to_data_tiers"client.ilm().migrateToDataTiers(m -> m
.legacyTemplateToDelete("global-template")
.nodeAttribute("custom_attribute_name")
);
{
"legacy_template_to_delete": "global-template",
"node_attribute": "custom_attribute_name"
}{
"dry_run": false,
"removed_legacy_template":"global-template",
"migrated_ilm_policies":["policy_with_allocate_action"],
"migrated_indices":["warm-index-to-migrate-000001"],
"migrated_legacy_templates":["a-legacy-template"],
"migrated_composable_templates":["a-composable-template"],
"migrated_component_templates":["a-component-template"]
}POST /my-index-000001/_ilm/retry
resp = client.ilm.retry(
index="my-index-000001",
)const response = await client.ilm.retry({
index: "my-index-000001",
});response = client.ilm.retry(
index: "my-index-000001"
)$resp = $client->ilm()->retry([
"index" => "my-index-000001",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_ilm/retry"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.
manage_ilmPeriod 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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
POST _ilm/stop
resp = client.ilm.stop()const response = await client.ilm.stop();response = client.ilm.stop$resp = $client->ilm()->stop();curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ilm/stop"{
"acknowledged": true
}All methods and paths for this operation:
The task type
Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.
The inference identifier.
DELETE /_inference/sparse_embedding/my-elser-model
resp = client.inference.delete(
task_type="sparse_embedding",
inference_id="my-elser-model",
)const response = await client.inference.delete({
task_type: "sparse_embedding",
inference_id: "my-elser-model",
});response = client.inference.delete(
task_type: "sparse_embedding",
inference_id: "my-elser-model"
)$resp = $client->inference()->delete([
"task_type" => "sparse_embedding",
"inference_id" => "my-elser-model",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model"The task type.
The only valid task type for the model to perform is completion.
Value is completion.
The unique identifier of the inference endpoint.
PUT _inference/completion/anthropic_completion
{
"service": "anthropic",
"service_settings": {
"api_key": "Anthropic-Api-Key",
"model_id": "Model-ID"
},
"task_settings": {
"max_tokens": 1024
}
}resp = client.inference.put(
task_type="completion",
inference_id="anthropic_completion",
inference_config={
"service": "anthropic",
"service_settings": {
"api_key": "Anthropic-Api-Key",
"model_id": "Model-ID"
},
"task_settings": {
"max_tokens": 1024
}
},
)const response = await client.inference.put({
task_type: "completion",
inference_id: "anthropic_completion",
inference_config: {
service: "anthropic",
service_settings: {
api_key: "Anthropic-Api-Key",
model_id: "Model-ID",
},
task_settings: {
max_tokens: 1024,
},
},
});response = client.inference.put(
task_type: "completion",
inference_id: "anthropic_completion",
body: {
"service": "anthropic",
"service_settings": {
"api_key": "Anthropic-Api-Key",
"model_id": "Model-ID"
},
"task_settings": {
"max_tokens": 1024
}
}
)$resp = $client->inference()->put([
"task_type" => "completion",
"inference_id" => "anthropic_completion",
"body" => [
"service" => "anthropic",
"service_settings" => [
"api_key" => "Anthropic-Api-Key",
"model_id" => "Model-ID",
],
"task_settings" => [
"max_tokens" => 1024,
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"anthropic","service_settings":{"api_key":"Anthropic-Api-Key","model_id":"Model-ID"},"task_settings":{"max_tokens":1024}}' "$ELASTICSEARCH_URL/_inference/completion/anthropic_completion"client.inference().put(p -> p
.inferenceId("anthropic_completion")
.taskType(TaskType.Completion)
.inferenceConfig(i -> i
.service("anthropic")
.serviceSettings(JsonData.fromJson("{\"api_key\":\"Anthropic-Api-Key\",\"model_id\":\"Model-ID\"}"))
.taskSettings(JsonData.fromJson("{\"max_tokens\":1024}"))
)
);
{
"service": "anthropic",
"service_settings": {
"api_key": "Anthropic-Api-Key",
"model_id": "Model-ID"
},
"task_settings": {
"max_tokens": 1024
}
}The type of the inference task that the model will perform.
Values are completion or text_embedding.
The unique identifier of the inference endpoint.
PUT _inference/text_embedding/azure_ai_studio_embeddings
{
"service": "azureaistudio",
"service_settings": {
"api_key": "Azure-AI-Studio-API-key",
"target": "Target-Uri",
"provider": "openai",
"endpoint_type": "token"
}
}resp = client.inference.put(
task_type="text_embedding",
inference_id="azure_ai_studio_embeddings",
inference_config={
"service": "azureaistudio",
"service_settings": {
"api_key": "Azure-AI-Studio-API-key",
"target": "Target-Uri",
"provider": "openai",
"endpoint_type": "token"
}
},
)const response = await client.inference.put({
task_type: "text_embedding",
inference_id: "azure_ai_studio_embeddings",
inference_config: {
service: "azureaistudio",
service_settings: {
api_key: "Azure-AI-Studio-API-key",
target: "Target-Uri",
provider: "openai",
endpoint_type: "token",
},
},
});response = client.inference.put(
task_type: "text_embedding",
inference_id: "azure_ai_studio_embeddings",
body: {
"service": "azureaistudio",
"service_settings": {
"api_key": "Azure-AI-Studio-API-key",
"target": "Target-Uri",
"provider": "openai",
"endpoint_type": "token"
}
}
)$resp = $client->inference()->put([
"task_type" => "text_embedding",
"inference_id" => "azure_ai_studio_embeddings",
"body" => [
"service" => "azureaistudio",
"service_settings" => [
"api_key" => "Azure-AI-Studio-API-key",
"target" => "Target-Uri",
"provider" => "openai",
"endpoint_type" => "token",
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"azureaistudio","service_settings":{"api_key":"Azure-AI-Studio-API-key","target":"Target-Uri","provider":"openai","endpoint_type":"token"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/azure_ai_studio_embeddings"client.inference().put(p -> p
.inferenceId("azure_ai_studio_embeddings")
.taskType(TaskType.TextEmbedding)
.inferenceConfig(i -> i
.service("azureaistudio")
.serviceSettings(JsonData.fromJson("{\"api_key\":\"Azure-AI-Studio-API-key\",\"target\":\"Target-Uri\",\"provider\":\"openai\",\"endpoint_type\":\"token\"}"))
)
);
{
"service": "azureaistudio",
"service_settings": {
"api_key": "Azure-AI-Studio-API-key",
"target": "Target-Uri",
"provider": "openai",
"endpoint_type": "token"
}
}{
"service": "azureaistudio",
"service_settings": {
"api_key": "Azure-AI-Studio-API-key",
"target": "Target-URI",
"provider": "databricks",
"endpoint_type": "realtime"
}
}Specifies the amount of time to wait for the inference request to complete.
Values are -1 or 0.
POST _inference/sparse_embedding/my-elser-model
{
"input": "The sky above the port was the color of television tuned to a dead channel."
}resp = client.inference.sparse_embedding(
inference_id="my-elser-model",
input="The sky above the port was the color of television tuned to a dead channel.",
)const response = await client.inference.sparseEmbedding({
inference_id: "my-elser-model",
input:
"The sky above the port was the color of television tuned to a dead channel.",
});response = client.inference.sparse_embedding(
inference_id: "my-elser-model",
body: {
"input": "The sky above the port was the color of television tuned to a dead channel."
}
)$resp = $client->inference()->sparseEmbedding([
"inference_id" => "my-elser-model",
"body" => [
"input" => "The sky above the port was the color of television tuned to a dead channel.",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"input":"The sky above the port was the color of television tuned to a dead channel."}' "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model"client.inference().sparseEmbedding(s -> s
.inferenceId("my-elser-model")
.input("The sky above the port was the color of television tuned to a dead channel.")
);
{
"input": "The sky above the port was the color of television tuned to a dead channel."
}{
"sparse_embedding": [
{
"port": 2.1259406,
"sky": 1.7073475,
"color": 1.6922266,
"dead": 1.6247464,
"television": 1.3525393,
"above": 1.2425821,
"tuned": 1.1440028,
"colors": 1.1218185,
"tv": 1.0111054,
"ports": 1.0067928,
"poem": 1.0042328,
"channel": 0.99471164,
"tune": 0.96235967,
"scene": 0.9020516
}
]
}All methods and paths for this operation:
Get information about one or more IP geolocation database configurations.
curl \
--request GET 'http://api.example.com/_ingest/geoip/database/{id}' \
--header "Authorization: $API_KEY"Refer to the create or update IP geolocation database configuration API.
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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
curl \
--request PUT 'http://api.example.com/_ingest/geoip/database/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"string","maxmind":{"account_id":"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.
A value of -1 indicates that the request should never time out.
Values are -1 or 0.
The period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.
A value of -1 indicates that the request should never time out.
Values are -1 or 0.
DELETE /_ingest/ip_location/database/my-database-id
resp = client.ingest.delete_ip_location_database(
id="my-database-id",
)const response = await client.ingest.deleteIpLocationDatabase({
id: "my-database-id",
});response = client.ingest.delete_ip_location_database(
id: "my-database-id"
)$resp = $client->ingest()->deleteIpLocationDatabase([
"id" => "my-database-id",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ingest/ip_location/database/my-database-id"All methods and paths for this operation:
Get information about one or more ingest pipelines. This API returns a local reference of the pipeline.
Comma-separated list of pipeline IDs to retrieve.
Wildcard (*) expressions are supported.
To get all ingest pipelines, omit this parameter or use *.
GET /_ingest/pipeline/my-pipeline-id
resp = client.ingest.get_pipeline(
id="my-pipeline-id",
)const response = await client.ingest.getPipeline({
id: "my-pipeline-id",
});response = client.ingest.get_pipeline(
id: "my-pipeline-id"
)$resp = $client->ingest()->getPipeline([
"id" => "my-pipeline-id",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ingest/pipeline/my-pipeline-id"{
"my-pipeline-id" : {
"description" : "describe pipeline",
"version" : 123,
"processors" : [
{
"set" : {
"field" : "foo",
"value" : "bar"
}
}
]
}
}Delete one or more ingest pipelines.
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 *.
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 -1 or 0.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
DELETE /_ingest/pipeline/my-pipeline-id
resp = client.ingest.delete_pipeline(
id="my-pipeline-id",
)const response = await client.ingest.deletePipeline({
id: "my-pipeline-id",
});response = client.ingest.delete_pipeline(
id: "my-pipeline-id"
)$resp = $client->ingest()->deletePipeline([
"id" => "my-pipeline-id",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ingest/pipeline/my-pipeline-id"All methods and paths for this operation:
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.
read_pipelineThe pipeline to test.
If you don't specify a pipeline in the request body, this parameter is required.
If true, the response includes output data for each processor in the executed pipeline.
POST /_ingest/pipeline/_simulate
{
"pipeline" :
{
"description": "_description",
"processors": [
{
"set" : {
"field" : "field2",
"value" : "_value"
}
}
]
},
"docs": [
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "bar"
}
},
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "rab"
}
}
]
}resp = client.ingest.simulate(
pipeline={
"description": "_description",
"processors": [
{
"set": {
"field": "field2",
"value": "_value"
}
}
]
},
docs=[
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "bar"
}
},
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "rab"
}
}
],
)const response = await client.ingest.simulate({
pipeline: {
description: "_description",
processors: [
{
set: {
field: "field2",
value: "_value",
},
},
],
},
docs: [
{
_index: "index",
_id: "id",
_source: {
foo: "bar",
},
},
{
_index: "index",
_id: "id",
_source: {
foo: "rab",
},
},
],
});response = client.ingest.simulate(
body: {
"pipeline": {
"description": "_description",
"processors": [
{
"set": {
"field": "field2",
"value": "_value"
}
}
]
},
"docs": [
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "bar"
}
},
{
"_index": "index",
"_id": "id",
"_source": {
"foo": "rab"
}
}
]
}
)$resp = $client->ingest()->simulate([
"body" => [
"pipeline" => [
"description" => "_description",
"processors" => array(
[
"set" => [
"field" => "field2",
"value" => "_value",
],
],
),
],
"docs" => array(
[
"_index" => "index",
"_id" => "id",
"_source" => [
"foo" => "bar",
],
],
[
"_index" => "index",
"_id" => "id",
"_source" => [
"foo" => "rab",
],
],
),
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"pipeline":{"description":"_description","processors":[{"set":{"field":"field2","value":"_value"}}]},"docs":[{"_index":"index","_id":"id","_source":{"foo":"bar"}},{"_index":"index","_id":"id","_source":{"foo":"rab"}}]}' "$ELASTICSEARCH_URL/_ingest/pipeline/_simulate"client.ingest().simulate(s -> s
.docs(List.of(Document.of(d -> d
.id("id")
.index("index")
.source(JsonData.fromJson("{\"foo\":\"bar\"}"))),Document.of(d -> d
.id("id")
.index("index")
.source(JsonData.fromJson("{\"foo\":\"rab\"}")))))
.pipeline(p -> p
.description("_description")
.processors(pr -> pr
.set(se -> se
.field("field2")
.value(JsonData.fromJson("\"_value\""))
)
)
)
);
{
"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"
}
}
}
]
}Licensing APIs enable you to manage your licenses.
All methods and paths for this operation:
You can update your license at runtime without shutting down your nodes. License updates take effect immediately. If the license you are installing does not support all of the features that were available with your previous license, however, you are notified in the response. You must then re-submit the API request with the acknowledge parameter set to true.
NOTE: If Elasticsearch security features are enabled and you are installing a gold or higher license, you must enable TLS on the transport networking layer before you install the license. If the operator privileges feature is enabled, only operator users can use this API.
manageSpecifies whether you acknowledge the license changes.
The period to wait for a connection to the master node.
Values are -1 or 0.
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 -1 or 0.
PUT _license
{
"licenses": [
{
"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
"type":"basic",
"issue_date_in_millis":1411948800000,
"expiry_date_in_millis":1914278399999,
"max_nodes":1,
"issued_to":"issuedTo",
"issuer":"issuer",
"signature":"xx"
}
]
}resp = client.license.post(
licenses=[
{
"uid": "893361dc-9749-4997-93cb-802e3d7fa4xx",
"type": "basic",
"issue_date_in_millis": 1411948800000,
"expiry_date_in_millis": 1914278399999,
"max_nodes": 1,
"issued_to": "issuedTo",
"issuer": "issuer",
"signature": "xx"
}
],
)const response = await client.license.post({
licenses: [
{
uid: "893361dc-9749-4997-93cb-802e3d7fa4xx",
type: "basic",
issue_date_in_millis: 1411948800000,
expiry_date_in_millis: 1914278399999,
max_nodes: 1,
issued_to: "issuedTo",
issuer: "issuer",
signature: "xx",
},
],
});response = client.license.post(
body: {
"licenses": [
{
"uid": "893361dc-9749-4997-93cb-802e3d7fa4xx",
"type": "basic",
"issue_date_in_millis": 1411948800000,
"expiry_date_in_millis": 1914278399999,
"max_nodes": 1,
"issued_to": "issuedTo",
"issuer": "issuer",
"signature": "xx"
}
]
}
)$resp = $client->license()->post([
"body" => [
"licenses" => array(
[
"uid" => "893361dc-9749-4997-93cb-802e3d7fa4xx",
"type" => "basic",
"issue_date_in_millis" => 1411948800000,
"expiry_date_in_millis" => 1914278399999,
"max_nodes" => 1,
"issued_to" => "issuedTo",
"issuer" => "issuer",
"signature" => "xx",
],
),
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"licenses":[{"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx","type":"basic","issue_date_in_millis":1411948800000,"expiry_date_in_millis":1914278399999,"max_nodes":1,"issued_to":"issuedTo","issuer":"issuer","signature":"xx"}]}' "$ELASTICSEARCH_URL/_license"client.license().post(p -> p
.licenses(l -> l
.expiryDateInMillis(1914278399999L)
.issueDateInMillis(1411948800000L)
.issuedTo("issuedTo")
.issuer("issuer")
.maxNodes(1L)
.signature("xx")
.type(LicenseType.Basic)
.uid("893361dc-9749-4997-93cb-802e3d7fa4xx")
)
);
{
"licenses": [
{
"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
"type":"basic",
"issue_date_in_millis":1411948800000,
"expiry_date_in_millis":1914278399999,
"max_nodes":1,
"issued_to":"issuedTo",
"issuer":"issuer",
"signature":"xx"
}
]
}{
"acknowledged": false,
"license_status": "valid",
"acknowledge": {
"message": "\"\"\"This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the \"acknowledge=true\" parameter:\"\"\"",
"watcher": [
"Watcher will be disabled"
],
"logstash": [
"Logstash will no longer poll for centrally-managed pipelines"
],
"security": [
"The following X-Pack security functionality will be disabled ..."
]
}
}GET /_license/basic_status
resp = client.license.get_basic_status()const response = await client.license.getBasicStatus();response = client.license.get_basic_status$resp = $client->license()->getBasicStatus();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_license/basic_status"client.license().getBasicStatus();
{
"eligible_to_start_basic": true
}A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.
manage_mlIdentifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. You can close multiple anomaly detection jobs in a single API request by using a group name, a comma-separated list of jobs, or a wildcard expression. You can close all jobs by using _all or by specifying * as the job identifier.
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; or contains wildcard expressions and there are only partial matches. By default, it returns an empty jobs array when there are no matches and the subset of results when there are partial matches.
If false, the request returns a 404 status code when there are no matches or only partial matches.
Use to close a failed job, or to forcefully close a job which has not responded to its initial close request; the request returns without performing the associated actions such as flushing buffers and persisting the model snapshots.
If you want the job to be in a consistent state after the close job API returns, do not set to true. This parameter should be used only in situations where the job has already failed or where you are not interested in results the job might have recently produced or might produce in the future.
Controls the time to wait until a job has closed.
Values are -1 or 0.
Refer to the description for the allow_no_match query parameter.
Default value is true.
Refer to the descriptiion for the force query parameter.
Default value is false.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
POST _ml/anomaly_detectors/low_request_rate/_close
resp = client.ml.close_job(
job_id="low_request_rate",
)const response = await client.ml.closeJob({
job_id: "low_request_rate",
});response = client.ml.close_job(
job_id: "low_request_rate"
)$resp = $client->ml()->closeJob([
"job_id" => "low_request_rate",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/_close"client.ml().closeJob(c -> c
.jobId("low_request_rate")
);
{
"closed": true
}DELETE _ml/calendars/planned-outages/jobs/total-requests
resp = client.ml.delete_calendar_job(
calendar_id="planned-outages",
job_id="total-requests",
)const response = await client.ml.deleteCalendarJob({
calendar_id: "planned-outages",
job_id: "total-requests",
});response = client.ml.delete_calendar_job(
calendar_id: "planned-outages",
job_id: "total-requests"
)$resp = $client->ml()->deleteCalendarJob([
"calendar_id" => "planned-outages",
"job_id" => "total-requests",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages/jobs/total-requests"{
"calendar_id": "planned-outages",
"job_ids": []
}PUT _ml/filters/safe_domains
{
"description": "A list of safe domains",
"items": ["*.google.com", "wikipedia.org"]
}resp = client.ml.put_filter(
filter_id="safe_domains",
description="A list of safe domains",
items=[
"*.google.com",
"wikipedia.org"
],
)const response = await client.ml.putFilter({
filter_id: "safe_domains",
description: "A list of safe domains",
items: ["*.google.com", "wikipedia.org"],
});response = client.ml.put_filter(
filter_id: "safe_domains",
body: {
"description": "A list of safe domains",
"items": [
"*.google.com",
"wikipedia.org"
]
}
)$resp = $client->ml()->putFilter([
"filter_id" => "safe_domains",
"body" => [
"description" => "A list of safe domains",
"items" => array(
"*.google.com",
"wikipedia.org",
),
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"description":"A list of safe domains","items":["*.google.com","wikipedia.org"]}' "$ELASTICSEARCH_URL/_ml/filters/safe_domains"client.ml().putFilter(p -> p
.description("A list of safe domains")
.filterId("safe_domains")
.items(List.of("*.google.com","wikipedia.org"))
);
{
"description": "A list of safe domains",
"items": ["*.google.com", "wikipedia.org"]
}Identifier for the anomaly detection job. The job must be open when you create a forecast; otherwise, an error occurs.
A period of time that indicates how far into the future to forecast. For
example, 30d corresponds to 30 days. The forecast starts at the last
record that was processed.
Values are -1 or 0.
The period of time that forecast results are retained. After a forecast expires, the results are deleted. If set to a value of 0, the forecast is never automatically deleted.
Values are -1 or 0.
The maximum memory the forecast can use. If the forecast needs to use more than the provided amount, it will spool to disk. Default is 20mb, maximum is 500mb and minimum is 1mb. If set to 40% or more of the job’s configured memory limit, it is automatically reduced to below that amount.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and
d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
Refer to the description for the max_model_memory query parameter.
Default value is 20mb.
POST _ml/anomaly_detectors/low_request_rate/_forecast
{
"duration": "10d"
}resp = client.ml.forecast(
job_id="low_request_rate",
duration="10d",
)const response = await client.ml.forecast({
job_id: "low_request_rate",
duration: "10d",
});response = client.ml.forecast(
job_id: "low_request_rate",
body: {
"duration": "10d"
}
)$resp = $client->ml()->forecast([
"job_id" => "low_request_rate",
"body" => [
"duration" => "10d",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"duration":"10d"}' "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/_forecast"client.ml().forecast(f -> f
.duration(d -> d
.time("10d")
)
.jobId("low_request_rate")
);
{
"duration": "10d"
}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.
Specifies what to do when the request:
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.
GET _ml/anomaly_detectors/low_request_rate/model_snapshots/_all/_upgrade/_stats
resp = client.ml.get_model_snapshot_upgrade_stats(
job_id="low_request_rate",
snapshot_id="_all",
)const response = await client.ml.getModelSnapshotUpgradeStats({
job_id: "low_request_rate",
snapshot_id: "_all",
});response = client.ml.get_model_snapshot_upgrade_stats(
job_id: "low_request_rate",
snapshot_id: "_all"
)$resp = $client->ml()->getModelSnapshotUpgradeStats([
"job_id" => "low_request_rate",
"snapshot_id" => "_all",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/model_snapshots/_all/_upgrade/_stats"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.
manage_mlPOST /_ml/anomaly_detectors/job-01/_open
{
"timeout": "35m"
}resp = client.ml.open_job(
job_id="job-01",
timeout="35m",
)const response = await client.ml.openJob({
job_id: "job-01",
timeout: "35m",
});response = client.ml.open_job(
job_id: "job-01",
body: {
"timeout": "35m"
}
)$resp = $client->ml()->openJob([
"job_id" => "job-01",
"body" => [
"timeout" => "35m",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"timeout":"35m"}' "$ELASTICSEARCH_URL/_ml/anomaly_detectors/job-01/_open"client.ml().openJob(o -> o
.jobId("job-01")
.timeout(t -> t
.time("35m")
)
);
{
"timeout": "35m"
}{
"opened": true,
"node": "node-1"
}All methods and paths for this operation:
This API returns the first "page" of search results from a datafeed. You can preview an existing datafeed or provide configuration details for a datafeed and anomaly detection job in the API. The preview shows the structure of the data that will be passed to the anomaly detection engine. IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. You can also use secondary authorization headers to supply the credentials.
readmanage_mlA 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. NOTE: If you use this path parameter, you cannot provide datafeed or anomaly detection job configuration details in the request body.
The start time from where the datafeed preview should begin
The end time when the datafeed preview should stop
GET _ml/datafeeds/datafeed-high_sum_total_sales/_preview
resp = client.ml.preview_datafeed(
datafeed_id="datafeed-high_sum_total_sales",
)const response = await client.ml.previewDatafeed({
datafeed_id: "datafeed-high_sum_total_sales",
});response = client.ml.preview_datafeed(
datafeed_id: "datafeed-high_sum_total_sales"
)$resp = $client->ml()->previewDatafeed([
"datafeed_id" => "datafeed-high_sum_total_sales",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/datafeeds/datafeed-high_sum_total_sales/_preview"client.ml().previewDatafeed(p -> p
.datafeedId("datafeed-high_sum_total_sales")
);
POST _ml/anomaly_detectors/total-requests/_reset
resp = client.ml.reset_job(
job_id="total-requests",
)const response = await client.ml.resetJob({
job_id: "total-requests",
});response = client.ml.reset_job(
job_id: "total-requests"
)$resp = $client->ml()->resetJob([
"job_id" => "total-requests",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/anomaly_detectors/total-requests/_reset"This API creates a data frame analytics job that performs an analysis on the
source indices and stores the outcome in a destination index.
By default, the query used in the source configuration is {"match_all": {}}.
If the destination index does not exist, it is created automatically when you start the job.
If you supply only a subset of the regression or classification parameters, hyperparameter optimization occurs. It determines a value for each of the undefined parameters.
create_index,index,manage,read,view_index_metadatamanage_mlIdentifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.
Specifies whether this job can start when there is insufficient machine
learning node capacity for it to be immediately assigned to a node. If
set to false and a machine learning node with capacity to run the job
cannot be immediately found, the API returns an error. If set to true,
the API does not return an error; the job waits in the starting state
until sufficient machine learning node capacity is available. This
behavior is also affected by the cluster-wide
xpack.ml.max_lazy_ml_nodes setting.
Default value is false.
A description of the job.
The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.
Default value is 1.
The approximate maximum amount of memory resources that are permitted for
analytical processing. If your elasticsearch.yml file contains an
xpack.ml.max_model_memory_limit setting, an error occurs when you try
to create data frame analytics jobs that have model_memory_limit values
greater than that setting.
Default value is 1gb.
PUT _ml/data_frame/analytics/model-flight-delays-pre
{
"source": {
"index": [
"kibana_sample_data_flights"
],
"query": {
"range": {
"DistanceKilometers": {
"gt": 0
}
}
},
"_source": {
"includes": [],
"excludes": [
"FlightDelay",
"FlightDelayType"
]
}
},
"dest": {
"index": "df-flight-delays",
"results_field": "ml-results"
},
"analysis": {
"regression": {
"dependent_variable": "FlightDelayMin",
"training_percent": 90
}
},
"analyzed_fields": {
"includes": [],
"excludes": [
"FlightNum"
]
},
"model_memory_limit": "100mb"
}resp = client.ml.put_data_frame_analytics(
id="model-flight-delays-pre",
source={
"index": [
"kibana_sample_data_flights"
],
"query": {
"range": {
"DistanceKilometers": {
"gt": 0
}
}
},
"_source": {
"includes": [],
"excludes": [
"FlightDelay",
"FlightDelayType"
]
}
},
dest={
"index": "df-flight-delays",
"results_field": "ml-results"
},
analysis={
"regression": {
"dependent_variable": "FlightDelayMin",
"training_percent": 90
}
},
analyzed_fields={
"includes": [],
"excludes": [
"FlightNum"
]
},
model_memory_limit="100mb",
)const response = await client.ml.putDataFrameAnalytics({
id: "model-flight-delays-pre",
source: {
index: ["kibana_sample_data_flights"],
query: {
range: {
DistanceKilometers: {
gt: 0,
},
},
},
_source: {
includes: [],
excludes: ["FlightDelay", "FlightDelayType"],
},
},
dest: {
index: "df-flight-delays",
results_field: "ml-results",
},
analysis: {
regression: {
dependent_variable: "FlightDelayMin",
training_percent: 90,
},
},
analyzed_fields: {
includes: [],
excludes: ["FlightNum"],
},
model_memory_limit: "100mb",
});response = client.ml.put_data_frame_analytics(
id: "model-flight-delays-pre",
body: {
"source": {
"index": [
"kibana_sample_data_flights"
],
"query": {
"range": {
"DistanceKilometers": {
"gt": 0
}
}
},
"_source": {
"includes": [],
"excludes": [
"FlightDelay",
"FlightDelayType"
]
}
},
"dest": {
"index": "df-flight-delays",
"results_field": "ml-results"
},
"analysis": {
"regression": {
"dependent_variable": "FlightDelayMin",
"training_percent": 90
}
},
"analyzed_fields": {
"includes": [],
"excludes": [
"FlightNum"
]
},
"model_memory_limit": "100mb"
}
)$resp = $client->ml()->putDataFrameAnalytics([
"id" => "model-flight-delays-pre",
"body" => [
"source" => [
"index" => array(
"kibana_sample_data_flights",
),
"query" => [
"range" => [
"DistanceKilometers" => [
"gt" => 0,
],
],
],
"_source" => [
"includes" => array(
),
"excludes" => array(
"FlightDelay",
"FlightDelayType",
),
],
],
"dest" => [
"index" => "df-flight-delays",
"results_field" => "ml-results",
],
"analysis" => [
"regression" => [
"dependent_variable" => "FlightDelayMin",
"training_percent" => 90,
],
],
"analyzed_fields" => [
"includes" => array(
),
"excludes" => array(
"FlightNum",
),
],
"model_memory_limit" => "100mb",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"source":{"index":["kibana_sample_data_flights"],"query":{"range":{"DistanceKilometers":{"gt":0}}},"_source":{"includes":[],"excludes":["FlightDelay","FlightDelayType"]}},"dest":{"index":"df-flight-delays","results_field":"ml-results"},"analysis":{"regression":{"dependent_variable":"FlightDelayMin","training_percent":90}},"analyzed_fields":{"includes":[],"excludes":["FlightNum"]},"model_memory_limit":"100mb"}' "$ELASTICSEARCH_URL/_ml/data_frame/analytics/model-flight-delays-pre"client.ml().putDataFrameAnalytics(p -> p
.analysis(a -> a
.regression(r -> r
.dependentVariable("FlightDelayMin")
.trainingPercent("90")
)
)
.analyzedFields(an -> an
.excludes("FlightNum")
)
.dest(d -> d
.index("df-flight-delays")
.resultsField("ml-results")
)
.id("model-flight-delays-pre")
.modelMemoryLimit("100mb")
.source(s -> s
.index("kibana_sample_data_flights")
.query(q -> q
.range(r -> r
.untyped(u -> u
.field("DistanceKilometers")
.gt(JsonData.fromJson("0"))
)
)
)
.source(so -> so
.excludes(List.of("FlightDelay","FlightDelayType"))
)
)
);
{
"source": {
"index": [
"kibana_sample_data_flights"
],
"query": {
"range": {
"DistanceKilometers": {
"gt": 0
}
}
},
"_source": {
"includes": [],
"excludes": [
"FlightDelay",
"FlightDelayType"
]
}
},
"dest": {
"index": "df-flight-delays",
"results_field": "ml-results"
},
"analysis": {
"regression": {
"dependent_variable": "FlightDelayMin",
"training_percent": 90
}
},
"analyzed_fields": {
"includes": [],
"excludes": [
"FlightNum"
]
},
"model_memory_limit": "100mb"
}The API packages together commonly used evaluation metrics for various types of machine learning features. This has been designed for use on indexes created by data frame analytics. Evaluation requires both a ground truth field and an analytics result field to be present.
monitor_mlAn Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
POST _ml/data_frame/_evaluate
{
"index": "animal_classification",
"evaluation": {
"classification": {
"actual_field": "animal_class",
"predicted_field": "ml.animal_class_prediction",
"metrics": {
"multiclass_confusion_matrix": {}
}
}
}
}resp = client.ml.evaluate_data_frame(
index="animal_classification",
evaluation={
"classification": {
"actual_field": "animal_class",
"predicted_field": "ml.animal_class_prediction",
"metrics": {
"multiclass_confusion_matrix": {}
}
}
},
)const response = await client.ml.evaluateDataFrame({
index: "animal_classification",
evaluation: {
classification: {
actual_field: "animal_class",
predicted_field: "ml.animal_class_prediction",
metrics: {
multiclass_confusion_matrix: {},
},
},
},
});response = client.ml.evaluate_data_frame(
body: {
"index": "animal_classification",
"evaluation": {
"classification": {
"actual_field": "animal_class",
"predicted_field": "ml.animal_class_prediction",
"metrics": {
"multiclass_confusion_matrix": {}
}
}
}
}
)$resp = $client->ml()->evaluateDataFrame([
"body" => [
"index" => "animal_classification",
"evaluation" => [
"classification" => [
"actual_field" => "animal_class",
"predicted_field" => "ml.animal_class_prediction",
"metrics" => [
"multiclass_confusion_matrix" => new ArrayObject([]),
],
],
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":"animal_classification","evaluation":{"classification":{"actual_field":"animal_class","predicted_field":"ml.animal_class_prediction","metrics":{"multiclass_confusion_matrix":{}}}}}' "$ELASTICSEARCH_URL/_ml/data_frame/_evaluate"client.ml().evaluateDataFrame(e -> e
.evaluation(ev -> ev
.classification(c -> c
.actualField("animal_class")
.predictedField("ml.animal_class_prediction")
.metrics(m -> m)
)
)
.index("animal_classification")
);
{
"index": "animal_classification",
"evaluation": {
"classification": {
"actual_field": "animal_class",
"predicted_field": "ml.animal_class_prediction",
"metrics": {
"multiclass_confusion_matrix": {}
}
}
}
}{
"index": "animal_classification",
"evaluation": {
"classification": {
"actual_field": "animal_class",
"metrics": {
"auc_roc": {
"class_name": "dog"
}
}
}
}
}{
"index": "my_analytics_dest_index",
"evaluation": {
"outlier_detection": {
"actual_field": "is_outlier",
"predicted_probability_field": "ml.outlier_score"
}
}
}{
"index": "house_price_predictions",
"query": {
"bool": {
"filter": [
{
"term": {
"ml.is_training": false
}
}
]
}
},
"evaluation": {
"regression": {
"actual_field": "price",
"predicted_field": "ml.price_prediction",
"metrics": {
"r_squared": {},
"mse": {},
"msle": {
"offset": 10
},
"huber": {
"delta": 1.5
}
}
}
}
}{
"index": "house_price_predictions",
"query": {
"term": {
"ml.is_training": {
"value": true
}
}
},
"evaluation": {
"regression": {
"actual_field": "price",
"predicted_field": "ml.price_prediction",
"metrics": {
"r_squared": {},
"mse": {},
"msle": {},
"huber": {}
}
}
}
}{
"classification": {
"multiclass_confusion_matrix": {
"confusion_matrix": [
{
"actual_class": "cat",
"actual_class_doc_count": 12,
"predicted_classes": [
{
"predicted_class": "cat",
"count": 12
},
{
"predicted_class": "dog",
"count": 0
}
],
"other_predicted_class_doc_count": 0
},
{
"actual_class": "dog",
"actual_class_doc_count": 11,
"predicted_classes": [
{
"predicted_class": "dog",
"count": 7
},
{
"predicted_class": "cat",
"count": 4
}
],
"other_predicted_class_doc_count": 0
}
],
"other_actual_class_count": 0
}
}
}{
"classification": {
"auc_roc": {
"value": 0.8941788639536681
}
}
}{
"outlier_detection": {
"auc_roc": {
"value": 0.9258475774641445
},
"confusion_matrix": {
"0.25": {
"tp": 5,
"fp": 9,
"tn": 204,
"fn": 5
},
"0.5": {
"tp": 1,
"fp": 5,
"tn": 208,
"fn": 9
},
"0.75": {
"tp": 0,
"fp": 4,
"tn": 209,
"fn": 10
}
},
"precision": {
"0.25": 0.35714285714285715,
"0.5": 0.16666666666666666,
"0.75": 0
},
"recall": {
"0.25": 0.5,
"0.5": 0.1,
"0.75": 0
}
}
}Specifies what to do when the request: contains wildcard expressions and there are no deployments that match;
contains the _all string or no identifiers and there are no matches; or contains wildcard expressions and
there are only partial matches. By default, it returns an empty array when there are no matches and the subset of results when there are partial matches.
If false, the request returns a 404 status code when there are no matches or only partial matches.
Forcefully stops the deployment, even if it is used by ingest pipelines. You can't use these pipelines until you restart the model deployment.
POST _ml/trained_models/my_model_for_search/deployment/_stop
resp = client.ml.stop_trained_model_deployment(
model_id="my_model_for_search",
)const response = await client.ml.stopTrainedModelDeployment({
model_id: "my_model_for_search",
});response = client.ml.stop_trained_model_deployment(
model_id: "my_model_for_search"
)$resp = $client->ml()->stopTrainedModelDeployment([
"model_id" => "my_model_for_search",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/trained_models/my_model_for_search/deployment/_stop"POST /_migration/reindex/my-data-stream/_cancel
resp = client.perform_request(
"POST",
"/_migration/reindex/my-data-stream/_cancel",
)const response = await client.transport.request({
method: "POST",
path: "/_migration/reindex/my-data-stream/_cancel",
});response = client.perform_request(
"POST",
"/_migration/reindex/my-data-stream/_cancel",
{},
)$requestFactory = Psr17FactoryDiscovery::findRequestFactory();
$request = $requestFactory->createRequest(
"POST",
"/_migration/reindex/my-data-stream/_cancel",
);
$resp = $client->sendRequest($request);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_migration/reindex/my-data-stream/_cancel"POST _rollup/job/sensor/_start
resp = client.rollup.start_job(
id="sensor",
)const response = await client.rollup.startJob({
id: "sensor",
});response = client.rollup.start_job(
id: "sensor"
)$resp = $client->rollup()->startJob([
"id" => "sensor",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_rollup/job/sensor/_start"{
"started": true
}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.
It can also be set to -1 to indicate that the request should never timeout.
Values are -1 or 0.
The period to wait for a response.
If no response is received 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.
Values are -1 or 0.
DELETE _scripts/my-search-template
resp = client.delete_script(
id="my-search-template",
)const response = await client.deleteScript({
id: "my-search-template",
});response = client.delete_script(
id: "my-search-template"
)$resp = $client->deleteScript([
"id" => "my-search-template",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_scripts/my-search-template"GET _script_context
resp = client.get_script_context()const response = await client.getScriptContext();response = client.get_script_context$resp = $client->getScriptContext();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_script_context"client.getScriptContext();
Get the status of a previously submitted async search request given its identifier, without retrieving search results. If the Elasticsearch security features are enabled, the access to the status of a specific async search is restricted to:
monitor cluster privilege or greater privileges.monitorGET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
resp = client.async_search.status(
id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)const response = await client.asyncSearch.status({
id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});response = client.async_search.status(
id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc="
)$resp = $client->asyncSearch()->status([
"id" => "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc="{
"id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_running" : true,
"is_partial" : true,
"start_time_in_millis" : 1583945890986,
"expiration_time_in_millis" : 1584377890986,
"_shards" : {
"total" : 562,
"successful" : 188,
"skipped" : 0,
"failed" : 0
}
}{
"id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_running" : false,
"is_partial" : false,
"start_time_in_millis" : 1583945890986,
"expiration_time_in_millis" : 1584377890986,
"_shards" : {
"total" : 562,
"successful" : 562,
"skipped" : 0,
"failed" : 0
},
"completion_status" : 200
}{
"id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_running" : false,
"is_partial" : true,
"start_time_in_millis" : 1583945890986,
"expiration_time_in_millis" : 1584377890986,
"_shards" : {
"total" : 562,
"successful" : 450,
"skipped" : 0,
"failed" : 112
},
"completion_status" : 503
}All methods and paths for this operation:
When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.
Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.
By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.
A comma-separated list of index names to search; use _all or empty string to perform the operation on all indices
Blocks and waits until the search is completed up to a certain timeout. When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster.
Values are -1 or 0.
Specifies how long the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period.
Values are -1 or 0.
If true, results are stored for later retrieval when the search completes within the wait_for_completion_timeout.
Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
Indicate if an error should be returned if there is a partial search failure or timeout
The analyzer to use for the query string
Specify whether wildcard and prefix queries should be analyzed (default: false)
Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).
The default value is the only supported value.
The default operator for query string query (AND or OR)
Values are and, AND, or, or OR.
The field to use as default where no field prefix is given in the query string
A comma-separated list of fields to return as the docvalue representation of a field for each hit
Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.none: Wildcard expressions are not accepted.Values are all, open, closed, hidden, or none.
Specify whether to return detailed information about score computation as part of a hit
Whether specified concrete, expanded or aliased indices should be ignored when throttled
Specify whether format-based query failures (such as providing text to a numeric field) should be ignored
The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests
Specify the node or shard the operation should be performed on (default: random)
Specify if request cache should be used for this request or not, defaults to true
A comma-separated list of specific routing values
Search operation type
Supported values include:
query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.Values are query_then_fetch or dfs_query_then_fetch.
Specific 'tag' of the request for logging and statistical purposes
A comma-separated list of stored fields to return as part of a hit
Specifies which field to use for suggestions.
Specify suggest mode
Supported values include:
missing: Only generate suggestions for terms that are not in the shard.popular: Only suggest terms that occur in more docs on the shard than the original term.always: Suggest any matching suggestions based on terms in the suggest text.Values are missing, popular, or always.
How many suggestions to return in response
The source text for which the suggestions should be returned.
The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.
Explicit operation timeout
Values are -1 or 0.
Indicate if the number of documents that match the query should be tracked. A number can also be specified, to accurately track the total hit count up to the number.
Whether to calculate and return scores even if they are not used for sorting
Specify whether aggregation and suggester names should be prefixed by their respective types in the response
Indicates whether hits.total should be rendered as an integer or an object in the rest search response
Specify whether to return document version as part of a hit
True or false to return the _source field or not, or a list of fields to return
A list of fields to exclude from the returned _source field
A list of fields to extract and return from the _source field
Specify whether to return sequence number and primary term of the last modification of each hit
Query in the Lucene query string syntax
Number of hits to return (default: 10)
Starting offset (default: 0)
A comma-separated list of : pairs
If true, returns detailed information about score computation as part of a hit.
Default value is false.
Configuration of search extensions defined by Elasticsearch plugins.
Starting document offset. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
Default value is 0.
Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
Boosts the _score of documents from specified indices.
Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
A reference to a field with formatting instructions on how to return the value
Minimum _score for matching documents. Documents with a lower _score are not included in the search results.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Retrieve a script evaluation (based on different fields) for each hit.
A field value.
A field value.
The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
Default value is 10.
Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
A reference to a field with formatting instructions on how to return the value
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. Defaults to 0, which does not terminate query execution early.
Default value is 0.
Specifies the period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
If true, calculate and return document scores, even if the scores are not used for sorting.
Default value is false.
If true, returns document version as part of a hit.
Default value is false.
If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
Stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
POST /sales*/_async_search?size=0
{
"sort": [
{ "date": { "order": "asc" } }
],
"aggs": {
"sale_date": {
"date_histogram": {
"field": "date",
"calendar_interval": "1d"
}
}
}
}resp = client.async_search.submit(
index="sales*",
size="0",
sort=[
{
"date": {
"order": "asc"
}
}
],
aggs={
"sale_date": {
"date_histogram": {
"field": "date",
"calendar_interval": "1d"
}
}
},
)const response = await client.asyncSearch.submit({
index: "sales*",
size: 0,
sort: [
{
date: {
order: "asc",
},
},
],
aggs: {
sale_date: {
date_histogram: {
field: "date",
calendar_interval: "1d",
},
},
},
});response = client.async_search.submit(
index: "sales*",
size: "0",
body: {
"sort": [
{
"date": {
"order": "asc"
}
}
],
"aggs": {
"sale_date": {
"date_histogram": {
"field": "date",
"calendar_interval": "1d"
}
}
}
}
)$resp = $client->asyncSearch()->submit([
"index" => "sales*",
"size" => "0",
"body" => [
"sort" => array(
[
"date" => [
"order" => "asc",
],
],
),
"aggs" => [
"sale_date" => [
"date_histogram" => [
"field" => "date",
"calendar_interval" => "1d",
],
],
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"sort":[{"date":{"order":"asc"}}],"aggs":{"sale_date":{"date_histogram":{"field":"date","calendar_interval":"1d"}}}}' "$ELASTICSEARCH_URL/sales*/_async_search?size=0"client.asyncSearch().submit(s -> s
.aggregations("sale_date", a -> a
.dateHistogram(d -> d
.calendarInterval(CalendarInterval.Day)
.field("date")
)
)
.index("sales*")
.size(0)
.sort(so -> so
.field(f -> f
.field("date")
.order(SortOrder.Asc)
)
)
,Void.class);
{
"sort": [
{ "date": { "order": "asc" } }
],
"aggs": {
"sale_date": {
"date_histogram": {
"field": "date",
"calendar_interval": "1d"
}
}
}
}{
"id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_partial" : true,
"is_running" : true,
"start_time_in_millis" : 1583945890986,
"expiration_time_in_millis" : 1584377890986,
"response" : {
"took" : 1122,
"timed_out" : false,
"num_reduce_phases" : 0,
"_shards" : {
"total" : 562,
"successful" : 3,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 157483,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
}
}
}All methods and paths for this operation:
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.
readThe period to retain the search context for scrolling.
Values are -1 or 0.
The scroll ID for scrolled search
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.
GET /_search/scroll
{
"scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}resp = client.scroll(
scroll_id="DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==",
)const response = await client.scroll({
scroll_id: "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==",
});response = client.scroll(
body: {
"scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}
)$resp = $client->scroll([
"body" => [
"scroll_id" => "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==",
],
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"scroll_id":"DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="}' "$ELASTICSEARCH_URL/_search/scroll"client.scroll(s -> s
.scrollId("DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==")
);
{
"scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}