curl \
--request GET http://api.example.com/_cat
Bulk index or delete documents
Perform multiple index
, create
, delete
, and update
actions in a single request.
This reduces overhead and can greatly increase indexing speed.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To use the
create
action, you must have thecreate_doc
,create
,index
, orwrite
index privilege. Data streams support only thecreate
action. - To use the
index
action, you must have thecreate
,index
, orwrite
index privilege. - To use the
delete
action, you must have thedelete
orwrite
index privilege. - To use the
update
action, you must have theindex
orwrite
index privilege. - To automatically create a data stream or index with a bulk API request, you must have the
auto_configure
,create_index
, ormanage
index privilege. - To make the result of a bulk operation visible to search using the
refresh
parameter, you must have themaintenance
ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:
action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n
The index
and create
actions expect a source on the next line and have the same semantics as the op_type
parameter in the standard index API.
A create
action fails if a document with the same ID already exists in the target
An index
action adds or replaces a document as necessary.
NOTE: Data streams support only the create
action.
To update or delete a document in a data stream, you must target the backing index containing the document.
An update
action expects that the partial doc, upsert, and script and its options are specified on the next line.
A delete
action does not expect a source on the next line and has the same semantics as the standard delete API.
NOTE: The final line of data must end with a newline character (\n
).
Each newline character may be preceded by a carriage return (\r
).
When sending NDJSON data to the _bulk
endpoint, use a Content-Type
header of application/json
or application/x-ndjson
.
Because this format uses literal newline characters (\n
) as delimiters, make sure that the JSON actions and sources are not pretty printed.
If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index
argument.
A note on the format: the idea here is to make processing as fast as possible.
As some of the actions are redirected to other shards on other nodes, only action_meta_data
is parsed on the receiving node side.
Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.
There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.
Client suppport for bulk requests
Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:
- Go: Check out
esutil.BulkIndexer
- Perl: Check out
Search::Elasticsearch::Client::5_0::Bulk
andSearch::Elasticsearch::Client::5_0::Scroll
- Python: Check out
elasticsearch.helpers.*
- JavaScript: Check out
client.helpers.*
- .NET: Check out
BulkAllObservable
- PHP: Check out bulk indexing.
Submitting bulk requests with cURL
If you're providing text file input to curl
, you must use the --data-binary
flag instead of plain -d
.
The latter doesn't preserve newlines. For example:
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
Optimistic concurrency control
Each index
and delete
action within a bulk API call may include the if_seq_no
and if_primary_term
parameters in their respective action and meta data lines.
The if_seq_no
and if_primary_term
parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.
Versioning
Each bulk item can include the version value using the version
field.
It automatically follows the behavior of the index or delete operation based on the _version
mapping.
It also support the version_type
.
Routing
Each bulk item can include the routing value using the routing
field.
It automatically follows the behavior of the index or delete operation based on the _routing
mapping.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Wait for active shards
When making bulk calls, you can set the wait_for_active_shards
parameter to require a minimum number of shard copies to be active before starting to process the bulk request.
Refresh
Control when the changes made by this request are visible to search.
NOTE: Only the shards that receive the bulk request will be affected by refresh.
Imagine a _bulk?refresh=wait_for
request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the _bulk
request at all.
Path parameters
-
The name of the data stream, index, or index alias to perform bulk actions on.
Query parameters
-
include_source_on_error boolean
True or false if to include the document source in the error message in case of parsing errors.
-
list_executed_pipelines boolean
If
true
, the response will include the ingest pipelines that were run for each index or create. -
pipeline string
The pipeline identifier to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to
_none
turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter. -
refresh string
If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, wait for a refresh to make this operation visible to search. Iffalse
, do nothing with refreshes. Valid values:true
,false
,wait_for
.Values are
true
,false
, orwait_for
. -
routing string
A custom value that is used to route operations to a specific shard.
-
_source boolean | string | array[string]
Indicates whether to return the
_source
field (true
orfalse
) or contains a list of fields to return. -
_source_excludes string | array[string]
A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in
_source_includes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
_source_includes string | array[string]
A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the
_source_excludes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
timeout string
The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards. The default is
1m
(one minute), which guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur. -
wait_for_active_shards number | string
The number of shard copies that must be active before proceeding with the operation. Set to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default is1
, which waits for each primary shard to be active. -
require_alias boolean
If
true
, the request's actions must target an index alias. -
require_data_stream boolean
If
true
, the request's actions must target a data stream (existing or to be created).
curl \
--request POST http://api.example.com/{index}/_bulk \
--header "Content-Type: application/json" \
--data '"{ \"index\" : { \"_index\" : \"test\", \"_id\" : \"1\" } }\n{ \"field1\" : \"value1\" }\n{ \"delete\" : { \"_index\" : \"test\", \"_id\" : \"2\" } }\n{ \"create\" : { \"_index\" : \"test\", \"_id\" : \"3\" } }\n{ \"field1\" : \"value3\" }\n{ \"update\" : {\"_id\" : \"1\", \"_index\" : \"test\"} }\n{ \"doc\" : {\"field2\" : \"value2\"} }"'
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}
{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }
{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}
{
"took": 30,
"errors": false,
"items": [
{
"index": {
"_index": "test",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 201,
"_seq_no" : 0,
"_primary_term": 1
}
},
{
"delete": {
"_index": "test",
"_id": "2",
"_version": 1,
"result": "not_found",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 404,
"_seq_no" : 1,
"_primary_term" : 2
}
},
{
"create": {
"_index": "test",
"_id": "3",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 201,
"_seq_no" : 2,
"_primary_term" : 3
}
},
{
"update": {
"_index": "test",
"_id": "1",
"_version": 2,
"result": "updated",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 200,
"_seq_no" : 3,
"_primary_term" : 4
}
}
]
}
{
"took": 486,
"errors": true,
"items": [
{
"update": {
"_index": "index1",
"_id": "5",
"status": 404,
"error": {
"type": "document_missing_exception",
"reason": "[5]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"update": {
"_index": "index1",
"_id": "6",
"status": 404,
"error": {
"type": "document_missing_exception",
"reason": "[6]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"create": {
"_index": "index1",
"_id": "7",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 201
}
}
]
}
{
"items": [
{
"update": {
"error": {
"type": "document_missing_exception",
"reason": "[5]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"update": {
"error": {
"type": "document_missing_exception",
"reason": "[6]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
}
]
}
Get term vector information
Get information and statistics about terms in the fields of a particular document.
You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request.
You can specify the fields you are interested in through the fields
parameter or by adding the fields to the request body.
For example:
GET /my-index-000001/_termvectors/1?fields=message
Fields can be specified using wildcards, similar to the multi match query.
Term vectors are real-time by default, not near real-time.
This can be changed by setting realtime
parameter to false
.
You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.
Term information
- term frequency in the field (always returned)
- term positions (
positions: true
) - start and end offsets (
offsets: true
) - term payloads (
payloads: true
), as base64 encoded bytes
If the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.
Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.
Behaviour
The term and field statistics are not accurate.
Deleted documents are not taken into account.
The information is only retrieved for the shard the requested document resides in.
The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
Use routing
only to hit a particular shard.
Path parameters
-
The name of the index that contains the document.
Query parameters
-
fields string | array[string]
A comma-separated list or wildcard expressions of fields to include in the statistics. It is used as the default list unless a specific field list is provided in the
completion_fields
orfielddata_fields
parameters. -
field_statistics boolean
If
true
, the response includes:- The document count (how many documents contain this field).
- The sum of document frequencies (the sum of document frequencies for all terms in this field).
- The sum of total term frequencies (the sum of total term frequencies of each term in this field).
-
offsets boolean
If
true
, the response includes term offsets. -
payloads boolean
If
true
, the response includes term payloads. -
positions boolean
If
true
, the response includes term positions. -
preference string
The node or shard the operation should be performed on. It is random by default.
-
realtime boolean
If true, the request is real-time as opposed to near-real-time.
-
routing string
A custom value that is used to route operations to a specific shard.
-
term_statistics boolean
If
true
, the response includes:- The total term frequency (how often a term occurs in all documents).
- The document frequency (the number of documents containing the current term).
By default these values are not returned since term statistics can have a serious performance impact.
-
version number
If
true
, returns the document version as part of a hit. -
version_type string
The version type.
Values are
internal
,external
,external_gte
, orforce
.
Body
-
doc object
An artificial document (a document not present in the index) for which you want to retrieve term vectors.
Additional properties are allowed.
-
filter object
Additional properties are allowed.
-
per_field_analyzer object
Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.
curl \
--request POST http://api.example.com/{index}/_termvectors \
--header "Content-Type: application/json" \
--data '"{\n \"fields\" : [\"text\"],\n \"offsets\" : true,\n \"payloads\" : true,\n \"positions\" : true,\n \"term_statistics\" : true,\n \"field_statistics\" : true\n}"'
{
"fields" : ["text"],
"offsets" : true,
"payloads" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}
{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
},
"fields": ["fullname"],
"per_field_analyzer" : {
"fullname": "keyword"
}
}
{
"doc": {
"plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
},
"term_statistics": true,
"field_statistics": true,
"positions": false,
"offsets": false,
"filter": {
"max_num_terms": 3,
"min_term_freq": 1,
"min_doc_freq": 1
}
}
{
"fields" : ["text", "some_field_without_term_vectors"],
"offsets" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}
{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
}
}
{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"found": true,
"took": 6,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 4,
"doc_count": 2,
"sum_ttf": 6
},
"terms": {
"test": {
"doc_freq": 2,
"ttf": 4,
"term_freq": 3,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 4,
"payload": "d29yZA=="
},
{
"position": 1,
"start_offset": 5,
"end_offset": 9,
"payload": "d29yZA=="
},
{
"position": 2,
"start_offset": 10,
"end_offset": 14,
"payload": "d29yZA=="
}
]
}
}
}
}
}
{
"_index": "my-index-000001",
"_version": 0,
"found": true,
"took": 6,
"term_vectors": {
"fullname": {
"field_statistics": {
"sum_doc_freq": 2,
"doc_count": 4,
"sum_ttf": 4
},
"terms": {
"John Doe": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 8
}
]
}
}
}
}
}
{
"_index": "imdb",
"_version": 0,
"found": true,
"term_vectors": {
"plot": {
"field_statistics": {
"sum_doc_freq": 3384269,
"doc_count": 176214,
"sum_ttf": 3753460
},
"terms": {
"armored": {
"doc_freq": 27,
"ttf": 27,
"term_freq": 1,
"score": 9.74725
},
"industrialist": {
"doc_freq": 88,
"ttf": 88,
"term_freq": 1,
"score": 8.590818
},
"stark": {
"doc_freq": 44,
"ttf": 47,
"term_freq": 1,
"score": 9.272792
}
}
}
}
}
Delete an async EQL search Added in 7.9.0
Delete an async EQL search or a stored synchronous EQL search. The API also deletes results for the search.
Path parameters
-
Identifier for the search to delete. A search ID is provided in the EQL search API's response for an async search. A search ID is also provided if the request’s
keep_on_completion
parameter istrue
.
curl \
--request DELETE http://api.example.com/_eql/search/{id}
Check component templates Added in 7.8.0
Returns information about whether a particular component template exists.
Path parameters
-
Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported.
Query parameters
-
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
local boolean
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}
Add an index block Added in 7.9.0
Add an index block to an index. Index blocks limit the operations allowed on an index by blocking specific operation types.
Path parameters
-
A comma-separated list or wildcard expression of index names used to limit the request. By default, you must explicitly name the indices you are adding blocks to. To allow the adding of blocks to indices with
_all
,*
, or other wildcard expressions, change theaction.destructive_requires_name
setting tofalse
. You can update this setting in theelasticsearch.yml
file or by using the cluster update settings API. -
The block type to add to the index.
Values are
metadata
,read
,read_only
, orwrite
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. -
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as
open,hidden
. -
master_timeout string
The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. It can also be set to
-1
to indicate that the request should never timeout. -
timeout string
The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. It can also be set to
-1
to indicate that the request should never timeout.
curl \
--request PUT http://api.example.com/{index}/_block/{block}
{
"acknowledged" : true,
"shards_acknowledged" : true,
"indices" : [ {
"name" : "my-index-000001",
"blocked" : true
} ]
}
Update field mappings
Add new fields to an existing data stream or index. You can also use this API to change the search settings of existing fields and add new properties to existing object fields. For data streams, these changes are applied to all backing indices by default.
Add multi-fields to an existing field
Multi-fields let you index the same field in different ways. You can use this API to update the fields mapping parameter and enable multi-fields for an existing field. WARNING: If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. You can populate the new multi-field with the update by query API.
Change supported mapping parameters for an existing field
The documentation for each mapping parameter indicates whether you can update it for an existing field using this API.
For example, you can use the update mapping API to update the ignore_above
parameter.
Change the mapping of an existing field
Except for supported mapping parameters, you can't change the mapping or field type of an existing field. Changing an existing field could invalidate data that's already indexed.
If you need to change the mapping of a field in a data stream's backing indices, refer to documentation about modifying data streams. If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.
Rename a field
Renaming a field would invalidate data already indexed under the old field name. Instead, add an alias field to create an alternate field name.
Path parameters
-
A comma-separated list of index names the mapping should be added to (supports wildcards); use
_all
or omit to add the mapping on all indices.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
master_timeout string
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout string
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
write_index_only boolean
If
true
, the mappings are applied only to the current write index for the target.
Body Required
-
date_detection boolean
Controls whether dynamic date detection is enabled.
-
dynamic string
Values are
strict
,runtime
,true
, orfalse
. -
dynamic_date_formats array[string]
If date detection is enabled then new string fields are checked against 'dynamic_date_formats' and if the value matches then a new date field is added instead of string.
dynamic_templates object | array[object]
Specify dynamic templates for the mapping.
-
_field_names object
Additional properties are allowed.
-
_meta object
-
numeric_detection boolean
Automatically map strings into numeric data types for all fields.
-
properties object
Mapping for a field. For new fields, this mapping can include:
- Field name
- Field data type
- Mapping parameters
-
_routing object
Additional properties are allowed.
-
_source object
Additional properties are allowed.
-
runtime object
curl \
--request POST http://api.example.com/{index}/_mapping \
--header "Content-Type: application/json" \
--data '{"properties":{"user":{"properties":{"name":{"type":"keyword"}}}}}'
{
"properties": {
"user": {
"properties": {
"name": {
"type": "keyword"
}
}
}
}
}
Create an inference endpoint Added in 8.11.0
When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running.
After creating the endpoint, wait for the model deployment to complete before using it.
To verify the deployment status, use the get trained model statistics API.
Look for "state": "fully_allocated"
in the response and ensure that the "allocation_count"
matches the "target_allocation_count"
.
Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.
IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
Path parameters
-
The inference Id
Body Required
-
The service type
-
Additional properties are allowed.
-
task_settings object
Additional properties are allowed.
curl \
--request PUT http://api.example.com/_inference/{inference_id} \
--header "Content-Type: application/json" \
--data '{"service":"string","service_settings":{},"task_settings":{}}'
Delete an inference endpoint Added in 8.11.0
Path parameters
-
The task type
Values are
sparse_embedding
,text_embedding
,rerank
, orcompletion
. -
The inference identifier.
curl \
--request DELETE http://api.example.com/_inference/{task_type}/{inference_id}
Licensing
Licensing APIs enable you to manage your licenses.
Delete a datafeed Added in 5.4.0
Path parameters
-
A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.
Query parameters
-
force boolean
Use to forcefully delete a started datafeed; this method is quicker than stopping and deleting the datafeed.
curl \
--request DELETE http://api.example.com/_ml/datafeeds/{datafeed_id}
{
"acknowledged": true
}
Get anomaly detection jobs configuration info Added in 5.5.0
You can get information for 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 get information for all anomaly detection jobs by using
_all
, by specifying *
as the <job_id>
, or by omitting the <job_id>
.
Path parameters
-
Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. If you do not specify one of these options, the API returns information for all anomaly detection jobs.
Query parameters
-
allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs that match.
- Contains the _all string or no identifiers and there are no matches.
- Contains wildcard expressions and there are only partial matches.
The default value is
true
, which returns an emptyjobs
array when there are no matches and the subset of results when there are partial matches. If this parameter isfalse
, the request returns a404
status code when there are no matches or only partial matches. -
exclude_generated boolean
Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.
curl \
--request GET http://api.example.com/_ml/anomaly_detectors/{job_id}
Force buffered data to be processed Deprecated Added in 5.4.0
The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send more data for analysis. When flushing, the job remains open and is available to continue analyzing data. A close operation additionally prunes and persists the model state to disk and the job must be opened again before analyzing further data.
Path parameters
-
Identifier for the anomaly detection job.
Query parameters
-
advance_time string | number
Specifies to advance to a particular time value. Results are generated and the model is updated for data from the specified time interval.
-
calc_interim boolean
If true, calculates the interim results for the most recent bucket or all buckets within the latency period.
-
end string | number
When used in conjunction with
calc_interim
andstart
, specifies the range of buckets on which to calculate interim results. -
skip_time string | number
Specifies to skip to a particular time value. Results are not generated and the model is not updated for data from the specified time interval.
-
start string | number
When used in conjunction with
calc_interim
, specifies the range of buckets on which to calculate interim results.
Body
advance_time string | number
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
-
calc_interim boolean
Refer to the description for the
calc_interim
query parameter. end string | number
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
skip_time string | number
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
start string | number
A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
curl \
--request POST http://api.example.com/_ml/anomaly_detectors/{job_id}/_flush \
--header "Content-Type: application/json" \
--data '{"":"string","calc_interim":true}'
Delete a data frame analytics job Added in 7.3.0
Path parameters
-
Identifier for the data frame analytics job.
curl \
--request DELETE http://api.example.com/_ml/data_frame/analytics/{id}
{
"acknowledged": true
}
Preview features used by data frame analytics Added in 7.13.0
Preview the extracted features used by a data frame analytics config.
curl \
--request GET http://api.example.com/_ml/data_frame/analytics/_preview \
--header "Content-Type: application/json" \
--data '{"config":{"source":{"index":"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"}},"_source":{"includes":["string"],"excludes":["string"]},"query":{}},"analysis":{"":{"alpha":42.0,"dependent_variable":"string","downsample_factor":42.0,"early_stopping_enabled":true,"eta":42.0,"eta_growth_rate_per_tree":42.0,"feature_bag_fraction":42.0,"feature_processors":[{"frequency_encoding":{},"multi_encoding":{},"n_gram_encoding":{},"one_hot_encoding":{},"target_mean_encoding":{}}],"gamma":42.0,"lambda":42.0,"max_optimization_rounds_per_hyperparameter":42.0,"max_trees":42.0,"num_top_feature_importance_values":42.0,"prediction_field_name":"string","randomize_seed":42.0,"soft_tree_depth_limit":42.0,"soft_tree_depth_tolerance":42.0,"":"string","loss_function":"string","loss_function_parameter":42.0},"outlier_detection":{"compute_feature_influence":true,"feature_influence_threshold":42.0,"method":"string","n_neighbors":42.0,"outlier_fraction":42.0,"standardization_enabled":true}},"model_memory_limit":"string","max_num_threads":42.0,"analyzed_fields":{"includes":["string"],"excludes":["string"]}}}'
Get a query rule Added in 8.15.0
Get details about a query rule within a query ruleset.
Path parameters
-
The unique identifier of the query ruleset containing the rule to retrieve
-
The unique identifier of the query rule within the specified ruleset to retrieve
curl \
--request GET http://api.example.com/_query_rules/{ruleset_id}/_rule/{rule_id}
Run a script Technical preview
Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.
Each context requires a script, but additional parameters depend on the context you're using for that script.
Body
-
context string
Values are
painless_test
,filter
,score
,boolean_field
,date_field
,double_field
,geo_point_field
,ip_field
,keyword_field
,long_field
, orcomposite_field
. -
context_setup object
Additional properties are allowed.
-
script object
Additional properties are allowed.
curl \
--request GET http://api.example.com/_scripts/painless/_execute \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"source\": \"params.count / params.total\",\n \"params\": {\n \"count\": 100.0,\n \"total\": 1000.0\n }\n }\n}"'
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
{
"script": {
"source": "doc['field'].value.length() <= params.max_length",
"params": {
"max_length": 4
}
},
"context": "filter",
"context_setup": {
"index": "my-index-000001",
"document": {
"field": "four"
}
}
}
{
"script": {
"source": "doc['rank'].value / params.max_rank",
"params": {
"max_rank": 5.0
}
},
"context": "score",
"context_setup": {
"index": "my-index-000001",
"document": {
"rank": 4
}
}
}
{
"result": "0.1"
}
{
"result": true
}
{
"result": 0.8
}
Close a point in time Added in 7.10.0
A point in time must be opened explicitly before being used in search requests.
The keep_alive
parameter tells Elasticsearch how long it should persist.
A point in time is automatically closed when the keep_alive
period has elapsed.
However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.
curl \
--request DELETE http://api.example.com/_pit \
--header "Content-Type: application/json" \
--data '"{\n \"id\": \"46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==\"\n}"'
{
"id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=="
}
{
"succeeded": true,
"num_freed": 3
}
Count search results
Get the number of documents matching a query.
The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.
The query is optional. When no query is provided, the API uses match_all
to count all the documents.
The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.
The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count.
Path parameters
-
A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (
*
). To search all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices boolean
If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
. -
analyzer string
The analyzer to use for the query string. This parameter can be used only when the
q
query string parameter is specified. -
analyze_wildcard boolean
If
true
, wildcard and prefix queries are analyzed. This parameter can be used only when theq
query string parameter is specified. -
default_operator string
The default operator for query string query:
AND
orOR
. This parameter can be used only when theq
query string parameter is specified.Values are
and
,AND
,or
, orOR
. -
df string
The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the
q
query string parameter is specified. -
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as
open,hidden
. -
If
true
, concrete, expanded, or aliased indices are ignored when frozen. -
lenient boolean
If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theq
query string parameter is specified. -
min_score number
The minimum
_score
value that documents must have to be included in the result. -
preference string
The node or shard the operation should be performed on. By default, it is random.
-
routing string
A custom value used to route operations to a specific shard.
-
terminate_after number
The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
-
q string
The query in Lucene query string syntax. This parameter cannot be used with a request body.
curl \
--request POST http://api.example.com/{index}/_count \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"term\" : { \"user.id\" : \"kimchy\" }\n }\n}"'
{
"query" : {
"term" : { "user.id" : "kimchy" }
}
}
{
"count": 1,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
}
}
Explain a document match result
Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.
Path parameters
-
Index names that are used to limit the request. Only a single index name can be provided to this parameter.
-
The document identifier.
Query parameters
-
analyzer string
The analyzer to use for the query string. This parameter can be used only when the
q
query string parameter is specified. -
analyze_wildcard boolean
If
true
, wildcard and prefix queries are analyzed. This parameter can be used only when theq
query string parameter is specified. -
default_operator string
The default operator for query string query:
AND
orOR
. This parameter can be used only when theq
query string parameter is specified.Values are
and
,AND
,or
, orOR
. -
df string
The field to use as default where no field prefix is given in the query string. This parameter can be used only when the
q
query string parameter is specified. -
lenient boolean
If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theq
query string parameter is specified. -
preference string
The node or shard the operation should be performed on. It is random by default.
-
routing string
A custom value used to route operations to a specific shard.
-
_source boolean | string | array[string]
True
orfalse
to return the_source
field or not or a list of fields to return. -
_source_excludes string | array[string]
A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in
_source_includes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
_source_includes string | array[string]
A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the
_source_excludes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
stored_fields string | array[string]
A comma-separated list of stored fields to return in the response.
-
q string
The query in the Lucene query string syntax.
curl \
--request GET http://api.example.com/{index}/_explain/{id} \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"match\" : { \"message\" : \"elasticsearch\" }\n }\n}"'
{
"query" : {
"match" : { "message" : "elasticsearch" }
}
}
{
"_index":"my-index-000001",
"_id":"0",
"matched":true,
"explanation":{
"value":1.6943598,
"description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
"details":[
{
"value":1.6943598,
"description":"score(freq=1.0), computed as boost * idf * tf from:",
"details":[
{
"value":2.2,
"description":"boost",
"details":[]
},
{
"value":1.3862944,
"description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
"details":[
{
"value":1,
"description":"n, number of documents containing term",
"details":[]
},
{
"value":5,
"description":"N, total number of documents with field",
"details":[]
}
]
},
{
"value":0.5555556,
"description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
"details":[
{
"value":1.0,
"description":"freq, occurrences of term within document",
"details":[]
},
{
"value":1.2,
"description":"k1, term saturation parameter",
"details":[]
},
{
"value":0.75,
"description":"b, length normalization parameter",
"details":[]
},
{
"value":3.0,
"description":"dl, length of field",
"details":[]
},
{
"value":5.4,
"description":"avgdl, average length of field",
"details":[]
}
]
}
]
}
]
}
}
Get the field capabilities Added in 5.4.0
Get information about the capabilities of fields among multiple indices.
For data streams, the API returns field capabilities among the stream’s backing indices.
It returns runtime fields like any other field.
For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the keyword
family.
Query parameters
-
allow_no_indices boolean
If false, the request returns an error if any wildcard expression, index alias, or
_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts with foo but no index starts with bar. -
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. -
fields string | array[string]
A comma-separated list of fields to retrieve capabilities for. Wildcard (
*
) expressions are supported. -
include_unmapped boolean
If true, unmapped fields are included in the response.
-
filters string
A comma-separated list of filters to apply to the response.
-
types array[string]
A comma-separated list of field types to include. Any fields that do not match one of these types will be excluded from the results. It defaults to empty, meaning that all field types are returned.
-
include_empty_fields boolean
If false, empty fields are not included in the response.
Body
-
fields string | array[string]
-
index_filter object
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Additional properties are allowed.
-
runtime_mappings object
curl \
--request GET http://api.example.com/_field_caps \
--header "Content-Type: application/json" \
--data '"{\n \"index_filter\": {\n \"range\": {\n \"@timestamp\": {\n \"gte\": \"2018\"\n }\n }\n }\n}"'
{
"index_filter": {
"range": {
"@timestamp": {
"gte": "2018"
}
}
}
}
{
"indices": [ "index1", "index2", "index3", "index4", "index5" ],
"fields": {
"rating": {
"long": {
"metadata_field": false,
"searchable": true,
"aggregatable": false,
"indices": [ "index1", "index2" ],
"non_aggregatable_indices": [ "index1" ]
},
"keyword": {
"metadata_field": false,
"searchable": false,
"aggregatable": true,
"indices": [ "index3", "index4" ],
"non_searchable_indices": [ "index4" ]
}
},
"title": {
"text": {
"metadata_field": false,
"searchable": true,
"aggregatable": false
}
}
}
}
{
"indices": [ "index1", "index2", "index3", "index4", "index5" ],
"fields": {
"rating": {
"long": {
"metadata_field": false,
"searchable": true,
"aggregatable": false,
"indices": [ "index1", "index2" ],
"non_aggregatable_indices": [ "index1" ]
},
"keyword": {
"metadata_field": false,
"searchable": false,
"aggregatable": true,
"indices": [ "index3", "index4" ],
"non_searchable_indices": [ "index4" ]
}
},
"title": {
"text": {
"metadata_field": false,
"searchable": true,
"aggregatable": false
}
}
}
}
Run multiple searches Added in 1.3.0
The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. The structure is as follows:
header\n
body\n
header\n
body\n
This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.
IMPORTANT: The final line of data must end with a newline character \n
.
Each newline character may be preceded by a carriage return \r
.
When sending requests to this endpoint the Content-Type
header should be set to application/x-ndjson
.
Path parameters
-
Comma-separated list of data streams, indices, and index aliases to search.
Query parameters
-
allow_no_indices boolean
If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
-
ccs_minimize_roundtrips boolean
If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
-
expand_wildcards string | array[string]
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
-
ignore_throttled boolean
If true, concrete, expanded or aliased indices are ignored when frozen.
-
include_named_queries_score boolean
Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
-
max_concurrent_searches number
Maximum number of concurrent searches the multi search API can execute.
-
Maximum number of concurrent shard requests that each sub-search request executes per node.
-
pre_filter_shard_size number
Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
-
rest_total_hits_as_int boolean
If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
-
routing string
Custom routing value used to route search operations to a specific shard.
-
search_type string
Indicates whether global term and document frequencies should be used when scoring returned documents.
Values are
query_then_fetch
ordfs_query_then_fetch
. -
typed_keys boolean
Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
Body object Required
-
allow_no_indices boolean
-
expand_wildcards string | array[string]
-
index string | array[string]
-
preference string
-
request_cache boolean
-
routing string
-
search_type string
Values are
query_then_fetch
ordfs_query_then_fetch
. -
ccs_minimize_roundtrips boolean
-
allow_partial_search_results boolean
-
ignore_throttled boolean
curl \
--request POST http://api.example.com/{index}/_msearch \
--header "Content-Type: application/json" \
--data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'
Render a search template
Render a search template as a search request body.
Path parameters
-
The ID of the search template to render. If no
source
is specified, this or theid
request body parameter is required.
Body
-
id string
-
file string
-
params object
Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.
-
source string
An inline search template. It supports the same parameters as the search API's request body. These parameters also support Mustache variables. If no
id
or<templated-id>
is specified, this parameter is required.
curl \
--request POST http://api.example.com/_render/template/{id} \
--header "Content-Type: application/json" \
--data '{"id":"string","file":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"source":"string"}'
Get a synonym set Added in 8.10.0
Path parameters
-
The synonyms set identifier to retrieve.
curl \
--request GET http://api.example.com/_synonyms/{id}
Create or update a synonym set Added in 8.10.0
Synonyms sets are limited to a maximum of 10,000 synonym rules per set. If you need to manage more synonym rules, you can create multiple synonym sets.
When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices. This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.
Path parameters
-
The ID of the synonyms set to be created or updated.
Body Required
synonyms_set object | array[object] Required
The synonym rules definitions for the synonyms set.
curl \
--request PUT http://api.example.com/_synonyms/{id} \
--header "Content-Type: application/json" \
--data '{"synonyms_set":{"id":"string","synonyms":"string"}}'