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.19 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 Sep 16, 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
DELETE _application/analytics/my_analytics_collection/
resp = client.search_application.delete_behavioral_analytics(
name="my_analytics_collection",
)const response = await client.searchApplication.deleteBehavioralAnalytics({
name: "my_analytics_collection",
});response = client.search_application.delete_behavioral_analytics(
name: "my_analytics_collection"
)$resp = $client->searchApplication()->deleteBehavioralAnalytics([
"name" => "my_analytics_collection",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection/"client.searchApplication().deleteBehavioralAnalytics(d -> d
.name("my_analytics_collection")
);
All methods and paths for this operation:
Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
view_index_metadataA comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
alias (or a): The name of the alias.index (or i, idx): The name of the index the alias points to.filter (or f, fi): The filter applied to the alias.routing.index (or ri, routingIndex): Index routing value for the alias.routing.search (or rs, routingSearch): Search routing value for the alias.is_write_index (or w, isWriteIndex): Indicates if the index is the write index for the alias.Values are alias, a, index, i, idx, filter, f, fi, routing.index, ri, routingIndex, routing.search, rs, routingSearch, is_write_index, w, or isWriteIndex.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
It supports comma-separated values, such as open,hidden.
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, 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.
GET _cat/aliases?format=json&v=true
resp = client.cat.aliases(
format="json",
v=True,
)const response = await client.cat.aliases({
format: "json",
v: "true",
});response = client.cat.aliases(
format: "json",
v: "true"
)$resp = $client->cat()->aliases([
"format" => "json",
"v" => "true",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/aliases?format=json&v=true"client.cat().aliases();
[
{
"alias": "alias1",
"index": "test1",
"filter": "-",
"routing.index": "-",
"routing.search": "-",
"is_write_index": "true"
},
{
"alias": "alias1",
"index": "test1",
"filter": "*",
"routing.index": "-",
"routing.search": "-",
"is_write_index": "true"
},
{
"alias": "alias3",
"index": "test1",
"filter": "-",
"routing.index": "1",
"routing.search": "1",
"is_write_index": "true"
},
{
"alias": "alias4",
"index": "test1",
"filter": "-",
"routing.index": "2",
"routing.search": "1,2",
"is_write_index": "true"
}
]All methods and paths for this operation:
Get a snapshot of the number of shards allocated to each data node and their disk space.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
monitorA comma-separated list of node identifiers or names used to limit the returned information.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
shards (or s): The number of shards on the node.shards.undesired: The number of shards scheduled to be moved elsewhere in the cluster.write_load.forecast (or wlf, writeLoadForecast): The sum of index write load forecasts.disk.indices.forecast (or dif, diskIndicesForecast): The sum of shard size forecasts.disk.indices (or di, diskIndices): The disk space used by Elasticsearch indices.disk.used (or du, diskUsed): The total disk space used on the node.disk.avail (or da, diskAvail): The available disk space on the node.disk.total (or dt, diskTotal): The total disk capacity of all volumes on the node.disk.percent (or dp, diskPercent): The percentage of disk space used on the node.host (or h): IThe host of the node.ip: The IP address of the node.node (or n): The name of the node.node.role (or r, role, nodeRole): The roles assigned to the node.Values are shards, s, shards.undesired, write_load.forecast, wlf, writeLoadForecast, disk.indices.forecast, dif, diskIndicesForecast, disk.indices, di, diskIndices, disk.used, du, diskUsed, disk.avail, da, diskAvail, disk.total, dt, diskTotal, disk.percent, dp, diskPercent, host, h, ip, node, n, node.role, r, role, or nodeRole.
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/allocation?v=true&format=json
resp = client.cat.allocation(
v=True,
format="json",
)const response = await client.cat.allocation({
v: "true",
format: "json",
});response = client.cat.allocation(
v: "true",
format: "json"
)$resp = $client->cat()->allocation([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/allocation?v=true&format=json"client.cat().allocation();
[
{
"shards": "1",
"shards.undesired": "0",
"write_load.forecast": "0.0",
"disk.indices.forecast": "260b",
"disk.indices": "260b",
"disk.used": "47.3gb",
"disk.avail": "43.4gb",
"disk.total": "100.7gb",
"disk.percent": "46",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "CSUXak2",
"node.role": "himrst"
}
]All methods and paths for this operation:
Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API.
monitorThe name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
name (or n): The name of the component template.version (or v): The version number of the component template.alias_count (or a): The number of aliases in the component template.mapping_count (or m): The number of mappings in the component template.settings_count (or s): The number of settings in the component template.metadata_count (or me): The number of metadata entries in the component template.included_in (or i): The index templates that include this component template.Values are name, n, version, v, alias_count, a, mapping_count, m, settings_count, s, metadata_count, me, included_in, or i.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
The period to wait for a connection to the master node.
Values are -1 or 0.
GET _cat/component_templates/my-template-*?v=true&s=name&format=json
resp = client.cat.component_templates(
name="my-template-*",
v=True,
s="name",
format="json",
)const response = await client.cat.componentTemplates({
name: "my-template-*",
v: "true",
s: "name",
format: "json",
});response = client.cat.component_templates(
name: "my-template-*",
v: "true",
s: "name",
format: "json"
)$resp = $client->cat()->componentTemplates([
"name" => "my-template-*",
"v" => "true",
"s" => "name",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/component_templates/my-template-*?v=true&s=name&format=json"client.cat().componentTemplates();
[
{
"name": "my-template-1",
"version": "null",
"alias_count": "0",
"mapping_count": "0",
"settings_count": "1",
"metadata_count": "0",
"included_in": "[my-index-template]"
},
{
"name": "my-template-2",
"version": null,
"alias_count": "0",
"mapping_count": "3",
"settings_count": "0",
"metadata_count": "0",
"included_in": "[my-index-template]"
}
]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.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
id: The node ID.host (or h): The host name of the node.ip: The IP address of the node.node (or n): The node name.field (or f): The field name.size (or s): The field data usage.Values are id, host, h, ip, node, n, field, f, size, or s.
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"
}
]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 cluster health API.
This API is often used to check malfunctioning clusters.
To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats:
HH:MM:SS, which is human-readable but includes no date information;
Unix epoch time, which is machine-sortable and includes date information.
The latter format is useful for cluster recoveries that take multiple days.
You can use the cat health API to verify cluster health across multiple nodes.
You also can use the API to track the recovery of a large cluster over a longer period of time.
monitorThe unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
If true, returns HH:MM:SS and Unix epoch timestamps.
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/health?v=true&format=json
resp = client.cat.health(
v=True,
format="json",
)const response = await client.cat.health({
v: "true",
format: "json",
});response = client.cat.health(
v: "true",
format: "json"
)$resp = $client->cat()->health([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/health?v=true&format=json"client.cat().health();
[
{
"epoch": "1475871424",
"timestamp": "16:17:04",
"cluster": "elasticsearch",
"status": "green",
"node.total": "1",
"node.data": "1",
"shards": "1",
"pri": "1",
"relo": "0",
"init": "0",
"unassign": "0",
"unassign.pri": "0",
"pending_tasks": "0",
"max_task_wait_time": "-",
"active_shards_percent": "100.0%"
}
]All methods and paths for this operation:
Get high-level information about indices in a cluster, including backing indices for data streams.
Use this request to get the following information for each index in a cluster:
These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
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 an index endpoint.
monitormonitorComma-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.
The type of index that wildcard patterns can match.
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 health status used to limit returned indices. By default, the response includes indices of any health 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.unknownunavailableValues are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
If true, the response includes information from segments that are not loaded into memory.
If true, the response only includes information from primary shards.
The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
Period to wait for a connection to the master node.
Values are -1 or 0.
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/indices/my-index-*?v=true&s=index&format=json
resp = client.cat.indices(
index="my-index-*",
v=True,
s="index",
format="json",
)const response = await client.cat.indices({
index: "my-index-*",
v: "true",
s: "index",
format: "json",
});response = client.cat.indices(
index: "my-index-*",
v: "true",
s: "index",
format: "json"
)$resp = $client->cat()->indices([
"index" => "my-index-*",
"v" => "true",
"s" => "index",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/indices/my-index-*?v=true&s=index&format=json"client.cat().indices();
[
{
"health": "yellow",
"status": "open",
"index": "my-index-000001",
"uuid": "u8FNjxh8Rfy_awN11oDKYQ",
"pri": "1",
"rep": "1",
"docs.count": "1200",
"docs.deleted": "0",
"store.size": "88.1kb",
"pri.store.size": "88.1kb",
"dataset.size": "88.1kb"
},
{
"health": "green",
"status": "open",
"index": "my-index-000002",
"uuid": "nYFWZEO7TUiOjLQXBaYJpA ",
"pri": "1",
"rep": "0",
"docs.count": "0",
"docs.deleted": "0",
"store.size": "260b",
"pri.store.size": "260b",
"dataset.size": "260b"
}
]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"
}
]All methods and paths for this operation:
Get configuration and usage information for anomaly detection jobs.
This API returns a maximum of 10,000 jobs.
If the Elasticsearch security features are enabled, you must have monitor_ml,
monitor, manage_ml, or manage cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get anomaly detection job statistics API.
monitor_mlSpecifies what to do when the request:
_all string or no identifiers and there are no matches.If true, the API returns an empty jobs array when there are no matches and the subset of results when there
are partial matches. If false, the API returns a 404 status code when there are no matches or only partial
matches.
The unit used 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): For open anomaly detection jobs only, contains messages relating to the
selection of a node to run the job.buckets.count (or bc, bucketsCount): The number of bucket results produced by the job.buckets.time.exp_avg (or btea, bucketsTimeExpAvg): Exponential moving average of all bucket processing times, in milliseconds.buckets.time.exp_avg_hour (or bteah, bucketsTimeExpAvgHour): Exponentially-weighted moving average of bucket processing times calculated
in a 1 hour time window, in milliseconds.buckets.time.max (or btmax, bucketsTimeMax): Maximum among all bucket processing times, in milliseconds.buckets.time.min (or btmin, bucketsTimeMin): Minimum among all bucket processing times, in milliseconds.buckets.time.total (or btt, bucketsTimeTotal): Sum of all bucket processing times, in milliseconds.data.buckets (or db, dataBuckets): The number of buckets processed.data.earliest_record (or der, dataEarliestRecord): The timestamp of the earliest chronologically input document.data.empty_buckets (or deb, dataEmptyBuckets): The number of buckets which did not contain any data.data.input_bytes (or dib, dataInputBytes): The number of bytes of input data posted to the anomaly detection job.data.input_fields (or dif, dataInputFields): The total number of fields in input documents posted to the anomaly
detection job. This count includes fields that are not used in the analysis.
However, be aware that if you are using a datafeed, it extracts only the
required fields from the documents it retrieves before posting them to the job.data.input_records (or dir, dataInputRecords): The number of input documents posted to the anomaly detection job.data.invalid_dates (or did, dataInvalidDates): The number of input documents with either a missing date field or a date
that could not be parsed.data.last (or dl, dataLast): The timestamp at which data was last analyzed, according to server time.data.last_empty_bucket (or dleb, dataLastEmptyBucket): The timestamp of the last bucket that did not contain any data.data.last_sparse_bucket (or dlsb, dataLastSparseBucket): The timestamp of the last bucket that was considered sparse.data.latest_record (or dlr, dataLatestRecord): The timestamp of the latest chronologically input document.data.missing_fields (or dmf, dataMissingFields): The number of input documents that are missing a field that the anomaly
detection job is configured to analyze. Input documents with missing fields
are still processed because it is possible that not all fields are missing.data.out_of_order_timestamps (or doot, dataOutOfOrderTimestamps): The number of input documents that have a timestamp chronologically
preceding the start of the current anomaly detection bucket offset by the
latency window. This information is applicable only when you provide data
to the anomaly detection job by using the post data API. These out of order
documents are discarded, since jobs require time series data to be in
ascending chronological order.data.processed_fields (or dpf, dataProcessedFields): The total number of fields in all the documents that have been processed by
the anomaly detection job. Only fields that are specified in the detector
configuration object contribute to this count. The timestamp is not
included in this count.data.processed_records (or dpr, dataProcessedRecords): The number of input documents that have been processed by the anomaly
detection job. This value includes documents with missing fields, since
they are nonetheless analyzed. If you use datafeeds and have aggregations
in your search query, the processed record count is the number of
aggregation results processed, not the number of Elasticsearch documents.data.sparse_buckets (or dsb, dataSparseBuckets): The number of buckets that contained few data points compared to the
expected number of data points.forecasts.memory.avg (or fmavg, forecastsMemoryAvg): The average memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.max (or fmmax, forecastsMemoryMax): The maximum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.min (or fmmin, forecastsMemoryMin): The minimum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.total (or fmt, forecastsMemoryTotal): The total memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.records.avg (or fravg, forecastsRecordsAvg): The average number of model_forecast` documents written for forecasts
related to the anomaly detection job.forecasts.records.max (or frmax, forecastsRecordsMax): The maximum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.min (or frmin, forecastsRecordsMin): The minimum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.total (or frt, forecastsRecordsTotal): The total number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.time.avg (or ftavg, forecastsTimeAvg): The average runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.max (or ftmax, forecastsTimeMax): The maximum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.min (or ftmin, forecastsTimeMin): The minimum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.total (or ftt, forecastsTimeTotal): The total runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.total (or ft, forecastsTotal): The number of individual forecasts currently available for the job.id: Identifier for the anomaly detection job.model.bucket_allocation_failures (or mbaf, modelBucketAllocationFailures): The number of buckets for which new entities in incoming data were not
processed due to insufficient model memory.model.by_fields (or mbf, modelByFields): The number of by field values that were analyzed by the models. This value
is cumulative for all detectors in the job.model.bytes (or mb, modelBytes): The number of bytes of memory used by the models. This is the maximum value
since the last time the model was persisted. If the job is closed, this
value indicates the latest size.model.bytes_exceeded (or mbe, modelBytesExceeded): The number of bytes over the high limit for memory usage at the last
allocation failure.model.categorization_status (or mcs, modelCategorizationStatus): The status of categorization for the job: ok or warn. If ok,
categorization is performing acceptably well (or not being used at all). If
warn, categorization is detecting a distribution of categories that
suggests the input data is inappropriate for categorization. Problems could
be that there is only one category, more than 90% of categories are rare,
the number of categories is greater than 50% of the number of categorized
documents, there are no frequently matched categories, or more than 50% of
categories are dead.model.categorized_doc_count (or mcdc, modelCategorizedDocCount): The number of documents that have had a field categorized.model.dead_category_count (or mdcc, modelDeadCategoryCount): The number of categories created by categorization that will never be
assigned again because another category’s definition makes it a superset of
the dead category. Dead categories are a side effect of the way
categorization has no prior training.model.failed_category_count (or mdcc, modelFailedCategoryCount): The number of times that categorization wanted to create a new category but
couldn’t because the job had hit its model memory limit. This count does
not track which specific categories failed to be created. Therefore, you
cannot use this value to determine the number of unique categories that
were missed.model.frequent_category_count (or mfcc, modelFrequentCategoryCount): The number of categories that match more than 1% of categorized documents.model.log_time (or mlt, modelLogTime): The timestamp when the model stats were gathered, according to server time.model.memory_limit (or mml, modelMemoryLimit): The timestamp when the model stats were gathered, according to server time.model.memory_status (or mms, modelMemoryStatus): The status of the mathematical models: ok, soft_limit, or hard_limit.
If ok, the models stayed below the configured value. If soft_limit, the
models used more than 60% of the configured memory limit and older unused
models will be pruned to free up space. Additionally, in categorization jobs
no further category examples will be stored. If hard_limit, the models
used more space than the configured memory limit. As a result, not all
incoming data was processed.model.over_fields (or mof, modelOverFields): The number of over field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.partition_fields (or mpf, modelPartitionFields): The number of partition field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.rare_category_count (or mrcc, modelRareCategoryCount): The number of categories that match just one categorized document.model.timestamp (or mt, modelTimestamp): The timestamp of the last record when the model stats were gathered.model.total_category_count (or mtcc, modelTotalCategoryCount): The number of categories created by categorization.node.address (or na, nodeAddress): The network address of the node that runs the job. This information is
available only for open jobs.node.ephemeral_id (or ne, nodeEphemeralId): The ephemeral ID of the node that runs the job. This information is
available only for open jobs.node.id (or ni, nodeId): The unique identifier of the node that runs the job. This information is
available only for open jobs.node.name (or nn, nodeName): The name of the node that runs the job. This information is available only
for open jobs.opened_time (or ot): For open jobs only, the elapsed time for which the job has been open.state (or s): The status of the anomaly detection job: closed, closing, failed,
opened, or opening. If closed, the job finished successfully with its
model state persisted. The job must be opened before it can accept further
data. If closing, the job close action is in progress and has not yet
completed. A closing job cannot accept further data. If failed, the job
did not finish successfully due to an error. This situation can occur due
to invalid input data, a fatal error occurring during the analysis, or an
external interaction such as the process being killed by the Linux out of
memory (OOM) killer. If the job had irrevocably failed, it must be force
closed and then deleted. If the datafeed can be corrected, the job can be
closed and then re-opened. If opened, the job is available to receive and
process data. If opening, the job open action is in progress and has not
yet completed.Comma-separated list of column names or column aliases used to sort the response.
Supported values include:
assignment_explanation (or ae): For open anomaly detection jobs only, contains messages relating to the
selection of a node to run the job.buckets.count (or bc, bucketsCount): The number of bucket results produced by the job.buckets.time.exp_avg (or btea, bucketsTimeExpAvg): Exponential moving average of all bucket processing times, in milliseconds.buckets.time.exp_avg_hour (or bteah, bucketsTimeExpAvgHour): Exponentially-weighted moving average of bucket processing times calculated
in a 1 hour time window, in milliseconds.buckets.time.max (or btmax, bucketsTimeMax): Maximum among all bucket processing times, in milliseconds.buckets.time.min (or btmin, bucketsTimeMin): Minimum among all bucket processing times, in milliseconds.buckets.time.total (or btt, bucketsTimeTotal): Sum of all bucket processing times, in milliseconds.data.buckets (or db, dataBuckets): The number of buckets processed.data.earliest_record (or der, dataEarliestRecord): The timestamp of the earliest chronologically input document.data.empty_buckets (or deb, dataEmptyBuckets): The number of buckets which did not contain any data.data.input_bytes (or dib, dataInputBytes): The number of bytes of input data posted to the anomaly detection job.data.input_fields (or dif, dataInputFields): The total number of fields in input documents posted to the anomaly
detection job. This count includes fields that are not used in the analysis.
However, be aware that if you are using a datafeed, it extracts only the
required fields from the documents it retrieves before posting them to the job.data.input_records (or dir, dataInputRecords): The number of input documents posted to the anomaly detection job.data.invalid_dates (or did, dataInvalidDates): The number of input documents with either a missing date field or a date
that could not be parsed.data.last (or dl, dataLast): The timestamp at which data was last analyzed, according to server time.data.last_empty_bucket (or dleb, dataLastEmptyBucket): The timestamp of the last bucket that did not contain any data.data.last_sparse_bucket (or dlsb, dataLastSparseBucket): The timestamp of the last bucket that was considered sparse.data.latest_record (or dlr, dataLatestRecord): The timestamp of the latest chronologically input document.data.missing_fields (or dmf, dataMissingFields): The number of input documents that are missing a field that the anomaly
detection job is configured to analyze. Input documents with missing fields
are still processed because it is possible that not all fields are missing.data.out_of_order_timestamps (or doot, dataOutOfOrderTimestamps): The number of input documents that have a timestamp chronologically
preceding the start of the current anomaly detection bucket offset by the
latency window. This information is applicable only when you provide data
to the anomaly detection job by using the post data API. These out of order
documents are discarded, since jobs require time series data to be in
ascending chronological order.data.processed_fields (or dpf, dataProcessedFields): The total number of fields in all the documents that have been processed by
the anomaly detection job. Only fields that are specified in the detector
configuration object contribute to this count. The timestamp is not
included in this count.data.processed_records (or dpr, dataProcessedRecords): The number of input documents that have been processed by the anomaly
detection job. This value includes documents with missing fields, since
they are nonetheless analyzed. If you use datafeeds and have aggregations
in your search query, the processed record count is the number of
aggregation results processed, not the number of Elasticsearch documents.data.sparse_buckets (or dsb, dataSparseBuckets): The number of buckets that contained few data points compared to the
expected number of data points.forecasts.memory.avg (or fmavg, forecastsMemoryAvg): The average memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.max (or fmmax, forecastsMemoryMax): The maximum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.min (or fmmin, forecastsMemoryMin): The minimum memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.memory.total (or fmt, forecastsMemoryTotal): The total memory usage in bytes for forecasts related to the anomaly
detection job.forecasts.records.avg (or fravg, forecastsRecordsAvg): The average number of model_forecast` documents written for forecasts
related to the anomaly detection job.forecasts.records.max (or frmax, forecastsRecordsMax): The maximum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.min (or frmin, forecastsRecordsMin): The minimum number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.records.total (or frt, forecastsRecordsTotal): The total number of model_forecast documents written for forecasts
related to the anomaly detection job.forecasts.time.avg (or ftavg, forecastsTimeAvg): The average runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.max (or ftmax, forecastsTimeMax): The maximum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.min (or ftmin, forecastsTimeMin): The minimum runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.time.total (or ftt, forecastsTimeTotal): The total runtime in milliseconds for forecasts related to the anomaly
detection job.forecasts.total (or ft, forecastsTotal): The number of individual forecasts currently available for the job.id: Identifier for the anomaly detection job.model.bucket_allocation_failures (or mbaf, modelBucketAllocationFailures): The number of buckets for which new entities in incoming data were not
processed due to insufficient model memory.model.by_fields (or mbf, modelByFields): The number of by field values that were analyzed by the models. This value
is cumulative for all detectors in the job.model.bytes (or mb, modelBytes): The number of bytes of memory used by the models. This is the maximum value
since the last time the model was persisted. If the job is closed, this
value indicates the latest size.model.bytes_exceeded (or mbe, modelBytesExceeded): The number of bytes over the high limit for memory usage at the last
allocation failure.model.categorization_status (or mcs, modelCategorizationStatus): The status of categorization for the job: ok or warn. If ok,
categorization is performing acceptably well (or not being used at all). If
warn, categorization is detecting a distribution of categories that
suggests the input data is inappropriate for categorization. Problems could
be that there is only one category, more than 90% of categories are rare,
the number of categories is greater than 50% of the number of categorized
documents, there are no frequently matched categories, or more than 50% of
categories are dead.model.categorized_doc_count (or mcdc, modelCategorizedDocCount): The number of documents that have had a field categorized.model.dead_category_count (or mdcc, modelDeadCategoryCount): The number of categories created by categorization that will never be
assigned again because another category’s definition makes it a superset of
the dead category. Dead categories are a side effect of the way
categorization has no prior training.model.failed_category_count (or mdcc, modelFailedCategoryCount): The number of times that categorization wanted to create a new category but
couldn’t because the job had hit its model memory limit. This count does
not track which specific categories failed to be created. Therefore, you
cannot use this value to determine the number of unique categories that
were missed.model.frequent_category_count (or mfcc, modelFrequentCategoryCount): The number of categories that match more than 1% of categorized documents.model.log_time (or mlt, modelLogTime): The timestamp when the model stats were gathered, according to server time.model.memory_limit (or mml, modelMemoryLimit): The timestamp when the model stats were gathered, according to server time.model.memory_status (or mms, modelMemoryStatus): The status of the mathematical models: ok, soft_limit, or hard_limit.
If ok, the models stayed below the configured value. If soft_limit, the
models used more than 60% of the configured memory limit and older unused
models will be pruned to free up space. Additionally, in categorization jobs
no further category examples will be stored. If hard_limit, the models
used more space than the configured memory limit. As a result, not all
incoming data was processed.model.over_fields (or mof, modelOverFields): The number of over field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.partition_fields (or mpf, modelPartitionFields): The number of partition field values that were analyzed by the models. This
value is cumulative for all detectors in the job.model.rare_category_count (or mrcc, modelRareCategoryCount): The number of categories that match just one categorized document.model.timestamp (or mt, modelTimestamp): The timestamp of the last record when the model stats were gathered.model.total_category_count (or mtcc, modelTotalCategoryCount): The number of categories created by categorization.node.address (or na, nodeAddress): The network address of the node that runs the job. This information is
available only for open jobs.node.ephemeral_id (or ne, nodeEphemeralId): The ephemeral ID of the node that runs the job. This information is
available only for open jobs.node.id (or ni, nodeId): The unique identifier of the node that runs the job. This information is
available only for open jobs.node.name (or nn, nodeName): The name of the node that runs the job. This information is available only
for open jobs.opened_time (or ot): For open jobs only, the elapsed time for which the job has been open.state (or s): The status of the anomaly detection job: closed, closing, failed,
opened, or opening. If closed, the job finished successfully with its
model state persisted. The job must be opened before it can accept further
data. If closing, the job close action is in progress and has not yet
completed. A closing job cannot accept further data. If failed, the job
did not finish successfully due to an error. This situation can occur due
to invalid input data, a fatal error occurring during the analysis, or an
external interaction such as the process being killed by the Linux out of
memory (OOM) killer. If the job had irrevocably failed, it must be force
closed and then deleted. If the datafeed can be corrected, the job can be
closed and then re-opened. If opened, the job is available to receive and
process data. If opening, the job open action is in progress and has not
yet completed.The unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/ml/anomaly_detectors?h=id,s,dpr,mb&v=true&format=json
resp = client.cat.ml_jobs(
h="id,s,dpr,mb",
v=True,
format="json",
)const response = await client.cat.mlJobs({
h: "id,s,dpr,mb",
v: "true",
format: "json",
});response = client.cat.ml_jobs(
h: "id,s,dpr,mb",
v: "true",
format: "json"
)$resp = $client->cat()->mlJobs([
"h" => "id,s,dpr,mb",
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/anomaly_detectors?h=id,s,dpr,mb&v=true&format=json"client.cat().mlJobs();
[
{
"id": "high_sum_total_sales",
"s": "closed",
"dpr": "14022",
"mb": "1.5mb"
},
{
"id": "low_request_rate",
"s": "closed",
"dpr": "1216",
"mb": "40.5kb"
},
{
"id": "response_code_rates",
"s": "closed",
"dpr": "28146",
"mb": "132.7kb"
},
{
"id": "url_scanning",
"s": "closed",
"dpr": "28146",
"mb": "501.6kb"
}
]All methods and paths for this operation:
Get configuration and usage information about inference trained models.
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 trained models statistics API.
monitor_mlSpecifies what to do when the request: contains wildcard expressions and there are no models that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches.
If true, the API returns an empty array when there are no matches and the subset of results when there are partial matches.
If false, the API returns a 404 status code when there are no matches or only partial matches.
The unit used to display byte values.
Values are b, kb, mb, gb, tb, or pb.
A comma-separated list of column names to display.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.A comma-separated list of column names or aliases used to sort the response.
Supported values include:
create_time (or ct): The time when the trained model was created.created_by (or c, createdBy): Information on the creator of the trained model.data_frame_analytics_id (or df, dataFrameAnalytics, dfid): Identifier for the data frame analytics job that created the model. Only
displayed if it is still available.description (or d): The description of the trained model.heap_size (or hs, modelHeapSize): The estimated heap size to keep the trained model in memory.id: Identifier for the trained model.ingest.count (or ic, ingestCount): The total number of documents that are processed by the model.ingest.current (or icurr, ingestCurrent): The total number of document that are currently being handled by the
trained model.ingest.failed (or if, ingestFailed): The total number of failed ingest attempts with the trained model.ingest.pipelines (or ip, ingestPipelines): The total number of ingest pipelines that are referencing the trained
model.ingest.time (or it, ingestTime): The total time that is spent processing documents with the trained model.license (or l): The license level of the trained model.operations (or o, modelOperations): The estimated number of operations to use the trained model. This number
helps measuring the computational complexity of the model.version (or v): The Elasticsearch version number in which the trained model was created.Skips the specified number of transforms.
The maximum number of transforms to display.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET _cat/ml/trained_models?v=true&format=json
resp = client.cat.ml_trained_models(
v=True,
format="json",
)const response = await client.cat.mlTrainedModels({
v: "true",
format: "json",
});response = client.cat.ml_trained_models(
v: "true",
format: "json"
)$resp = $client->cat()->mlTrainedModels([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/ml/trained_models?v=true&format=json"client.cat().mlTrainedModels();
[
{
"id": "ddddd-1580216177138",
"heap_size": "0b",
"operations": "196",
"create_time": "2025-03-25T00:01:38.662Z",
"type": "pytorch",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
},
{
"id": "lang_ident_model_1",
"heap_size": "1mb",
"operations": "39629",
"create_time": "2019-12-05T12:28:34.594Z",
"type": "lang_ident",
"ingest.pipelines": "0",
"data_frame.id": "__none__"
}
]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"
}
]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 the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get snapshot API.
monitor_snapshotA comma-separated list of snapshot repositories used to limit the request.
Accepts wildcard expressions.
_all returns all repositories.
If any repository fails during the request, Elasticsearch returns an error.
A comma-separated list of columns names to display. It supports simple wildcards.
Supported values include:
id (or snapshot): The ID of the snapshot, such as 'snap1'.repository (or re, repo): The name of the repository, such as 'repo1'.status (or s): State of the snapshot process. Returned values are: 'FAILED': The snapshot process failed. 'INCOMPATIBLE': The snapshot process is incompatible with the current cluster version. 'IN_PROGRESS': The snapshot process started but has not completed. 'PARTIAL': The snapshot process completed with a partial success. 'SUCCESS': The snapshot process completed with a full success.start_epoch (or ste, startEpoch): The unix epoch time at which the snapshot process started.start_time (or sti, startTime): 'HH:MM:SS' time at which the snapshot process started.end_epoch (or ete, endEpoch): The unix epoch time at which the snapshot process ended.end_time (or eti, endTime): 'HH:MM:SS' time at which the snapshot process ended.duration (or dur): The time it took the snapshot process to complete in time units.indices (or i): The number of indices in the snapshot.successful_shards (or ss): The number of successful shards in the snapshot.failed_shards (or fs): The number of failed shards in the snapshot.total_shards (or ts): The total number of shards in the snapshot.reason (or r): The reason for any snapshot failures.Values are id, snapshot, repository, re, repo, status, s, start_epoch, ste, startEpoch, start_time, sti, startTime, end_epoch, ete, endEpoch, end_time, eti, endTime, duration, dur, indices, i, successful_shards, ss, failed_shards, fs, total_shards, ts, reason, or r.
List of columns that determine how the table should be sorted.
Sorting defaults to ascending and can be changed by setting :asc
or :desc as a suffix to the column name.
Period to wait for a connection to the master node.
Values are -1 or 0.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
GET /_cat/snapshots/repo1?v=true&s=id&format=json
resp = client.cat.snapshots(
repository="repo1",
v=True,
s="id",
format="json",
)const response = await client.cat.snapshots({
repository: "repo1",
v: "true",
s: "id",
format: "json",
});response = client.cat.snapshots(
repository: "repo1",
v: "true",
s: "id",
format: "json"
)$resp = $client->cat()->snapshots([
"repository" => "repo1",
"v" => "true",
"s" => "id",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/snapshots/repo1?v=true&s=id&format=json"client.cat().snapshots();
[
{
"id": "snap1",
"repository": "repo1",
"status": "FAILED",
"start_epoch": "1445616705",
"start_time": "18:11:45",
"end_epoch": "1445616978",
"end_time": "18:16:18",
"duration": "4.6m",
"indices": "1",
"successful_shards": "4",
"failed_shards": "1",
"total_shards": "5"
},
{
"id": "snap2",
"repository": "repo1",
"status": "SUCCESS",
"start_epoch": "1445634298",
"start_time": "23:04:58",
"end_epoch": "1445634672",
"end_time": "23:11:12",
"duration": "6.2m",
"indices": "2",
"successful_shards": "10",
"failed_shards": "0",
"total_shards": "10"
}
]Get information about tasks currently running 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 task management API.
monitorThe task action names, which are used to limit the response.
If true, the response includes detailed information about shard recoveries.
Unique node identifiers, which are used to limit the response.
The parent task identifier, which is used to limit the response.
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.
Unit used to display time values.
Values are nanos, micros, ms, s, m, h, or d.
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.
If true, the request blocks until the task has completed.
GET _cat/tasks?v=true&format=json
resp = client.cat.tasks(
v=True,
format="json",
)const response = await client.cat.tasks({
v: "true",
format: "json",
});response = client.cat.tasks(
v: "true",
format: "json"
)$resp = $client->cat()->tasks([
"v" => "true",
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/tasks?v=true&format=json"client.cat().tasks();
[
{
"action": "cluster:monitor/tasks/lists[n]",
"task_id": "oTUltX4IQMOUUVeiohTt8A:124",
"parent_task_id": "oTUltX4IQMOUUVeiohTt8A:123",
"type": "direct",
"start_time": "1458585884904",
"timestamp": "01:48:24",
"running_time": "44.1micros",
"ip": "127.0.0.1:9300",
"node": "oTUltX4IQMOUUVeiohTt8A"
},
{
"action": "cluster:monitor/tasks/lists",
"task_id": "oTUltX4IQMOUUVeiohTt8A:123",
"parent_task_id": "-",
"type": "transport",
"start_time": "1458585884904",
"timestamp": "01:48:24",
"running_time": "186.2micros",
"ip": "127.0.0.1:9300",
"node": "oTUltX4IQMOUUVeiohTt8A"
}
]All methods and paths for this operation:
Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. 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.
monitorA comma-separated list of thread pool names used to limit the request. Accepts wildcard expressions.
List of columns to appear in the response. Supports simple wildcards.
Supported values include:
active (or a): Number of active threads in the current thread pool.completed (or c): Number of tasks completed by the thread pool executor.core (or cr): Configured core number of active threads allowed in the current thread pool.ephemeral_id (or eid): Ephemeral node ID.host (or h): Hostname for the current node.ip (or i): IP address for the current node.keep_alive (or k): Configured keep alive time for threads.largest (or l): Highest number of active threads in the current thread pool.max (or mx): Configured maximum number of active threads allowed in the current thread pool.name: Name of the thread pool, such as analyze or generic.node_id (or id): ID of the node, such as k0zy.node_name: Node name, such as I8hydUG.pid (or p): Process ID of the running node.pool_size (or psz): Number of threads in the current thread pool.port (or po): Bound transport port for the current node.queue (or q): Number of tasks in the queue for the current thread pool.queue_size (or qs): Maximum number of tasks permitted in the queue for the current thread pool.rejected (or r): Number of tasks rejected by the thread pool executor.size (or sz): Configured fixed number of active threads allowed in the current thread pool.type (or t): Type of thread pool. Returned values are fixed, fixed_auto_queue_size, direct, or scaling.Values are active, a, completed, c, core, cr, ephemeral_id, eid, host, h, ip, i, keep_alive, k, largest, l, max, mx, name, node_id, id, node_name, pid, p, pool_size, psz, port, po, queue, q, queue_size, qs, rejected, r, size, sz, type, or t.
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.
If true, the request computes the list of selected nodes from the
local cluster state. If false the list of selected nodes are computed
from the cluster state of the master node. In both cases the coordinating
node will send requests for further information to each selected node.
The period to wait for a connection to the master node.
Values are -1 or 0.
GET /_cat/thread_pool?format=json
resp = client.cat.thread_pool(
format="json",
)const response = await client.cat.threadPool({
format: "json",
});response = client.cat.thread_pool(
format: "json"
)$resp = $client->cat()->threadPool([
"format" => "json",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/thread_pool?format=json"client.cat().threadPool();
[
{
"node_name": "node-0",
"name": "analyze",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_started",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "fetch_shard_store",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "flush",
"active": "0",
"queue": "0",
"rejected": "0"
},
{
"node_name": "node-0",
"name": "write",
"active": "0",
"queue": "0",
"rejected": "0"
}
][
{
"id": "0EWUhXeBQtaVGlexUeVwMg",
"name": "generic",
"active": "0",
"rejected": "0",
"completed": "70"
}
]All methods and paths for this operation:
Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
If true, returns information about disk usage and shard sizes.
If true, returns YES decisions in explanation.
Period to wait for a connection to the master node.
Values are -1 or 0.
Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.
Specifies the name of the index that you would like an explanation for.
If true, returns explanation for the primary shard for the given shard ID.
Specifies the ID of the shard that you would like an explanation for.
GET _cluster/allocation/explain
{
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}resp = client.cluster.allocation_explain(
index="my-index-000001",
shard=0,
primary=False,
current_node="my-node",
)const response = await client.cluster.allocationExplain({
index: "my-index-000001",
shard: 0,
primary: false,
current_node: "my-node",
});response = client.cluster.allocation_explain(
body: {
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}
)$resp = $client->cluster()->allocationExplain([
"body" => [
"index" => "my-index-000001",
"shard" => 0,
"primary" => false,
"current_node" => "my-node",
],
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":"my-index-000001","shard":0,"primary":false,"current_node":"my-node"}' "$ELASTICSEARCH_URL/_cluster/allocation/explain"client.cluster().allocationExplain(a -> a
.currentNode("my-node")
.index("my-index-000001")
.primary(false)
.shard(0)
);
{
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "unassigned",
"unassigned_info" : {
"reason" : "INDEX_CREATED",
"at" : "2017-01-04T18:08:16.600Z",
"last_allocation_status" : "no"
},
"can_allocate" : "no",
"allocate_explanation" : "Elasticsearch isn't allowed to allocate this shard to any of the nodes in the cluster. Choose a node to which you expect this shard to be allocated, find this node in the node-by-node explanation, and address the reasons which prevent Elasticsearch from allocating this shard there.",
"node_allocation_decisions" : [
{
"node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
"node_name" : "node-0",
"transport_address" : "127.0.0.1:9401",
"roles" : ["data", "data_cold", "data_content", "data_frozen", "data_hot", "data_warm", "ingest", "master", "ml", "remote_cluster_client", "transform"],
"node_attributes" : {},
"node_decision" : "no",
"weight_ranking" : 1,
"deciders" : [
{
"decider" : "filter",
"decision" : "NO",
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]"
}
]
}
]
}{
"index" : "my-index-000001",
"shard" : 0,
"primary" : true,
"current_state" : "unassigned",
"unassigned_info" : {
"at" : "2017-01-04T18:03:28.464Z",
"failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException",
"reason": "ALLOCATION_FAILED",
"failed_allocation_attempts": 5,
"last_allocation_status": "no",
},
"can_allocate": "no",
"allocate_explanation": "cannot allocate because allocation is not permitted to any of the nodes",
"node_allocation_decisions" : [
{
"node_id" : "3sULLVJrRneSg0EfBB-2Ew",
"node_name" : "node_t0",
"transport_address" : "127.0.0.1:9400",
"roles" : ["data_content", "data_hot"],
"node_decision" : "no",
"store" : {
"matching_size" : "4.2kb",
"matching_size_in_bytes" : 4325
},
"deciders" : [
{
"decider": "max_retry",
"decision" : "NO",
"explanation": "shard has exceeded the maximum number of retries [5] on failed allocation attempts - manually call [POST /_cluster/reroute?retry_failed] to retry, [unassigned_info[[reason=ALLOCATION_FAILED], at[2024-07-30T21:04:12.166Z], failed_attempts[5], failed_nodes[[mEKjwwzLT1yJVb8UxT6anw]], delayed=false, details[failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException], allocation_status[deciders_no]]]"
}
]
}
]
}Remove master-eligible nodes from the voting configuration exclusion list.
Period to wait for a connection to the master node.
Values are -1 or 0.
Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from the cluster before this API takes any action. If set to false then the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster.
curl \
--request DELETE 'http://api.example.com/_cluster/voting_config_exclusions' \
--header "Authorization: $API_KEY"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"client.cluster().info(i -> i
.target("_all")
);
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"
}
}
]
}curl \
--request HEAD 'http://api.example.com/' \
--header "Authorization: $API_KEY"Get repositories metering information for a cluster. This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.
monitor,managecurl \
--request GET 'http://api.example.com/_nodes/{node_id}/_repositories_metering' \
--header "Authorization: $API_KEY"All methods and paths for this operation:
By default, the API returns all attributes and core settings for cluster nodes.
Comma-separated list of node IDs or names used to limit returned information.
Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest.
GET _nodes/_all/jvm
resp = client.nodes.info(
node_id="_all",
metric="jvm",
)const response = await client.nodes.info({
node_id: "_all",
metric: "jvm",
});response = client.nodes.info(
node_id: "_all",
metric: "jvm"
)$resp = $client->nodes()->info([
"node_id" => "_all",
"metric" => "jvm",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_nodes/_all/jvm"client.nodes().info(i -> i
.metric("jvm")
.nodeId("_all")
);
{
"_nodes": {},
"cluster_name": "elasticsearch",
"nodes": {
"USpTGYaBSIKbgSUJR2Z9lg": {
"name": "node-0",
"transport_address": "192.168.17:9300",
"host": "node-0.elastic.co",
"ip": "192.168.17",
"version": "{version}",
"transport_version": 100000298,
"index_version": 100000074,
"component_versions": {
"ml_config_version": 100000162,
"transform_config_version": 100000096
},
"build_flavor": "default",
"build_type": "{build_type}",
"build_hash": "587409e",
"roles": [
"master",
"data",
"ingest"
],
"attributes": {},
"plugins": [
{
"name": "analysis-icu",
"version": "{version}",
"description": "The ICU Analysis plugin integrates Lucene ICU
module into elasticsearch, adding ICU relates analysis components.",
"classname":
"org.elasticsearch.plugin.analysis.icu.AnalysisICUPlugin",
"has_native_controller": false
}
],
"modules": [
{
"name": "lang-painless",
"version": "{version}",
"description": "An easy, safe and fast scripting language for
Elasticsearch",
"classname": "org.elasticsearch.painless.PainlessPlugin",
"has_native_controller": false
}
]
}
}
}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"client.healthReport(h -> h);
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"client.connector().checkIn(c -> c
.connectorId("my-connector")
);
{
"result": "updated"
}Starting offset (default: 0)
Specifies a max number of results to get
A comma-separated list of connector index names to fetch connector documents for
A comma-separated list of connector names to fetch connector documents for
A comma-separated list of connector service types to fetch connector documents for
A wildcard query string that filters connectors with matching name, description or index name
GET _connector
resp = client.connector.list()const response = await client.connector.list();response = client.connector.list$resp = $client->connector()->list();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector"client.connector().list(l -> l);
Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time.
The connector service is then responsible for setting the status of connector sync jobs to cancelled.
PUT _connector/_sync_job/my-connector-sync-job-id/_cancel
resp = client.connector.sync_job_cancel(
connector_sync_job_id="my-connector-sync-job-id",
)const response = await client.connector.syncJobCancel({
connector_sync_job_id: "my-connector-sync-job-id",
});response = client.connector.sync_job_cancel(
connector_sync_job_id: "my-connector-sync-job-id"
)$resp = $client->connector()->syncJobCancel([
"connector_sync_job_id" => "my-connector-sync-job-id",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id/_cancel"client.connector().syncJobCancel(s -> s
.connectorSyncJobId("my-connector-sync-job-id")
);
Check in a connector sync job and set the last_seen field to the current time before updating it in the internal index.
To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.
PUT _connector/_sync_job/my-connector-sync-job/_check_in
resp = client.connector.sync_job_check_in(
connector_sync_job_id="my-connector-sync-job",
)const response = await client.connector.syncJobCheckIn({
connector_sync_job_id: "my-connector-sync-job",
});response = client.connector.sync_job_check_in(
connector_sync_job_id: "my-connector-sync-job"
)$resp = $client->connector()->syncJobCheckIn([
"connector_sync_job_id" => "my-connector-sync-job",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_check_in"client.connector().syncJobCheckIn(s -> s
.connectorSyncJobId("my-connector-sync-job")
);
GET _connector/_sync_job/my-connector-sync-job
resp = client.connector.sync_job_get(
connector_sync_job_id="my-connector-sync-job",
)const response = await client.connector.syncJobGet({
connector_sync_job_id: "my-connector-sync-job",
});response = client.connector.sync_job_get(
connector_sync_job_id: "my-connector-sync-job"
)$resp = $client->connector()->syncJobGet([
"connector_sync_job_id" => "my-connector-sync-job",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job"client.connector().syncJobGet(s -> s
.connectorSyncJobId("my-connector-sync-job")
);
Get information about all stored connector sync jobs listed by their creation date in ascending order.
Starting offset (default: 0)
Specifies a max number of results to get
A sync job status to fetch connector sync jobs for
Values are canceling, canceled, completed, error, in_progress, pending, or suspended.
A connector id to fetch connector sync jobs for
A comma-separated list of job types to fetch the sync jobs for
Supported values include: full, incremental, access_control
Values are full, incremental, or access_control.
GET _connector/_sync_job?connector_id=my-connector-id&size=1
resp = client.connector.sync_job_list(
connector_id="my-connector-id",
size="1",
)const response = await client.connector.syncJobList({
connector_id: "my-connector-id",
size: 1,
});response = client.connector.sync_job_list(
connector_id: "my-connector-id",
size: "1"
)$resp = $client->connector()->syncJobList([
"connector_id" => "my-connector-id",
"size" => "1",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_connector/_sync_job?connector_id=my-connector-id&size=1"client.connector().syncJobList(s -> s
.connectorId("my-connector-id")
.size(1)
);
Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.
PUT _connector/my-connector/_index_name
{
"index_name": "data-from-my-google-drive"
}resp = client.connector.update_index_name(
connector_id="my-connector",
index_name="data-from-my-google-drive",
)const response = await client.connector.updateIndexName({
connector_id: "my-connector",
index_name: "data-from-my-google-drive",
});response = client.connector.update_index_name(
connector_id: "my-connector",
body: {
"index_name": "data-from-my-google-drive"
}
)$resp = $client->connector()->updateIndexName([
"connector_id" => "my-connector",
"body" => [
"index_name" => "data-from-my-google-drive",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_name":"data-from-my-google-drive"}' "$ELASTICSEARCH_URL/_connector/my-connector/_index_name"client.connector().updateIndexName(u -> u
.connectorId("my-connector")
.indexName("data-from-my-google-drive")
);
{
"index_name": "data-from-my-google-drive"
}{
"result": "updated"
}When you create a new connector, the configuration of an ingest pipeline is populated with default settings.
PUT _connector/my-connector/_pipeline
{
"pipeline": {
"extract_binary_content": true,
"name": "my-connector-pipeline",
"reduce_whitespace": true,
"run_ml_inference": true
}
}resp = client.connector.update_pipeline(
connector_id="my-connector",
pipeline={
"extract_binary_content": True,
"name": "my-connector-pipeline",
"reduce_whitespace": True,
"run_ml_inference": True
},
)const response = await client.connector.updatePipeline({
connector_id: "my-connector",
pipeline: {
extract_binary_content: true,
name: "my-connector-pipeline",
reduce_whitespace: true,
run_ml_inference: true,
},
});response = client.connector.update_pipeline(
connector_id: "my-connector",
body: {
"pipeline": {
"extract_binary_content": true,
"name": "my-connector-pipeline",
"reduce_whitespace": true,
"run_ml_inference": true
}
}
)$resp = $client->connector()->updatePipeline([
"connector_id" => "my-connector",
"body" => [
"pipeline" => [
"extract_binary_content" => true,
"name" => "my-connector-pipeline",
"reduce_whitespace" => true,
"run_ml_inference" => true,
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"pipeline":{"extract_binary_content":true,"name":"my-connector-pipeline","reduce_whitespace":true,"run_ml_inference":true}}' "$ELASTICSEARCH_URL/_connector/my-connector/_pipeline"client.connector().updatePipeline(u -> u
.connectorId("my-connector")
.pipeline(p -> p
.extractBinaryContent(true)
.name("my-connector-pipeline")
.reduceWhitespace(true)
.runMlInference(true)
)
);
{
"pipeline": {
"extract_binary_content": true,
"name": "my-connector-pipeline",
"reduce_whitespace": true,
"run_ml_inference": true
}
}{
"result": "updated"
}PUT _connector/my-connector/_status
{
"status": "needs_configuration"
}resp = client.connector.update_status(
connector_id="my-connector",
status="needs_configuration",
)const response = await client.connector.updateStatus({
connector_id: "my-connector",
status: "needs_configuration",
});response = client.connector.update_status(
connector_id: "my-connector",
body: {
"status": "needs_configuration"
}
)$resp = $client->connector()->updateStatus([
"connector_id" => "my-connector",
"body" => [
"status" => "needs_configuration",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"status":"needs_configuration"}' "$ELASTICSEARCH_URL/_connector/my-connector/_status"client.connector().updateStatus(u -> u
.connectorId("my-connector")
.status(ConnectorStatus.NeedsConfiguration)
);
{
"status": "needs_configuration"
}{
"result": "updated"
}Create a collection of cross-cluster replication auto-follow patterns for a remote cluster. Newly created indices on the remote cluster that match any of the patterns are automatically configured as follower indices. Indices on the remote cluster that were created before the auto-follow pattern was created will not be auto-followed even if they match the pattern.
This API can also be used to update auto-follow patterns. NOTE: Follower indices that were configured automatically before updating an auto-follow pattern will remain unchanged even if they do not match against the new patterns.
The remote cluster containing the leader indices to match against.
The name of follower index. The template {{leader_index}} can be used to derive the name of the follower index from the name of the leader index. When following a data stream, use {{leader_index}}; CCR does not support changes to the names of a follower data stream’s backing indices.
An array of simple index patterns to match against indices in the remote cluster specified by the remote_cluster field.
An array of simple index patterns that can be used to exclude indices from being auto-followed. Indices in the remote cluster whose names are matching one or more leader_index_patterns and one or more leader_index_exclusion_patterns won’t be followed.
The maximum number of outstanding reads requests from the remote cluster.
Default value is 12.
Settings to override from the leader index. Note that certain settings can not be overrode (e.g., index.number_of_shards).
The maximum number of outstanding reads requests from the remote cluster.
Default value is 9.
The maximum time to wait for new operations on the remote cluster when the follower index is synchronized with the leader index. When the timeout has elapsed, the poll for operations will return to the follower so that it can update some statistics. Then the follower will immediately attempt to read from the leader again.
The maximum number of operations to pull per read from the remote cluster.
Default value is 5120.
The maximum time to wait before retrying an operation that failed exceptionally. An exponential backoff strategy is employed when retrying.
The maximum number of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the number of queued operations goes below the limit.
Default value is 2147483647.
The maximum total bytes of operations that can be queued for writing. When this limit is reached, reads from the remote cluster will be deferred until the total bytes of queued operations goes below the limit.
The maximum number of operations per bulk write request executed on the follower.
Default value is 5120.
PUT /_ccr/auto_follow/my_auto_follow_pattern
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}resp = client.ccr.put_auto_follow_pattern(
name="my_auto_follow_pattern",
remote_cluster="remote_cluster",
leader_index_patterns=[
"leader_index*"
],
follow_index_pattern="{{leader_index}}-follower",
settings={
"index.number_of_replicas": 0
},
max_read_request_operation_count=1024,
max_outstanding_read_requests=16,
max_read_request_size="1024k",
max_write_request_operation_count=32768,
max_write_request_size="16k",
max_outstanding_write_requests=8,
max_write_buffer_count=512,
max_write_buffer_size="512k",
max_retry_delay="10s",
read_poll_timeout="30s",
)const response = await client.ccr.putAutoFollowPattern({
name: "my_auto_follow_pattern",
remote_cluster: "remote_cluster",
leader_index_patterns: ["leader_index*"],
follow_index_pattern: "{{leader_index}}-follower",
settings: {
"index.number_of_replicas": 0,
},
max_read_request_operation_count: 1024,
max_outstanding_read_requests: 16,
max_read_request_size: "1024k",
max_write_request_operation_count: 32768,
max_write_request_size: "16k",
max_outstanding_write_requests: 8,
max_write_buffer_count: 512,
max_write_buffer_size: "512k",
max_retry_delay: "10s",
read_poll_timeout: "30s",
});response = client.ccr.put_auto_follow_pattern(
name: "my_auto_follow_pattern",
body: {
"remote_cluster": "remote_cluster",
"leader_index_patterns": [
"leader_index*"
],
"follow_index_pattern": "{{leader_index}}-follower",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count": 1024,
"max_outstanding_read_requests": 16,
"max_read_request_size": "1024k",
"max_write_request_operation_count": 32768,
"max_write_request_size": "16k",
"max_outstanding_write_requests": 8,
"max_write_buffer_count": 512,
"max_write_buffer_size": "512k",
"max_retry_delay": "10s",
"read_poll_timeout": "30s"
}
)$resp = $client->ccr()->putAutoFollowPattern([
"name" => "my_auto_follow_pattern",
"body" => [
"remote_cluster" => "remote_cluster",
"leader_index_patterns" => array(
"leader_index*",
),
"follow_index_pattern" => "{{leader_index}}-follower",
"settings" => [
"index.number_of_replicas" => 0,
],
"max_read_request_operation_count" => 1024,
"max_outstanding_read_requests" => 16,
"max_read_request_size" => "1024k",
"max_write_request_operation_count" => 32768,
"max_write_request_size" => "16k",
"max_outstanding_write_requests" => 8,
"max_write_buffer_count" => 512,
"max_write_buffer_size" => "512k",
"max_retry_delay" => "10s",
"read_poll_timeout" => "30s",
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"remote_cluster":"remote_cluster","leader_index_patterns":["leader_index*"],"follow_index_pattern":"{{leader_index}}-follower","settings":{"index.number_of_replicas":0},"max_read_request_operation_count":1024,"max_outstanding_read_requests":16,"max_read_request_size":"1024k","max_write_request_operation_count":32768,"max_write_request_size":"16k","max_outstanding_write_requests":8,"max_write_buffer_count":512,"max_write_buffer_size":"512k","max_retry_delay":"10s","read_poll_timeout":"30s"}' "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern"client.ccr().putAutoFollowPattern(p -> p
.followIndexPattern("{{leader_index}}-follower")
.leaderIndexPatterns("leader_index*")
.maxOutstandingReadRequests(16)
.maxOutstandingWriteRequests(8)
.maxReadRequestOperationCount(1024)
.maxReadRequestSize("1024k")
.maxRetryDelay(m -> m
.time("10s")
)
.maxWriteBufferCount(512)
.maxWriteBufferSize("512k")
.maxWriteRequestOperationCount(32768)
.maxWriteRequestSize("16k")
.name("my_auto_follow_pattern")
.readPollTimeout(r -> r
.time("30s")
)
.remoteCluster("remote_cluster")
.settings("index.number_of_replicas", JsonData.fromJson("0"))
);
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower",
"settings": {
"index.number_of_replicas": 0
},
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}{
"acknowledged": true
}Delete a collection of cross-cluster replication auto-follow patterns.
manage_ccrDELETE /_ccr/auto_follow/my_auto_follow_pattern
resp = client.ccr.delete_auto_follow_pattern(
name="my_auto_follow_pattern",
)const response = await client.ccr.deleteAutoFollowPattern({
name: "my_auto_follow_pattern",
});response = client.ccr.delete_auto_follow_pattern(
name: "my_auto_follow_pattern"
)$resp = $client->ccr()->deleteAutoFollowPattern([
"name" => "my_auto_follow_pattern",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern"client.ccr().deleteAutoFollowPattern(d -> d
.name("my_auto_follow_pattern")
);
{
"acknowledged" : true
}Get cross-cluster replication follower stats. The API returns shard-level stats about the "following tasks" associated with each shard for the specified indices.
monitorGET /follower_index/_ccr/stats
resp = client.ccr.follow_stats(
index="follower_index",
)const response = await client.ccr.followStats({
index: "follower_index",
});response = client.ccr.follow_stats(
index: "follower_index"
)$resp = $client->ccr()->followStats([
"index" => "follower_index",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/follower_index/_ccr/stats"client.ccr().followStats(f -> f
.index("follower_index")
);
{
"indices" : [
{
"index" : "follower_index",
"total_global_checkpoint_lag" : 256,
"shards" : [
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"follower_index" : "follower_index",
"shard_id" : 0,
"leader_global_checkpoint" : 1024,
"leader_max_seq_no" : 1536,
"follower_global_checkpoint" : 768,
"follower_max_seq_no" : 896,
"last_requested_seq_no" : 897,
"outstanding_read_requests" : 8,
"outstanding_write_requests" : 2,
"write_buffer_operation_count" : 64,
"follower_mapping_version" : 4,
"follower_settings_version" : 2,
"follower_aliases_version" : 8,
"total_read_time_millis" : 32768,
"total_read_remote_exec_time_millis" : 16384,
"successful_read_requests" : 32,
"failed_read_requests" : 0,
"operations_read" : 896,
"bytes_read" : 32768,
"total_write_time_millis" : 16384,
"write_buffer_size_in_bytes" : 1536,
"successful_write_requests" : 16,
"failed_write_requests" : 0,
"operations_written" : 832,
"read_exceptions" : [ ],
"time_since_last_read_millis" : 8
}
]
}
]
}Remove the cross-cluster replication follower retention leases from the leader.
A following index takes out retention leases on its leader index. These leases are used to increase the likelihood that the shards of the leader index retain the history of operations that the shards of the following index need to run replication. When a follower index is converted to a regular index by the unfollow API (either by directly calling the API or by index lifecycle management tasks), these leases are removed. However, removal of the leases can fail, for example when the remote cluster containing the leader index is unavailable. While the leases will eventually expire on their own, their extended existence can cause the leader index to hold more history than necessary and prevent index lifecycle management from performing some operations on the leader index. This API exists to enable manually removing the leases when the unfollow API is unable to do so.
NOTE: This API does not stop replication by a following index. If you use this API with a follower index that is still actively following, the following index will add back retention leases on the leader. The only purpose of this API is to handle the case of failure to remove the following retention leases after the unfollow API is invoked.
the name of the leader index for which specified follower retention leases should be removed
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 /<leader_index>/_ccr/forget_follower
{
"follower_cluster" : "<follower_cluster>",
"follower_index" : "<follower_index>",
"follower_index_uuid" : "<follower_index_uuid>",
"leader_remote_cluster" : "<leader_remote_cluster>"
}resp = client.ccr.forget_follower(
index="<leader_index>",
follower_cluster="<follower_cluster>",
follower_index="<follower_index>",
follower_index_uuid="<follower_index_uuid>",
leader_remote_cluster="<leader_remote_cluster>",
)const response = await client.ccr.forgetFollower({
index: "<leader_index>",
follower_cluster: "<follower_cluster>",
follower_index: "<follower_index>",
follower_index_uuid: "<follower_index_uuid>",
leader_remote_cluster: "<leader_remote_cluster>",
});response = client.ccr.forget_follower(
index: "<leader_index>",
body: {
"follower_cluster": "<follower_cluster>",
"follower_index": "<follower_index>",
"follower_index_uuid": "<follower_index_uuid>",
"leader_remote_cluster": "<leader_remote_cluster>"
}
)$resp = $client->ccr()->forgetFollower([
"index" => "<leader_index>",
"body" => [
"follower_cluster" => "<follower_cluster>",
"follower_index" => "<follower_index>",
"follower_index_uuid" => "<follower_index_uuid>",
"leader_remote_cluster" => "<leader_remote_cluster>",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"follower_cluster":"<follower_cluster>","follower_index":"<follower_index>","follower_index_uuid":"<follower_index_uuid>","leader_remote_cluster":"<leader_remote_cluster>"}' "$ELASTICSEARCH_URL/<leader_index>/_ccr/forget_follower"client.ccr().forgetFollower(f -> f
.followerCluster("<follower_cluster>")
.followerIndex("<follower_index>")
.followerIndexUuid("<follower_index_uuid>")
.index("<leader_index>")
.leaderRemoteCluster("<leader_remote_cluster>")
);
{
"follower_cluster" : "<follower_cluster>",
"follower_index" : "<follower_index>",
"follower_index_uuid" : "<follower_index_uuid>",
"leader_remote_cluster" : "<leader_remote_cluster>"
}{
"_shards" : {
"total" : 1,
"successful" : 1,
"failed" : 0,
"failures" : [ ]
}
}Pause a cross-cluster replication auto-follow pattern. When the API returns, the auto-follow pattern is inactive. New indices that are created on the remote cluster and match the auto-follow patterns are ignored.
You can resume auto-following with the resume auto-follow pattern API. When it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns. Remote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.
manage_ccrPOST /_ccr/auto_follow/my_auto_follow_pattern/pause
resp = client.ccr.pause_auto_follow_pattern(
name="my_auto_follow_pattern",
)const response = await client.ccr.pauseAutoFollowPattern({
name: "my_auto_follow_pattern",
});response = client.ccr.pause_auto_follow_pattern(
name: "my_auto_follow_pattern"
)$resp = $client->ccr()->pauseAutoFollowPattern([
"name" => "my_auto_follow_pattern",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern/pause"client.ccr().pauseAutoFollowPattern(p -> p
.name("my_auto_follow_pattern")
);
{
"acknowledged" : true
}Resume a cross-cluster replication auto-follow pattern that was paused. The auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster. Remote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.
manage_ccrPOST /_ccr/auto_follow/my_auto_follow_pattern/resume
resp = client.ccr.resume_auto_follow_pattern(
name="my_auto_follow_pattern",
)const response = await client.ccr.resumeAutoFollowPattern({
name: "my_auto_follow_pattern",
});response = client.ccr.resume_auto_follow_pattern(
name: "my_auto_follow_pattern"
)$resp = $client->ccr()->resumeAutoFollowPattern([
"name" => "my_auto_follow_pattern",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ccr/auto_follow/my_auto_follow_pattern/resume"client.ccr().resumeAutoFollowPattern(r -> r
.name("my_auto_follow_pattern")
);
{
"acknowledged" : true
}Resume a cross-cluster replication follower index that was paused. The follower index could have been paused with the pause follower API. Alternatively it could be paused due to replication that cannot be retried due to failures during following tasks. When this API returns, the follower index will resume fetching operations from the leader index.
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.
POST /follower_index/_ccr/resume_follow
{
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}resp = client.ccr.resume_follow(
index="follower_index",
max_read_request_operation_count=1024,
max_outstanding_read_requests=16,
max_read_request_size="1024k",
max_write_request_operation_count=32768,
max_write_request_size="16k",
max_outstanding_write_requests=8,
max_write_buffer_count=512,
max_write_buffer_size="512k",
max_retry_delay="10s",
read_poll_timeout="30s",
)const response = await client.ccr.resumeFollow({
index: "follower_index",
max_read_request_operation_count: 1024,
max_outstanding_read_requests: 16,
max_read_request_size: "1024k",
max_write_request_operation_count: 32768,
max_write_request_size: "16k",
max_outstanding_write_requests: 8,
max_write_buffer_count: 512,
max_write_buffer_size: "512k",
max_retry_delay: "10s",
read_poll_timeout: "30s",
});response = client.ccr.resume_follow(
index: "follower_index",
body: {
"max_read_request_operation_count": 1024,
"max_outstanding_read_requests": 16,
"max_read_request_size": "1024k",
"max_write_request_operation_count": 32768,
"max_write_request_size": "16k",
"max_outstanding_write_requests": 8,
"max_write_buffer_count": 512,
"max_write_buffer_size": "512k",
"max_retry_delay": "10s",
"read_poll_timeout": "30s"
}
)$resp = $client->ccr()->resumeFollow([
"index" => "follower_index",
"body" => [
"max_read_request_operation_count" => 1024,
"max_outstanding_read_requests" => 16,
"max_read_request_size" => "1024k",
"max_write_request_operation_count" => 32768,
"max_write_request_size" => "16k",
"max_outstanding_write_requests" => 8,
"max_write_buffer_count" => 512,
"max_write_buffer_size" => "512k",
"max_retry_delay" => "10s",
"read_poll_timeout" => "30s",
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"max_read_request_operation_count":1024,"max_outstanding_read_requests":16,"max_read_request_size":"1024k","max_write_request_operation_count":32768,"max_write_request_size":"16k","max_outstanding_write_requests":8,"max_write_buffer_count":512,"max_write_buffer_size":"512k","max_retry_delay":"10s","read_poll_timeout":"30s"}' "$ELASTICSEARCH_URL/follower_index/_ccr/resume_follow"client.ccr().resumeFollow(r -> r
.index("follower_index")
.maxOutstandingReadRequests(16L)
.maxOutstandingWriteRequests(8L)
.maxReadRequestOperationCount(1024L)
.maxReadRequestSize("1024k")
.maxRetryDelay(m -> m
.time("10s")
)
.maxWriteBufferCount(512L)
.maxWriteBufferSize("512k")
.maxWriteRequestOperationCount(32768L)
.maxWriteRequestSize("16k")
.readPollTimeout(re -> re
.time("30s")
)
);
{
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}{
"acknowledged" : true
}Comma-separated list of data streams to delete. Wildcard (*) expressions are supported.
Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.
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.
DELETE _data_stream/my-data-stream
resp = client.indices.delete_data_stream(
name="my-data-stream",
)const response = await client.indices.deleteDataStream({
name: "my-data-stream",
});response = client.indices.delete_data_stream(
name: "my-data-stream"
)$resp = $client->indices()->deleteDataStream([
"name" => "my-data-stream",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream"client.indices().deleteDataStream(d -> d
.name("my-data-stream")
);
Comma-separated list of data streams used to limit the request.
Wildcard expressions (*) are supported.
To target all data streams in a cluster, omit this parameter or use *.
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.
GET /_data_stream/my-index-000001/_stats
resp = client.indices.data_streams_stats(
name="my-index-000001",
)const response = await client.indices.dataStreamsStats({
name: "my-index-000001",
});response = client.indices.data_streams_stats(
name: "my-index-000001"
)$resp = $client->indices()->dataStreamsStats([
"name" => "my-index-000001",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-index-000001/_stats"client.indices().dataStreamsStats(d -> d
.name("my-index-000001")
);
{
"_shards": {
"total": 10,
"successful": 5,
"failed": 0
},
"data_stream_count": 2,
"backing_indices": 5,
"total_store_size": "7kb",
"total_store_size_bytes": 7268,
"data_streams": [
{
"data_stream": "my-data-stream",
"backing_indices": 3,
"store_size": "3.7kb",
"store_size_bytes": 3772,
"maximum_timestamp": 1607512028000
},
{
"data_stream": "my-data-stream-two",
"backing_indices": 2,
"store_size": "3.4kb",
"store_size_bytes": 3496,
"maximum_timestamp": 1607425567000
}
]
}Get the data stream lifecycle configuration of one or more data streams.
Comma-separated list of data streams to limit the request.
Supports wildcards (*).
To target all data streams, omit this parameter or use * or _all.
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, return all default settings in the response.
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 /_data_stream/{name}/_lifecycle?human&pretty
resp = client.indices.get_data_lifecycle(
name="{name}",
human=True,
pretty=True,
)const response = await client.indices.getDataLifecycle({
name: "{name}",
human: "true",
pretty: "true",
});response = client.indices.get_data_lifecycle(
name: "{name}",
human: "true",
pretty: "true"
)$resp = $client->indices()->getDataLifecycle([
"name" => "{name}",
"human" => "true",
"pretty" => "true",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/%7Bname%7D/_lifecycle?human&pretty"{
"data_streams": [
{
"name": "my-data-stream-1",
"lifecycle": {
"enabled": true,
"data_retention": "7d"
}
},
{
"name": "my-data-stream-2",
"lifecycle": {
"enabled": true,
"data_retention": "7d"
}
}
]
}Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.
GET .ds-metrics-2023.03.22-000001/_lifecycle/explain
resp = client.indices.explain_data_lifecycle(
index=".ds-metrics-2023.03.22-000001",
)const response = await client.indices.explainDataLifecycle({
index: ".ds-metrics-2023.03.22-000001",
});response = client.indices.explain_data_lifecycle(
index: ".ds-metrics-2023.03.22-000001"
)$resp = $client->indices()->explainDataLifecycle([
"index" => ".ds-metrics-2023.03.22-000001",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/.ds-metrics-2023.03.22-000001/_lifecycle/explain"client.indices().explainDataLifecycle(e -> e
.index(".ds-metrics-2023.03.22-000001")
);
{
"indices": {
".ds-metrics-2023.03.22-000001": {
"index" : ".ds-metrics-2023.03.22-000001",
"managed_by_lifecycle" : true,
"index_creation_date_millis" : 1679475563571,
"time_since_index_creation" : "843ms",
"rollover_date_millis" : 1679475564293,
"time_since_rollover" : "121ms",
"lifecycle" : { },
"generation_time" : "121ms"
}
}{
"indices": {
".ds-metrics-2023.03.22-000001": {
"index" : ".ds-metrics-2023.03.22-000001",
"managed_by_lifecycle" : true,
"index_creation_date_millis" : 1679475563571,
"time_since_index_creation" : "843ms",
"lifecycle" : {
"enabled": true
},
"error": "{\"type\":\"validation_exception\",\"reason\":\"Validation Failed: 1: this action would add [2] shards, but this cluster
currently has [4]/[3] maximum normal shards open;\"}"
}
}Get statistics about the data streams that are managed by a data stream lifecycle.
monitorGET _lifecycle/stats?human&pretty
resp = client.indices.get_data_lifecycle_stats(
human=True,
pretty=True,
)const response = await client.indices.getDataLifecycleStats({
human: "true",
pretty: "true",
});response = client.indices.get_data_lifecycle_stats(
human: "true",
pretty: "true"
)$resp = $client->indices()->getDataLifecycleStats([
"human" => "true",
"pretty" => "true",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_lifecycle/stats?human&pretty"client.indices().getDataLifecycleStats();
{
"last_run_duration_in_millis": 2,
"last_run_duration": "2ms",
"time_between_starts_in_millis": 9998,
"time_between_starts": "9.99s",
"data_streams_count": 2,
"data_streams": [
{
"name": "my-data-stream",
"backing_indices_in_total": 2,
"backing_indices_in_error": 0
},
{
"name": "my-other-stream",
"backing_indices_in_total": 2,
"backing_indices_in_error": 1
}
]
}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.*BulkAllObservableElasticsearch::Helpers::BulkHelperSubmitting 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).
Index the specified document. If the document exists, it replaces the document and increments the version. The following line must contain the source data to be indexed.
Index the specified document if it does not already exist. The following line must contain the source data to be indexed.
Perform a partial document update. The following line must contain the partial document and update options.
Remove the specified document from the index.
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"
}
}
}
]
}Remove a JSON document from the specified index.
NOTE: You cannot send deletion requests directly to a data stream. To delete a document in a data stream, you must target the backing index containing the document.
Optimistic concurrency control
Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters.
If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.
Versioning
Each document indexed is versioned.
When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime.
Every write operation run on a document, deletes included, causes its version to be incremented.
The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations.
The length of time for which a deleted document's version remains available is determined by the index.gc_deletes index setting.
Routing
If routing is used during indexing, the routing value also needs to be specified to delete a document.
If the _routing mapping is set to required and no routing value is specified, the delete API throws a RoutingMissingException and rejects the request.
For example:
DELETE /my-index-000001/_doc/1?routing=shard-1
This request deletes the document with ID 1, but it is routed based on the user. The document is not deleted if the correct routing is not specified.
Distributed
The delete operation gets hashed into a specific shard ID. It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.
deleteOnly perform the operation if the document has this primary term.
Only perform the operation if the document has this sequence number.
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.
A custom value used to route operations to a specific shard.
The period to wait for active shards.
This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. Some reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation. By default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.
Values are -1 or 0.
An explicit 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.
The minimum 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.
DELETE /my-index-000001/_doc/1
resp = client.delete(
index="my-index-000001",
id="1",
)const response = await client.delete({
index: "my-index-000001",
id: 1,
});response = client.delete(
index: "my-index-000001",
id: "1"
)$resp = $client->delete([
"index" => "my-index-000001",
"id" => "1",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_doc/1"client.delete(d -> d
.id("1")
.index("my-index-000001")
);
{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 5,
"result": "deleted"
}Verify that a document exists.
For example, check to see if a document with the _id 0 exists:
HEAD my-index-000001/_doc/0
If the document exists, the API returns a status code of 200 - OK.
If the document doesn’t exist, the API returns 404 - Not Found.
Versioning support
You can use the version parameter to check 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.
A comma-separated list of data streams, indices, and aliases.
It supports wildcards (*).
A unique document identifier.
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If it is set to _local, the operation will prefer to be run on a local allocated shard when possible.
If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.
This can help with "jumping values" when hitting different shards in different refresh states.
A sample value can be something like the web session ID or the user name.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude from the response.
You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of source fields to include in the response.
If this parameter is specified, only these source fields are returned.
You can exclude fields from this subset using the _source_excludes query parameter.
If the _source parameter is false, this parameter is ignored.
A comma-separated list of stored fields to return as part of a hit.
If no fields are specified, no stored fields are included in the response.
If this field is specified, the _source parameter defaults to false.
Explicit version number for concurrency control. The specified version 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/_doc/0
resp = client.exists(
index="my-index-000001",
id="0",
)const response = await client.exists({
index: "my-index-000001",
id: 0,
});response = client.exists(
index: "my-index-000001",
id: "0"
)$resp = $client->exists([
"index" => "my-index-000001",
"id" => "0",
]);curl --head -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_doc/0"client.exists(e -> e
.id("0")
.index("my-index-000001")
);
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.
The documents to delete specified with Query DSL.
Slice the request manually using the provided slice ID and total number of slices.
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" : [ ]
}Change the number of requests per second for a particular delete 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 _delete_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1
resp = client.delete_by_query_rethrottle(
task_id="r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second="-1",
)const response = await client.deleteByQueryRethrottle({
task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second: "-1",
});response = client.delete_by_query_rethrottle(
task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
requests_per_second: "-1"
)$resp = $client->deleteByQueryRethrottle([
"task_id" => "r1A2WoRbTwKZ516z6NEs5A:36619",
"requests_per_second" => "-1",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_delete_by_query/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1"client.deleteByQueryRethrottle(d -> d
.requestsPerSecond(-1.0F)
.taskId("r1A2WoRbTwKZ516z6NEs5A:36619")
);
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"client.getSource(g -> g
.id("1")
.index("my-index-000001")
);
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"client.reindexRethrottle(r -> r
.requestsPerSecond(-1.0F)
.taskId("r1A2WoRbTwKZ516z6NEs5A:36619")
);
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.
Filter terms based on their tf-idf scores. This could be useful in order find out a good characteristic vector of a document. This feature works in a similar manner to the second phase of the More Like This Query.
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.
A list 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:
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.
A custom value that is used to route operations to a specific shard.
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.
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.
The script to run to update the document.
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(so -> so
.scriptString("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.
The documents to update using the Query DSL.
The script to run to update the document source or metadata when updating.
Slice the request manually using the provided slice ID and total number of slices.
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.
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"client.updateByQueryRethrottle(u -> u
.requestsPerSecond(-1.0F)
.taskId("r1A2WoRbTwKZ516z6NEs5A:36619")
);
Creates an enrich policy.
PUT /_enrich/policy/postal_policy
{
"geo_match": {
"indices": "postal_codes",
"match_field": "location",
"enrich_fields": [ "location", "postal_code" ]
}
}resp = client.enrich.put_policy(
name="postal_policy",
geo_match={
"indices": "postal_codes",
"match_field": "location",
"enrich_fields": [
"location",
"postal_code"
]
},
)const response = await client.enrich.putPolicy({
name: "postal_policy",
geo_match: {
indices: "postal_codes",
match_field: "location",
enrich_fields: ["location", "postal_code"],
},
});response = client.enrich.put_policy(
name: "postal_policy",
body: {
"geo_match": {
"indices": "postal_codes",
"match_field": "location",
"enrich_fields": [
"location",
"postal_code"
]
}
}
)$resp = $client->enrich()->putPolicy([
"name" => "postal_policy",
"body" => [
"geo_match" => [
"indices" => "postal_codes",
"match_field" => "location",
"enrich_fields" => array(
"location",
"postal_code",
),
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"geo_match":{"indices":"postal_codes","match_field":"location","enrich_fields":["location","postal_code"]}}' "$ELASTICSEARCH_URL/_enrich/policy/postal_policy"client.enrich().putPolicy(p -> p
.geoMatch(g -> g
.enrichFields(List.of("location","postal_code"))
.indices("postal_codes")
.matchField("location")
)
.name("postal_policy")
);
{
"geo_match": {
"indices": "postal_codes",
"match_field": "location",
"enrich_fields": [ "location", "postal_code" ]
}
}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"client.enrich().deletePolicy(d -> d
.name("my-policy")
);
Create the enrich index for an existing enrich policy.
PUT /_enrich/policy/my-policy/_execute?wait_for_completion=false
resp = client.enrich.execute_policy(
name="my-policy",
wait_for_completion=False,
)const response = await client.enrich.executePolicy({
name: "my-policy",
wait_for_completion: "false",
});response = client.enrich.execute_policy(
name: "my-policy",
wait_for_completion: "false"
)$resp = $client->enrich()->executePolicy([
"name" => "my-policy",
"wait_for_completion" => "false",
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy/_execute?wait_for_completion=false"client.enrich().executePolicy(e -> e
.name("my-policy")
.waitForCompletion(false)
);
Returns enrich coordinator statistics and information about enrich policies that are currently executing.
GET /_enrich/_stats
resp = client.enrich.stats()const response = await client.enrich.stats();response = client.enrich.stats$resp = $client->enrich()->stats();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/_stats"client.enrich().stats(s -> s);
Get the current status and available results for an async EQL search or a stored synchronous EQL search.
Period for which the search and its results are stored on the cluster. Defaults to the keep_alive value set by the search’s EQL search API request.
Values are -1 or 0.
Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.
Values are -1 or 0.
GET /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=2s
resp = client.eql.get(
id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
wait_for_completion_timeout="2s",
)const response = await client.eql.get({
id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
wait_for_completion_timeout: "2s",
});response = client.eql.get(
id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
wait_for_completion_timeout: "2s"
)$resp = $client->eql()->get([
"id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
"wait_for_completion_timeout" => "2s",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=2s"client.eql().get(g -> g
.id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
.waitForCompletionTimeout(w -> w
.offset(2)
)
);
GET /_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=
resp = client.eql.get_status(
id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
)const response = await client.eql.getStatus({
id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
});response = client.eql.get_status(
id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="
)$resp = $client->eql()->getStatus([
"id" => "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE="client.eql().getStatus(g -> g
.id("FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=")
);
{
"id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
"is_running" : true,
"is_partial" : true,
"start_time_in_millis" : 1611690235000,
"expiration_time_in_millis" : 1611690295000
}The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, and analyze data stored in Elasticsearch, and in the future in other runtimes.
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.
readIf true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards.
If false, the query will fail if there are any failures.
To override the default behavior, you can set the esql.query.allow_partial_results cluster setting to false.
The character to use between values within a CSV row. It is valid only for the CSV format.
Indicates whether columns that are entirely null will be removed from the columns and values portion of the results.
If true, the response will include an extra section under the name all_columns which has the name of all the columns.
A short version of the Accept header, e.g. json, yaml.
csv, tsv, and txt formats will return results in a tabular format, excluding other metadata fields from the response.
For async requests, nothing will be returned if the async query doesn't finish within the timeout.
The query ID and running status are available in the X-Elasticsearch-Async-Id and X-Elasticsearch-Async-Is-Running HTTP headers of the response, respectively.
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.
Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.
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.
The period to wait for the request to finish. By default, the request waits for 1 second for the query results. If the query completes during this period, results are returned Otherwise, a query ID is returned that can later be used to retrieve the results.
The period for which the query and its results are stored in the cluster.
The default period is five days.
When this period expires, the query and its results are deleted, even if the query is still ongoing.
If the keep_on_completion parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the wait_for_completion_timeout parameter, regardless of this value.
Indicates whether the query and its results are stored in the cluster.
If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.
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
}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"Get search results for an ES|QL (Elasticsearch query language) query.
A short version of the Accept header, e.g. json, yaml.
csv, tsv, and txt formats will return results in a tabular format, excluding other metadata fields from the response.
Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
The character to use between values within a CSV row. Only valid for the CSV format.
Should columns that are entirely null be removed from the columns and values portion of the results?
Defaults to false. If true then the response will include an extra section under the name all_columns which has the name of all columns.
If true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards.
If false, the query will fail if there are any failures.
To override the default behavior, you can set the esql.query.allow_partial_results cluster setting to false.
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.
Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.
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.
POST /_query
{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"include_ccs_metadata": true
}resp = client.esql.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 ",
include_ccs_metadata=True,
)const response = await client.esql.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 ",
include_ccs_metadata: true,
});response = client.esql.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 ",
"include_ccs_metadata": true
}
)$resp = $client->esql()->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 ",
"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 ","include_ccs_metadata":true}' "$ELASTICSEARCH_URL/_query"client.esql().query(q -> q
.includeCcsMetadata(true)
.query(" FROM library,remote-*:library | EVAL year = DATE_TRUNC(1 YEARS, release_date) | STATS MAX(page_count) BY year | SORT year | LIMIT 5 ")
);
{
"query": """
FROM library,remote-*:library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"include_ccs_metadata": true
}Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot.
You can use this API to determine which feature states to include when taking a snapshot.
By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.
A feature state includes one or more system indices necessary for a given feature to function. In order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.
The features listed by this API are a combination of built-in features and features defined by plugins. In order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.
GET _features
resp = client.features.get_features()const response = await client.features.getFeatures();response = client.features.get_features$resp = $client->features()->getFeatures();curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_features"client.features().getFeatures(g -> g);
{
"features": [
{
"name": "tasks",
"description": "Manages task results"
},
{
"name": "kibana",
"description": "Manages Kibana configuration and reports"
}
]
}Clear all of the state information stored in system indices by Elasticsearch features, including the security and machine learning indices.
WARNING: Intended for development and testing use only. Do not reset features on a production cluster.
Return a cluster to the same state as a new installation by resetting the feature state for all Elasticsearch features. This deletes all state information stored in system indices.
The response code is HTTP 200 if the state is successfully reset for all features. It is HTTP 500 if the reset operation failed for any feature.
Note that select features might provide a way to reset particular system indices. Using this API resets all features, both those that are built-in and implemented as plugins.
To list the features that will be affected, use the get features API.
IMPORTANT: The features installed on the node you submit this request to are the features that will be reset. Run on the master node if you have any doubts about which plugins are installed on individual nodes.
POST /_features/_reset
resp = client.features.reset_features()const response = await client.features.resetFeatures();response = client.features.reset_features$resp = $client->features()->resetFeatures();curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_features/_reset"client.features().resetFeatures(r -> r);
{
"features" : [
{
"feature_name" : "security",
"status" : "SUCCESS"
},
{
"feature_name" : "tasks",
"status" : "SUCCESS"
}
]
}Get the current global checkpoints for an index. This API is designed for internal use by the Fleet server project.
A boolean value which controls whether to wait (until the timeout) for the global checkpoints
to advance past the provided checkpoints.
A boolean value which controls whether to wait (until the timeout) for the target index to exist
and all primary shards be active. Can only be true when wait_for_advance is true.
A comma separated list of previous global checkpoints. When used in combination with wait_for_advance,
the API will only return once the global checkpoints advances past the checkpoints. Providing an empty list
will cause Elasticsearch to immediately return the current global checkpoints.
Period to wait for a global checkpoints to advance past checkpoints.
Values are -1 or 0.
curl \
--request GET 'http://api.example.com/{index}/_fleet/global_checkpoints' \
--header "Authorization: $API_KEY"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 search results and results collected by aggregations.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Defines the search definition using the Query DSL.
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.
Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.
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.
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. You can pass _source: true to return both source fields and stored fields in the search response.
Limits the search to a point in time (PIT). If you provide a PIT, you cannot specify an in the request path.
Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.
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":{"type":"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":{}},"lang":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"lang":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"search_after":[42.0],"size":10,"slice":{"field":"string","id":"string","max":42.0},"sort":"string","_source":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":{}},"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":{}},"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.
All methods and paths for this operation:
Extract and summarize information about the documents and terms in an Elasticsearch data stream or index.
The easiest way to understand the behavior of this API is to use the Graph UI to explore connections.
An initial request to the _explore API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph.
Subsequent requests enable you to spider out from one more vertices of interest.
You can exclude vertices that have already been returned.
Custom value used to route operations to a specific shard.
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.
Values are -1 or 0.
Specifies or more fields from which you want to extract terms that are associated with the specified vertices.
Direct the Graph API how to build the graph.
A seed query that identifies the documents of interest. Can be any valid Elasticsearch query.
Specifies one or more fields that contain the terms you want to include in the graph as vertices.
POST clicklogs/_graph/explore
{
"query": {
"match": {
"query.raw": "midi"
}
},
"vertices": [
{
"field": "product"
}
],
"connections": {
"vertices": [
{
"field": "query.raw"
}
]
}
}resp = client.graph.explore(
index="clicklogs",
query={
"match": {
"query.raw": "midi"
}
},
vertices=[
{
"field": "product"
}
],
connections={
"vertices": [
{
"field": "query.raw"
}
]
},
)const response = await client.graph.explore({
index: "clicklogs",
query: {
match: {
"query.raw": "midi",
},
},
vertices: [
{
field: "product",
},
],
connections: {
vertices: [
{
field: "query.raw",
},
],
},
});response = client.graph.explore(
index: "clicklogs",
body: {
"query": {
"match": {
"query.raw": "midi"
}
},
"vertices": [
{
"field": "product"
}
],
"connections": {
"vertices": [
{
"field": "query.raw"
}
]
}
}
)$resp = $client->graph()->explore([
"index" => "clicklogs",
"body" => [
"query" => [
"match" => [
"query.raw" => "midi",
],
],
"vertices" => array(
[
"field" => "product",
],
),
"connections" => [
"vertices" => array(
[
"field" => "query.raw",
],
),
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"match":{"query.raw":"midi"}},"vertices":[{"field":"product"}],"connections":{"vertices":[{"field":"query.raw"}]}}' "$ELASTICSEARCH_URL/clicklogs/_graph/explore"client.graph().explore(e -> e
.connections(c -> c
.vertices(v -> v
.field("query.raw")
)
)
.index("clicklogs")
.query(q -> q
.match(m -> m
.field("query.raw")
.query(FieldValue.of("midi"))
)
)
.vertices(v -> v
.field("product")
)
);
{
"query": {
"match": {
"query.raw": "midi"
}
},
"vertices": [
{
"field": "product"
}
],
"connections": {
"vertices": [
{
"field": "query.raw"
}
]
}
}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.
The template to be applied which includes mappings, settings, or aliases configuration.
Version number used to manage component templates externally. This number isn't automatically generated or incremented by Elasticsearch. To unset a version, replace the template without specifying a version.
Optional user metadata about the component template.
It may have any contents. This map is not automatically generated by Elasticsearch.
This information is stored in the cluster state, so keeping it short is preferable.
To unset _meta, replace the template without specifying this information.
Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.
PUT _component_template/template_1
{
"template": {
"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={
"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: {
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": {
"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" => [
"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":{"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": {
"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": {}
}
}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.
manageThe UUID of the index to import. Use the get dangling indices API to locate the UUID.
This parameter must be set to true to import a dangling index. Because Elasticsearch cannot know where the dangling index data came from or determine which shard copies are fresh and which are stale, it cannot guarantee that the imported data represents the latest state of the index when it was last in the cluster.
Specify timeout for connection to master
Values are -1 or 0.
Explicit operation timeout
Values are -1 or 0.
POST /_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true
resp = client.dangling_indices.import_dangling_index(
index_uuid="zmM4e0JtBkeUjiHD-MihPQ",
accept_data_loss=True,
)const response = await client.danglingIndices.importDanglingIndex({
index_uuid: "zmM4e0JtBkeUjiHD-MihPQ",
accept_data_loss: "true",
});response = client.dangling_indices.import_dangling_index(
index_uuid: "zmM4e0JtBkeUjiHD-MihPQ",
accept_data_loss: "true"
)$resp = $client->danglingIndices()->importDanglingIndex([
"index_uuid" => "zmM4e0JtBkeUjiHD-MihPQ",
"accept_data_loss" => "true",
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true"client.danglingIndices().importDanglingIndex(i -> i
.acceptDataLoss(true)
.indexUuid("zmM4e0JtBkeUjiHD-MihPQ")
);
{
"acknowledged": true
}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.
manageDELETE /_dangling/<index-uuid>?accept_data_loss=true
resp = client.dangling_indices.delete_dangling_index(
index_uuid="<index-uuid>",
accept_data_loss=True,
)const response = await client.danglingIndices.deleteDanglingIndex({
index_uuid: "<index-uuid>",
accept_data_loss: "true",
});response = client.dangling_indices.delete_dangling_index(
index_uuid: "<index-uuid>",
accept_data_loss: "true"
)$resp = $client->danglingIndices()->deleteDanglingIndex([
"index_uuid" => "<index-uuid>",
"accept_data_loss" => "true",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_dangling/<index-uuid>?accept_data_loss=true"client.danglingIndices().deleteDanglingIndex(d -> d
.acceptDataLoss(true)
.indexUuid("<index-uuid>")
);
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"client.indices().addBlock(a -> a
.block(IndicesBlockOptions.Write)
.index("my-index-000001")
);
{
"acknowledged" : true,
"shards_acknowledged" : true,
"indices" : [ {
"name" : "my-index-000001",
"blocked" : true
} ]
}All methods and paths for this operation:
Clone an existing index into a new index. Each original primary shard is cloned into a new primary shard in the new index.
IMPORTANT: Elasticsearch does not apply index templates to the resulting index. The API also does not copy index metadata from the original index. Index metadata includes aliases, index lifecycle management phase definitions, and cross-cluster replication (CCR) follower information. For example, if you clone a CCR follower index, the resulting clone will not be a follower index.
The clone API copies most index settings from the source index to the resulting index, with the exception of index.number_of_replicas and index.auto_expand_replicas.
To set the number of replicas in the resulting index, configure these settings in the clone request.
Cloning works as follows:
IMPORTANT: Indices can only be cloned if they meet the following requirements:
The current write index on a data stream cannot be cloned. In order to clone 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 cloned.
NOTE: Mappings cannot be specified in the _clone request. The mappings of the source index will be used for the target index.
Monitor the cloning process
The cloning process can be monitored with the cat recovery API or the cluster health API can be used to wait until all primary shards have been allocated by setting the wait_for_status parameter to yellow.
The _clone API returns as soon as the target index has been added to the cluster state, before any shards have been allocated.
At this point, all shards are in the state unassigned.
If, for any reason, the target index can't be allocated, its primary shard will remain unassigned until it can be allocated on that node.
Once the primary shard is allocated, it moves to state initializing, and the clone process begins. When the clone operation completes, the shard will become active. At that point, Elasticsearch will try to allocate any replicas and may decide to relocate the primary shard to another node.
Wait for active shards
Because the clone operation creates a new index to clone the shards to, the wait for active shards setting on index creation applies to the clone index action as well.
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_source_index/_clone/my_target_index
{
"settings": {
"index.number_of_shards": 5
},
"aliases": {
"my_search_indices": {}
}
}resp = client.indices.clone(
index="my_source_index",
target="my_target_index",
settings={
"index.number_of_shards": 5
},
aliases={
"my_search_indices": {}
},
)const response = await client.indices.clone({
index: "my_source_index",
target: "my_target_index",
settings: {
"index.number_of_shards": 5,
},
aliases: {
my_search_indices: {},
},
});response = client.indices.clone(
index: "my_source_index",
target: "my_target_index",
body: {
"settings": {
"index.number_of_shards": 5
},
"aliases": {
"my_search_indices": {}
}
}
)$resp = $client->indices()->clone([
"index" => "my_source_index",
"target" => "my_target_index",
"body" => [
"settings" => [
"index.number_of_shards" => 5,
],
"aliases" => [
"my_search_indices" => new ArrayObject([]),
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"index.number_of_shards":5},"aliases":{"my_search_indices":{}}}' "$ELASTICSEARCH_URL/my_source_index/_clone/my_target_index"client.indices().clone(c -> c
.aliases("my_search_indices", a -> a)
.index("my_source_index")
.settings("index.number_of_shards", JsonData.fromJson("5"))
.target("my_target_index")
);
{
"settings": {
"index.number_of_shards": 5
},
"aliases": {
"my_search_indices": {}
}
}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"client.indices().close(c -> c
.index("my-index-00001")
);
{
"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"client.indices().get(g -> g
.index("my-index-000001")
);
You can use the create index API to add a new index to an Elasticsearch cluster. When creating an index, you can specify the following:
Wait for active shards
By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out.
The index creation response will indicate what happened.
For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out.
Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful.
These values simply indicate whether the operation completed before the timeout.
If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon.
If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).
You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards.
Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.
create_index,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.
Aliases for the index.
Mapping for fields in the index. If specified, this mapping can include:
Configuration options for the index.
PUT /my-index-000001
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 2
}
}resp = client.indices.create(
index="my-index-000001",
settings={
"number_of_shards": 3,
"number_of_replicas": 2
},
)const response = await client.indices.create({
index: "my-index-000001",
settings: {
number_of_shards: 3,
number_of_replicas: 2,
},
});response = client.indices.create(
index: "my-index-000001",
body: {
"settings": {
"number_of_shards": 3,
"number_of_replicas": 2
}
}
)$resp = $client->indices()->create([
"index" => "my-index-000001",
"body" => [
"settings" => [
"number_of_shards" => 3,
"number_of_replicas" => 2,
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"number_of_shards":3,"number_of_replicas":2}}' "$ELASTICSEARCH_URL/my-index-000001"client.indices().create(c -> c
.index("my-index-000001")
.settings(s -> s
.numberOfShards("3")
.numberOfReplicas("2")
)
);
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 2
}
}{
"settings": {
"number_of_shards": 1
},
"mappings": {
"properties": {
"field1": { "type": "text" }
}
}
}{
"aliases": {
"alias_1": {},
"alias_2": {
"filter": {
"term": {
"user.id": "kimchy"
}
},
"routing": "shard-1"
}
}
}Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.
You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. You can then use the delete index API to delete the previous write index.
delete_indexComma-separated list of indices to delete.
You cannot specify index aliases.
By default, this parameter does not support wildcards (*) or _all.
To use wildcards or _all, set the action.destructive_requires_name cluster setting to false.
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.
DELETE /books
resp = client.indices.delete(
index="books",
)const response = await client.indices.delete({
index: "books",
});response = client.indices.delete(
index: "books"
)$resp = $client->indices()->delete([
"index" => "books",
]);curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/books"client.indices().delete(d -> d
.index("books")
);
Check if one or more indices, index aliases, or data streams exist.
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.
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.
HEAD my-data-stream
resp = client.indices.exists(
index="my-data-stream",
)const response = await client.indices.exists({
index: "my-data-stream",
});response = client.indices.exists(
index: "my-data-stream"
)$resp = $client->indices()->exists([
"index" => "my-data-stream",
]);curl --head -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-data-stream"client.indices().exists(e -> e
.index("my-data-stream")
);
Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.
If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
If true, returns settings in flat format.
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, returns all relevant default configurations for the index template.
GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream
resp = client.indices.get_index_template(
name="*",
filter_path="index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream",
)const response = await client.indices.getIndexTemplate({
name: "*",
filter_path:
"index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream",
});response = client.indices.get_index_template(
name: "*",
filter_path: "index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream"
)$resp = $client->indices()->getIndexTemplate([
"name" => "*",
"filter_path" => "index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream",
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream"All methods and paths for this operation:
Index templates define settings, mappings, and aliases that can be applied automatically to new indices.
Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. Index templates are applied during data stream or index creation. For data streams, these settings and mappings are applied when the stream's backing indices are created. Settings and mappings specified in a create index API request override any settings or mappings specified in an index template. Changes to index templates do not affect existing indices, including the existing backing indices of a data stream.
You can use C-style /* *\/ block comments in index templates.
You can include comments anywhere in the request body, except before the opening curly bracket.
Multiple matching templates
If multiple index templates match the name of a new index or data stream, the template with the highest priority is used.
Multiple templates with overlapping index patterns at the same priority are not allowed and an error will be thrown when attempting to create a template matching an existing index template at identical priorities.
Composing aliases, mappings, and settings
When multiple component templates are specified in the composed_of field for an index template, they are merged in the order specified, meaning that later component templates override earlier component templates.
Any mappings, settings, or aliases from the parent index template are merged in next.
Finally, any configuration on the index request itself is merged.
Mapping definitions are merged recursively, which means that later mapping components can introduce new field mappings and update the mapping configuration.
If a field mapping is already contained in an earlier component, its definition will be completely overwritten by the later one.
This recursive merging strategy applies not only to field mappings, but also root options like dynamic_templates and meta.
If an earlier component contains a dynamic_templates block, then by default new dynamic_templates entries are appended onto the end.
If an entry already exists with the same key, then it is overwritten by the new definition.
manage_index_templatesIf true, this request cannot replace or update existing index templates.
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.
User defined reason for creating/updating the index template
Name of the index template to create.
An ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence.
Template to be applied.
It may optionally include an aliases, mappings, or settings configuration.
If this object is included, the template is used to create data streams and their backing indices.
Supports an empty object.
Data streams require a matching index template with a data_stream object.
Priority to determine index template precedence when a new data stream or index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though it is of priority 0 (lowest priority). This number is not automatically generated by Elasticsearch.
Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch. External systems can use these version numbers to simplify template management. To unset a version, replace the template without specifying one.
Optional user metadata about the index template. It may have any contents. It is not automatically generated or used by Elasticsearch. This user-defined object is stored in the cluster state, so keeping it short is preferable To unset the metadata, replace the template without specifying it.
This setting overrides the value of the action.auto_create_index cluster setting.
If set to true in a template, then indices can be automatically created using that template even if auto-creation of indices is disabled via actions.auto_create_index.
If set to false, then indices or data streams matching the template must always be explicitly created, and may never be automatically created.
The configuration option ignore_missing_component_templates can be used when an index template references a component template that might not exist
Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.
PUT /_index_template/template_1
{
"index_patterns" : ["template*"],
"priority" : 1,
"template": {
"settings" : {
"number_of_shards" : 2
}
}
}resp = client.indices.put_index_template(
name="template_1",
index_patterns=[
"template*"
],
priority=1,
template={
"settings": {
"number_of_shards": 2
}
},
)const response = await client.indices.putIndexTemplate({
name: "template_1",
index_patterns: ["template*"],
priority: 1,
template: {
settings: {
number_of_shards: 2,
},
},
});response = client.indices.put_index_template(
name: "template_1",
body: {
"index_patterns": [
"template*"
],
"priority": 1,
"template": {
"settings": {
"number_of_shards": 2
}
}
}
)$resp = $client->indices()->putIndexTemplate([
"name" => "template_1",
"body" => [
"index_patterns" => array(
"template*",
),
"priority" => 1,
"template" => [
"settings" => [
"number_of_shards" => 2,
],
],
],
]);curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_patterns":["template*"],"priority":1,"template":{"settings":{"number_of_shards":2}}}' "$ELASTICSEARCH_URL/_index_template/template_1"client.indices().putIndexTemplate(p -> p
.indexPatterns("template*")
.name("template_1")
.priority(1L)
.template(t -> t
.settings(s -> s
.numberOfShards("2")
)
)
);
{
"index_patterns" : ["template*"],
"priority" : 1,
"template": {
"settings" : {
"number_of_shards" : 2
}
}
}{
"index_patterns": [
"template*"
],
"template": {
"settings": {
"number_of_shards": 1
},
"aliases": {
"alias1": {},
"alias2": {
"filter": {
"term": {
"user.id": "kimchy"
}
},
"routing": "shard-1"
},
"{index}-alias": {}
}
}
}