Get field data cache information
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.
Query parameters
-
bytes
string The unit used to display byte values.
Values are
b,kb,mb,gb,tb, orpb. -
fields
string | array[string] Comma-separated list of fields used to limit returned information.
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:ascor:descas a suffix to the column name.
curl \
--request GET 'http://api.example.com/_cat/fielddata' \
--header "Authorization: $API_KEY"[
{
"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"
}
]Get index information
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:
- shard count
- document count
- deleted document count
- primary store size
- total store size of all shards, including shard replicas
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.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*). To target all data streams and indices, omit this parameter or use*or_all.
Query parameters
-
bytes
string The unit used to display byte values.
Values are
b,kb,mb,gb,tb, orpb. -
expand_wildcards
string | array[string] 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 withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
health
string The health status used to limit returned indices. By default, the response includes indices of any health status.
Supported values include:
green(orGREEN): All shards are assigned.yellow(orYELLOW): 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(orRED): One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
Values are
green,GREEN,yellow,YELLOW,red, orRED. -
include_unloaded_segments
boolean If true, the response includes information from segments that are not loaded into memory.
-
pri
boolean If true, the response only includes information from primary shards.
-
time
string The unit used to display time values.
Values are
nanos,micros,ms,s,m,h, ord. -
master_timeout
string Period to wait for a connection to the master node.
-
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:ascor:descas a suffix to the column name.
curl \
--request GET 'http://api.example.com/_cat/indices/{index}' \
--header "Authorization: $API_KEY"[
{
"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"
}
]
Get the cluster health status
Added in 1.3.0
You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.
The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.
One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (
*) are supported. To target all data streams and indices in a cluster, omit this parameter or use _all or*.
Query parameters
-
expand_wildcards
string | array[string] Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
level
string Can be one of cluster, indices or shards. Controls the details level of the health information returned.
Values are
cluster,indices, orshards. -
local
boolean If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
-
master_timeout
string Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
wait_for_active_shards
number | string A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.
-
wait_for_events
string Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.
Values are
immediate,urgent,high,normal,low, orlanguid. -
wait_for_nodes
string | number The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.
-
wait_for_no_initializing_shards
boolean A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.
-
wait_for_no_relocating_shards
boolean A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.
-
wait_for_status
string One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.
Supported values include:
green(orGREEN): All shards are assigned.yellow(orYELLOW): 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(orRED): One or more primary shards are unassigned, so some data is unavailable. This can occur briefly during cluster startup as primary shards are assigned.
Values are
green,GREEN,yellow,YELLOW,red, orRED.
curl \
--request GET 'http://api.example.com/_cluster/health/{index}' \
--header "Authorization: $API_KEY"{
"cluster_name" : "testcluster",
"status" : "yellow",
"timed_out" : false,
"number_of_nodes" : 1,
"number_of_data_nodes" : 1,
"active_primary_shards" : 1,
"active_shards" : 1,
"relocating_shards" : 0,
"initializing_shards" : 0,
"unassigned_shards" : 1,
"delayed_unassigned_shards": 0,
"number_of_pending_tasks" : 0,
"number_of_in_flight_fetch": 0,
"task_max_waiting_in_queue_millis": 0,
"active_shards_percent_as_number": 50.0
}
Get cluster repositories metering
Technical preview
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.
Path parameters
-
node_id
string | array[string] Required Comma-separated list of node IDs or names used to limit returned information.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/_repositories_metering' \
--header "Authorization: $API_KEY"
Create a connector
Beta
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. Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. Self-managed connectors (Connector clients) are self-managed on your infrastructure.
Body
-
description
string -
index_name
string -
is_native
boolean -
language
string -
name
string -
service_type
string
curl \
--request POST 'http://api.example.com/_connector' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"description":"string","index_name":"string","is_native":true,"language":"string","name":"string","service_type":"string"}'
Activate the connector draft filter
Technical preview
Activates the valid draft filtering for a connector.
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_activate' \
--header "Authorization: $API_KEY"
Update the connector index name
Beta
Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
Body
Required
index_name
string | null
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_index_name' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"index_name\": \"data-from-my-google-drive\"\n}"'{
"index_name": "data-from-my-google-drive"
}{
"result": "updated"
}
Update the connector service type
Beta
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
Body
Required
-
service_type
string Required
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_service_type' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service_type\": \"sharepoint_online\"\n}"'{
"service_type": "sharepoint_online"
}{
"result": "updated"
}
Downsample an index
Technical preview
Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval.
For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index.
All documents within an hour interval are summarized and stored as a single document in the downsample index.
NOTE: Only indices in a time series data stream are supported.
Neither field nor document level security can be defined on the source index.
The source index must be read only (index.blocks.write: true).
Path parameters
-
index
string Required Name of the time series index to downsample.
-
target_index
string Required Name of the index to create.
Body
Required
-
fixed_interval
string Required A date histogram interval. Similar to
Durationwith additional units:w(week),M(month),q(quarter) andy(year)
curl \
--request POST 'http://api.example.com/{index}/_downsample/{target_index}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"fixed_interval\": \"1d\"\n}"'{
"fixed_interval": "1d"
}Get term vector information
Get information and statistics about terms in the fields of a particular document.
You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request.
You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body.
For example:
GET /my-index-000001/_termvectors/1?fields=message
Fields can be specified using wildcards, similar to the multi match query.
Term vectors are real-time by default, not near real-time.
This can be changed by setting realtime parameter to false.
You can request three types of values: term information, term statistics, and field statistics. By default, all term information and field statistics are returned for all fields but term statistics are excluded.
Term information
- term frequency in the field (always returned)
- term positions (
positions: true) - start and end offsets (
offsets: true) - term payloads (
payloads: true), as base64 encoded bytes
If the requested information wasn't stored in the index, it will be computed on the fly if possible. Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.
Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.
Behaviour
The term and field statistics are not accurate.
Deleted documents are not taken into account.
The information is only retrieved for the shard the requested document resides in.
The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context.
By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected.
Use routing only to hit a particular shard.
Query parameters
-
fields
string | array[string] A comma-separated list or wildcard expressions of fields to include in the statistics. It is used as the default list unless a specific field list is provided in the
completion_fieldsorfielddata_fieldsparameters. -
field_statistics
boolean If
true, the response includes:- The document count (how many documents contain this field).
- The sum of document frequencies (the sum of document frequencies for all terms in this field).
- The sum of total term frequencies (the sum of total term frequencies of each term in this field).
-
offsets
boolean If
true, the response includes term offsets. -
payloads
boolean If
true, the response includes term payloads. -
positions
boolean If
true, the response includes term positions. -
preference
string The node or shard the operation should be performed on. It is random by default.
-
realtime
boolean If true, the request is real-time as opposed to near-real-time.
-
routing
string A custom value that is used to route operations to a specific shard.
-
term_statistics
boolean If
true, the response includes:- The total term frequency (how often a term occurs in all documents).
- The document frequency (the number of documents containing the current term).
By default these values are not returned since term statistics can have a serious performance impact.
-
version
number If
true, returns the document version as part of a hit. -
version_type
string The version type.
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: Theexternal_gteversion 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, orforce.
Body
-
doc
object An artificial document (a document not present in the index) for which you want to retrieve term vectors.
-
filter
object -
per_field_analyzer
object Override the default per-field analyzer. This is useful in order to generate term vectors in any fashion, especially when using artificial documents. When providing an analyzer for a field that already stores term vectors, the term vectors will be regenerated.
-
fields
string | array[string] -
field_statistics
boolean If
true, the response includes:- The document count (how many documents contain this field).
- The sum of document frequencies (the sum of document frequencies for all terms in this field).
- The sum of total term frequencies (the sum of total term frequencies of each term in this field).
-
offsets
boolean If
true, the response includes term offsets. -
payloads
boolean If
true, the response includes term payloads. -
positions
boolean If
true, the response includes term positions. -
term_statistics
boolean If
true, the response includes:- The total term frequency (how often a term occurs in all documents).
- The document frequency (the number of documents containing the current term).
By default these values are not returned since term statistics can have a serious performance impact.
-
routing
string -
version
number -
version_type
string Values are
internal,external,external_gte, orforce.
curl \
--request GET 'http://api.example.com/{index}/_termvectors/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"fields\" : [\"text\"],\n \"offsets\" : true,\n \"payloads\" : true,\n \"positions\" : true,\n \"term_statistics\" : true,\n \"field_statistics\" : true\n}"'{
"fields" : ["text"],
"offsets" : true,
"payloads" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
},
"fields": ["fullname"],
"per_field_analyzer" : {
"fullname": "keyword"
}
}{
"doc": {
"plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
},
"term_statistics": true,
"field_statistics": true,
"positions": false,
"offsets": false,
"filter": {
"max_num_terms": 3,
"min_term_freq": 1,
"min_doc_freq": 1
}
}{
"fields" : ["text", "some_field_without_term_vectors"],
"offsets" : true,
"positions" : true,
"term_statistics" : true,
"field_statistics" : true
}{
"doc" : {
"fullname" : "John Doe",
"text" : "test test test"
}
}{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"found": true,
"took": 6,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 4,
"doc_count": 2,
"sum_ttf": 6
},
"terms": {
"test": {
"doc_freq": 2,
"ttf": 4,
"term_freq": 3,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 4,
"payload": "d29yZA=="
},
{
"position": 1,
"start_offset": 5,
"end_offset": 9,
"payload": "d29yZA=="
},
{
"position": 2,
"start_offset": 10,
"end_offset": 14,
"payload": "d29yZA=="
}
]
}
}
}
}
}{
"_index": "my-index-000001",
"_version": 0,
"found": true,
"took": 6,
"term_vectors": {
"fullname": {
"field_statistics": {
"sum_doc_freq": 2,
"doc_count": 4,
"sum_ttf": 4
},
"terms": {
"John Doe": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 8
}
]
}
}
}
}
}{
"_index": "imdb",
"_version": 0,
"found": true,
"term_vectors": {
"plot": {
"field_statistics": {
"sum_doc_freq": 3384269,
"doc_count": 176214,
"sum_ttf": 3753460
},
"terms": {
"armored": {
"doc_freq": 27,
"ttf": 27,
"term_freq": 1,
"score": 9.74725
},
"industrialist": {
"doc_freq": 88,
"ttf": 88,
"term_freq": 1,
"score": 8.590818
},
"stark": {
"doc_freq": 44,
"ttf": 47,
"term_freq": 1,
"score": 9.272792
}
}
}
}
}EQL
Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
Get mapping definitions
Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices.
This API is useful if you don't need a complete mapping or if an index mapping contains a large number of fields.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*). To target all data streams and indices, omit this parameter or use*or_all. -
fields
string | array[string] Required Comma-separated list or wildcard expression of fields used to limit returned information. Supports wildcards (
*).
Query parameters
-
allow_no_indices
boolean If
false, the request returns an error if any wildcard expression, index alias, or_allvalue targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards
string | array[string] Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden. Valid values are:all,open,closed,hidden,none.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 withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
include_defaults
boolean If
true, return all default settings in the response.
curl \
--request GET 'http://api.example.com/{index}/_mapping/field/{fields}' \
--header "Authorization: $API_KEY"{
"publications": {
"mappings": {
"title": {
"full_name": "title",
"mapping": {
"title": {
"type": "text"
}
}
}
}
}
}{
"publications": {
"mappings": {
"author.id": {
"full_name": "author.id",
"mapping": {
"id": {
"type": "text"
}
}
},
"abstract": {
"full_name": "abstract",
"mapping": {
"abstract": {
"type": "text"
}
}
}
}
}
}{
"publications": {
"mappings": {
"author.name": {
"full_name": "author.name",
"mapping": {
"name": {
"type": "text"
}
}
},
"abstract": {
"full_name": "abstract",
"mapping": {
"abstract": {
"type": "text"
}
}
},
"author.id": {
"full_name": "author.id",
"mapping": {
"id": {
"type": "text"
}
}
}
}
}
}Refresh an index
A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.
By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds.
You can change this default interval with the index.refresh_interval setting.
Refresh requests are synchronous and do not return a response until the refresh operation completes.
Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.
If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option.
This option ensures the indexing operation waits for a periodic refresh before running the search.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*). To target all data streams and indices, omit this parameter or use*or_all.
Query parameters
-
allow_no_indices
boolean If
false, the request returns an error if any wildcard expression, index alias, or_allvalue targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards
string | array[string] Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden. Valid values are:all,open,closed,hidden,none.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 withopen,closed, orboth.none: Wildcard expressions are not accepted.
curl \
--request POST 'http://api.example.com/{index}/_refresh' \
--header "Authorization: $API_KEY"
Reload search analyzers
Added in 7.3.0
Reload an index's search analyzers and their resources. For data streams, the API reloads search analyzers and resources for the stream's backing indices.
IMPORTANT: After reloading the search analyzers you should clear the request cache to make sure it doesn't contain responses derived from the previous versions of the analyzer.
You can use the reload search analyzers API to pick up changes to synonym files used in the synonym_graph or synonym token filter of a search analyzer.
To be eligible, the token filter must have an updateable flag of true and only be used in search analyzers.
NOTE: This API does not perform a reload for each shard of an index. Instead, it performs a reload for each node containing index shards. As a result, the total shard count returned by the API can differ from the number of index shards. Because reloading affects every node with an index shard, it is important to update the synonym file on every data node in the cluster--including nodes that don't contain a shard replica--before using this API. This ensures the synonym file is updated everywhere in the cluster in case shards are relocated in the future.
Path parameters
-
index
string | array[string] Required A comma-separated list of index names to reload analyzers for
Query parameters
-
allow_no_indices
boolean Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes
_allstring or when no indices have been specified) -
expand_wildcards
string | array[string] Whether to expand wildcard expression to concrete indices that are open, closed or both.
Supported values include:
all: Match any data stream or index, including hidden ones.open: Match open, non-hidden indices. Also matches any non-hidden data stream.closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.hidden: Match hidden data streams and hidden indices. Must be combined withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
resource
string Changed resource to reload analyzers from if applicable
curl \
--request GET 'http://api.example.com/{index}/_reload_search_analyzers' \
--header "Authorization: $API_KEY"Query parameters
-
master_timeout
string Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_ilm/policy' \
--header "Authorization: $API_KEY"{
"my_policy": {
"version": 1,
"modified_date": 82392349,
"policy": {
"phases": {
"warm": {
"min_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"min_age": "30d",
"actions": {
"delete": {
"delete_searchable_snapshot": true
}
}
}
}
},
"in_use_by" : {
"indices" : [],
"data_streams" : [],
"composable_templates" : []
}
}
}
Get an inference endpoint
Added in 8.11.0
Path parameters
-
inference_id
string Required The inference Id
curl \
--request GET 'http://api.example.com/_inference/{inference_id}' \
--header "Authorization: $API_KEY"
Create a Google Vertex AI inference endpoint
Added in 8.15.0
Create an inference endpoint to perform an inference task with the googlevertexai service.
When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running.
After creating the endpoint, wait for the model deployment to complete before using it.
To verify the deployment status, use the get trained model statistics API.
Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count".
Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.
Path parameters
-
task_type
string Required The type of the inference task that the model will perform.
Values are
rerankortext_embedding. -
googlevertexai_inference_id
string Required The unique identifier of the inference endpoint.
Body
-
chunking_settings
object -
service
string Required Value is
googlevertexai. -
service_settings
object Required -
task_settings
object
curl \
--request PUT 'http://api.example.com/_inference/{task_type}/{googlevertexai_inference_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service\": \"googlevertexai\",\n \"service_settings\": {\n \"service_account_json\": \"service-account-json\",\n \"model_id\": \"model-id\",\n \"location\": \"location\",\n \"project_id\": \"project-id\"\n }\n}"'{
"service": "googlevertexai",
"service_settings": {
"service_account_json": "service-account-json",
"model_id": "model-id",
"location": "location",
"project_id": "project-id"
}
}{
"service": "googlevertexai",
"service_settings": {
"service_account_json": "service-account-json",
"project_id": "project-id"
}
}Licensing
Licensing APIs enable you to manage your licenses.
Get anomaly detection job stats
Added in 5.5.0
Path parameters
-
job_id
string Required Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs, or a wildcard expression. If you do not specify one of these options, the API returns information for all anomaly detection jobs.
Query parameters
-
allow_no_match
boolean Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs that match.
- Contains the _all string or no identifiers and there are no matches.
- Contains wildcard expressions and there are only partial matches.
If
true, the API returns an emptyjobsarray when there are no matches and the subset of results when there are partial matches. Iffalse, the API returns a404status code when there are no matches or only partial matches.
curl \
--request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/_stats' \
--header "Authorization: $API_KEY"
Get anomaly records for an anomaly detection job
Added in 5.4.0
Records contain the detailed analytical results. They describe the anomalous activity that has been identified in the input data based on the detector configuration. There can be many anomaly records depending on the characteristics and size of the input data. In practice, there are often too many to be able to manually process them. The machine learning features therefore perform a sophisticated aggregation of the anomaly records into buckets. The number of record results depends on the number of anomalies found in each bucket, which relates to the number of time series being modeled and the number of detectors.
Path parameters
-
job_id
string Required Identifier for the anomaly detection job.
Query parameters
-
desc
boolean If true, the results are sorted in descending order.
-
end
string | number Returns records with timestamps earlier than this time. The default value means results are not limited to specific timestamps.
-
exclude_interim
boolean If
true, the output excludes interim results. -
from
number Skips the specified number of records.
-
record_score
number Returns records with anomaly scores greater or equal than this value.
-
size
number Specifies the maximum number of records to obtain.
-
sort
string Specifies the sort field for the requested records.
-
start
string | number Returns records with timestamps after this time. The default value means results are not limited to specific timestamps.
Body
-
desc
boolean Refer to the description for the
descquery parameter. end
string | number A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
-
exclude_interim
boolean Refer to the description for the
exclude_interimquery parameter. -
page
object -
record_score
number Refer to the description for the
record_scorequery parameter. -
sort
string Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
start
string | number A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
curl \
--request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/results/records' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"desc":true,"":"string","exclude_interim":true,"page":{"from":42.0,"size":42.0},"record_score":42.0,"sort":"string"}'
Update a filter
Added in 6.4.0
Updates the description of a filter, adds items, or removes items from the list.
Path parameters
-
filter_id
string Required A string that uniquely identifies a filter.
Body
Required
-
add_items
array[string] The items to add to the filter.
-
description
string A description for the filter.
-
remove_items
array[string] The items to remove from the filter.
curl \
--request POST 'http://api.example.com/_ml/filters/{filter_id}/_update' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"add_items":["string"],"description":"string","remove_items":["string"]}'
Create or update a query rule
Added in 8.15.0
Create or update a query rule within a query ruleset.
IMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.
Path parameters
-
ruleset_id
string Required The unique identifier of the query ruleset containing the rule to be created or updated.
-
rule_id
string Required The unique identifier of the query rule within the specified ruleset to be created or updated.
Body
Required
curl \
--request PUT 'http://api.example.com/_query_rules/{ruleset_id}/_rule/{rule_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"match_criteria\": {\n \"query_string\": \"puggles\"\n }\n}"'{
"match_criteria": {
"query_string": "puggles"
}
}
Search rolled-up data
Deprecated
Technical preview
The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given the original query.
The request body supports a subset of features from the regular search API. The following functionality is not available:
size: Because rollups work on pre-aggregated data, no search hits can be returned and so size must be set to zero or omitted entirely.
highlighter, suggestors, post_filter, profile, explain: These are similarly disallowed.
Searching both historical rollup and non-rollup data
The rollup search API has the capability to search across both "live" non-rollup data and the aggregated rollup data. This is done by simply adding the live indices to the URI. For example:
GET sensor-1,sensor_rollup/_rollup_search
{
"size": 0,
"aggregations": {
"max_temperature": {
"max": {
"field": "temperature"
}
}
}
}
The rollup search endpoint does two things when the search runs:
- The original request is sent to the non-rollup index unaltered.
- A rewritten version of the original request is sent to the rollup index.
When the two responses are received, the endpoint rewrites the rollup response and merges the two together. During the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.
Path parameters
-
index
string | array[string] Required A comma-separated list of data streams and indices used to limit the request. This parameter has the following rules:
- At least one data stream, index, or wildcard expression must be specified. This target can include a rollup or non-rollup index. For data streams, the stream's backing indices can only serve as non-rollup indices. Omitting the parameter or using
_allare not permitted. - Multiple non-rollup indices may be specified.
- Only one rollup index may be specified. If more than one are supplied, an exception occurs.
- Wildcard expressions (
*) may be used. If they match more than one rollup index, an exception occurs. However, you can use an expression to match multiple non-rollup indices or data streams.
- At least one data stream, index, or wildcard expression must be specified. This target can include a rollup or non-rollup index. For data streams, the stream's backing indices can only serve as non-rollup indices. Omitting the parameter or using
Query parameters
-
rest_total_hits_as_int
boolean Indicates whether hits.total should be rendered as an integer or an object in the rest search response
-
typed_keys
boolean Specify whether aggregation and suggester names should be prefixed by their respective types in the response
Body
Required
-
aggregations
object Specifies aggregations.
External documentation -
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
size
number Must be zero if set, as rollups work on pre-aggregated data.
curl \
--request POST 'http://api.example.com/{index}/_rollup_search' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"size\": 0,\n \"aggregations\": {\n \"max_temperature\": {\n \"max\": {\n \"field\": \"temperature\"\n }\n }\n }\n}"'{
"size": 0,
"aggregations": {
"max_temperature": {
"max": {
"field": "temperature"
}
}
}
}{
"took" : 102,
"timed_out" : false,
"terminated_early" : false,
"_shards" : {} ,
"hits" : {
"total" : {
"value": 0,
"relation": "eq"
},
"max_score" : 0.0,
"hits" : [ ]
},
"aggregations" : {
"max_temperature" : {
"value" : 202.0
}
}
}Count search results
Get the number of documents matching a query.
The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body.
The query is optional. When no query is provided, the API uses match_all to count all the documents.
The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.
The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count.
Query parameters
-
allow_no_indices
boolean If
false, the request returns an error if any wildcard expression, index alias, or_allvalue targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*returns an error if an index starts withfoobut no index starts withbar. -
analyzer
string The analyzer to use for the query string. This parameter can be used only when the
qquery string parameter is specified. -
analyze_wildcard
boolean If
true, wildcard and prefix queries are analyzed. This parameter can be used only when theqquery string parameter is specified. -
default_operator
string The default operator for query string query:
ANDorOR. This parameter can be used only when theqquery string parameter is specified.Values are
and,AND,or, orOR. -
df
string The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the
qquery string parameter is specified. -
expand_wildcards
string | array[string] The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as
open,hidden.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 withopen,closed, orboth.none: Wildcard expressions are not accepted.
-
ignore_throttled
boolean Deprecated If
true, concrete, expanded, or aliased indices are ignored when frozen. -
lenient
boolean If
true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theqquery string parameter is specified. -
min_score
number The minimum
_scorevalue that documents must have to be included in the result. -
preference
string The node or shard the operation should be performed on. By default, it is random.
-
routing
string A custom value used to route operations to a specific shard.
-
terminate_after
number The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
-
q
string The query in Lucene query string syntax. This parameter cannot be used with a request body.
Body
-
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
curl \
--request POST 'http://api.example.com/_count' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"term\" : { \"user.id\" : \"kimchy\" }\n }\n}"'{
"query" : {
"term" : { "user.id" : "kimchy" }
}
}{
"count": 1,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
}
}Explain a document match result
Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.
Query parameters
-
analyzer
string The analyzer to use for the query string. This parameter can be used only when the
qquery string parameter is specified. -
analyze_wildcard
boolean If
true, wildcard and prefix queries are analyzed. This parameter can be used only when theqquery string parameter is specified. -
default_operator
string The default operator for query string query:
ANDorOR. This parameter can be used only when theqquery string parameter is specified.Values are
and,AND,or, orOR. -
df
string The field to use as default where no field prefix is given in the query string. This parameter can be used only when the
qquery string parameter is specified. -
lenient
boolean If
true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theqquery string parameter is specified. -
preference
string The node or shard the operation should be performed on. It is random by default.
-
routing
string A custom value used to route operations to a specific shard.
-
_source
boolean | string | array[string] Trueorfalseto return the_sourcefield or not or a list of fields to return. -
_source_excludes
string | array[string] A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in
_source_includesquery parameter. If the_sourceparameter isfalse, this parameter is ignored. -
_source_includes
string | array[string] A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the
_source_excludesquery parameter. If the_sourceparameter isfalse, this parameter is ignored. -
stored_fields
string | array[string] A comma-separated list of stored fields to return in the response.
-
q
string The query in the Lucene query string syntax.
Body
-
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
curl \
--request GET 'http://api.example.com/{index}/_explain/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"match\" : { \"message\" : \"elasticsearch\" }\n }\n}"'{
"query" : {
"match" : { "message" : "elasticsearch" }
}
}{
"_index":"my-index-000001",
"_id":"0",
"matched":true,
"explanation":{
"value":1.6943598,
"description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
"details":[
{
"value":1.6943598,
"description":"score(freq=1.0), computed as boost * idf * tf from:",
"details":[
{
"value":2.2,
"description":"boost",
"details":[]
},
{
"value":1.3862944,
"description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
"details":[
{
"value":1,
"description":"n, number of documents containing term",
"details":[]
},
{
"value":5,
"description":"N, total number of documents with field",
"details":[]
}
]
},
{
"value":0.5555556,
"description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
"details":[
{
"value":1.0,
"description":"freq, occurrences of term within document",
"details":[]
},
{
"value":1.2,
"description":"k1, term saturation parameter",
"details":[]
},
{
"value":0.75,
"description":"b, length normalization parameter",
"details":[]
},
{
"value":3.0,
"description":"dl, length of field",
"details":[]
},
{
"value":5.4,
"description":"avgdl, average length of field",
"details":[]
}
]
}
]
}
]
}
}Explain a document match result
Get information about why a specific document matches, or doesn't match, a query. It computes a score explanation for a query and a specific document.
Query parameters
-
analyzer
string The analyzer to use for the query string. This parameter can be used only when the
qquery string parameter is specified. -
analyze_wildcard
boolean If
true, wildcard and prefix queries are analyzed. This parameter can be used only when theqquery string parameter is specified. -
default_operator
string The default operator for query string query:
ANDorOR. This parameter can be used only when theqquery string parameter is specified.Values are
and,AND,or, orOR. -
df
string The field to use as default where no field prefix is given in the query string. This parameter can be used only when the
qquery string parameter is specified. -
lenient
boolean If
true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when theqquery string parameter is specified. -
preference
string The node or shard the operation should be performed on. It is random by default.
-
routing
string A custom value used to route operations to a specific shard.
-
_source
boolean | string | array[string] Trueorfalseto return the_sourcefield or not or a list of fields to return. -
_source_excludes
string | array[string] A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in
_source_includesquery parameter. If the_sourceparameter isfalse, this parameter is ignored. -
_source_includes
string | array[string] A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the
_source_excludesquery parameter. If the_sourceparameter isfalse, this parameter is ignored. -
stored_fields
string | array[string] A comma-separated list of stored fields to return in the response.
-
q
string The query in the Lucene query string syntax.
Body
-
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
curl \
--request POST 'http://api.example.com/{index}/_explain/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"match\" : { \"message\" : \"elasticsearch\" }\n }\n}"'{
"query" : {
"match" : { "message" : "elasticsearch" }
}
}{
"_index":"my-index-000001",
"_id":"0",
"matched":true,
"explanation":{
"value":1.6943598,
"description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
"details":[
{
"value":1.6943598,
"description":"score(freq=1.0), computed as boost * idf * tf from:",
"details":[
{
"value":2.2,
"description":"boost",
"details":[]
},
{
"value":1.3862944,
"description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
"details":[
{
"value":1,
"description":"n, number of documents containing term",
"details":[]
},
{
"value":5,
"description":"N, total number of documents with field",
"details":[]
}
]
},
{
"value":0.5555556,
"description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
"details":[
{
"value":1.0,
"description":"freq, occurrences of term within document",
"details":[]
},
{
"value":1.2,
"description":"k1, term saturation parameter",
"details":[]
},
{
"value":0.75,
"description":"b, length normalization parameter",
"details":[]
},
{
"value":3.0,
"description":"dl, length of field",
"details":[]
},
{
"value":5.4,
"description":"avgdl, average length of field",
"details":[]
}
]
}
]
}
]
}
}
Search a vector tile
Added in 7.15.0
Search a vector tile for geospatial values. Before using this API, you should be familiar with the Mapbox vector tile specification. The API returns results as a binary mapbox vector tile.
Internally, Elasticsearch translates a vector tile search API request into a search containing:
- A
geo_bounding_boxquery on the<field>. The query uses the<zoom>/<x>/<y>tile as a bounding box. - A
geotile_gridorgeohex_gridaggregation on the<field>. Thegrid_aggparameter determines the aggregation type. The aggregation uses the<zoom>/<x>/<y>tile as a bounding box. - Optionally, a
geo_boundsaggregation on the<field>. The search only includes this aggregation if theexact_boundsparameter istrue. - If the optional parameter
with_labelsistrue, the internal search will include a dynamic runtime field that calls thegetLabelPositionfunction of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.
For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search
GET my-index/_search
{
"size": 10000,
"query": {
"geo_bounding_box": {
"my-geo-field": {
"top_left": {
"lat": -40.979898069620134,
"lon": -45
},
"bottom_right": {
"lat": -66.51326044311186,
"lon": 0
}
}
}
},
"aggregations": {
"grid": {
"geotile_grid": {
"field": "my-geo-field",
"precision": 11,
"size": 65536,
"bounds": {
"top_left": {
"lat": -40.979898069620134,
"lon": -45
},
"bottom_right": {
"lat": -66.51326044311186,
"lon": 0
}
}
}
},
"bounds": {
"geo_bounds": {
"field": "my-geo-field",
"wrap_longitude": false
}
}
}
}
The API returns results as a binary Mapbox vector tile. Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:
- A
hitslayer containing a feature for each<field>value matching thegeo_bounding_boxquery. - An
aggslayer containing a feature for each cell of thegeotile_gridorgeohex_grid. The layer only contains features for cells with matching data. - A meta layer containing:
- A feature containing a bounding box. By default, this is the bounding box of the tile.
- Value ranges for any sub-aggregations on the
geotile_gridorgeohex_grid. - Metadata for the search.
The API only returns features that can display at its zoom level. For example, if a polygon feature has no area at its zoom level, the API omits it. The API returns errors as UTF-8 encoded JSON.
IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. If you specify both parameters, the query parameter takes precedence.
Grid precision for geotile
For a grid_agg of geotile, you can use cells in the aggs layer as tiles for lower zoom levels.
grid_precision represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision.
For example, if <zoom> is 7 and grid_precision is 8, then the geotile_grid aggregation will use a precision of 15.
The maximum final precision is 29.
The grid_precision also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision).
For example, a value of 8 divides the tile into a grid of 256 x 256 cells.
The aggs layer only contains features for cells with matching data.
Grid precision for geohex
For a grid_agg of geohex, Elasticsearch uses <zoom> and grid_precision to calculate a final precision as follows: <zoom> + grid_precision.
This precision determines the H3 resolution of the hexagonal cells produced by the geohex aggregation.
The following table maps the H3 resolution for each precision.
For example, if <zoom> is 3 and grid_precision is 3, the precision is 6.
At a precision of 6, hexagonal cells have an H3 resolution of 2.
If <zoom> is 3 and grid_precision is 4, the precision is 7.
At a precision of 7, hexagonal cells have an H3 resolution of 3.
| Precision | Unique tile bins | H3 resolution | Unique hex bins | Ratio |
|---|---|---|---|---|
| 1 | 4 | 0 | 122 | 30.5 |
| 2 | 16 | 0 | 122 | 7.625 |
| 3 | 64 | 1 | 842 | 13.15625 |
| 4 | 256 | 1 | 842 | 3.2890625 |
| 5 | 1024 | 2 | 5882 | 5.744140625 |
| 6 | 4096 | 2 | 5882 | 1.436035156 |
| 7 | 16384 | 3 | 41162 | 2.512329102 |
| 8 | 65536 | 3 | 41162 | 0.6280822754 |
| 9 | 262144 | 4 | 288122 | 1.099098206 |
| 10 | 1048576 | 4 | 288122 | 0.2747745514 |
| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |
| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |
| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |
| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |
| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |
| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |
| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |
| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |
| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |
| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |
| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |
| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |
| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |
| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |
| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |
| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |
| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |
| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |
| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |
Hexagonal cells don't align perfectly on a vector tile. Some cells may intersect more than one vector tile. To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, or aliases to search
-
field
string Required Field containing geospatial data to return
-
zoom
number Required Zoom level for the vector tile to search
-
x
number Required X coordinate for the vector tile to search
-
y
number Required Y coordinate for the vector tile to search
Query parameters
-
exact_bounds
boolean If
false, the meta layer's feature is the bounding box of the tile. If true, the meta layer's feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the // tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile. -
extent
number The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
grid_agg
string Aggregation used to create a grid for
field.Values are
geotileorgeohex. -
grid_precision
number Additional zoom levels available through the aggs layer. For example, if is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer.
-
grid_type
string Determines the geometry type for features in the aggs layer. In the aggs layer, each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon of the cells bounding box. If 'point' each feature is a Point that is the centroid of the cell.
Values are
grid,point, orcentroid. -
size
number Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
-
with_labels
boolean If
true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.PointandMultiPointfeatures will have one of the points selected.PolygonandMultiPolygonfeatures will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.LineStringfeatures will likewise provide a roughly central point selected from the triangle-tree.- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag
_mvt_label_position.
Body
-
aggs
object Sub-aggregations for the geotile_grid.
It supports the following aggregation types:
avgboxplotcardinalityextended statsmaxmedian absolute deviationminpercentilepercentile-rankstatssumvalue count
The aggregation names can't start with
_mvt_. The_mvt_prefix is reserved for internal aggregations. -
buffer
number The size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile.
-
exact_bounds
boolean If
false, the meta layer's feature is the bounding box of the tile. Iftrue, the meta layer's feature is a bounding box resulting from ageo_boundsaggregation. The aggregation runs on values that intersect the<zoom>/<x>/<y>tile withwrap_longitudeset tofalse. The resulting bounding box may be larger than the vector tile. -
extent
number The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
fields
string | array[string] -
grid_agg
string Values are
geotileorgeohex. -
grid_precision
number Additional zoom levels available through the aggs layer. For example, if
<zoom>is7andgrid_precisionis8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer. -
grid_type
string Values are
grid,point, orcentroid. -
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
runtime_mappings
object -
size
number The maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
-
track_total_hits
boolean | number 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.
-
with_labels
boolean If
true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.PointandMultiPointfeatures will have one of the points selected.PolygonandMultiPolygonfeatures will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.LineStringfeatures will likewise provide a roughly central point selected from the triangle-tree.- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag
_mvt_label_position.
curl \
--request POST 'http://api.example.com/{index}/_mvt/{field}/{zoom}/{x}/{y}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"grid_agg\": \"geotile\",\n \"grid_precision\": 2,\n \"fields\": [\n \"name\",\n \"price\"\n ],\n \"query\": {\n \"term\": {\n \"included\": true\n }\n },\n \"aggs\": {\n \"min_price\": {\n \"min\": {\n \"field\": \"price\"\n }\n },\n \"max_price\": {\n \"max\": {\n \"field\": \"price\"\n }\n },\n \"avg_price\": {\n \"avg\": {\n \"field\": \"price\"\n }\n }\n }\n}"'{
"grid_agg": "geotile",
"grid_precision": 2,
"fields": [
"name",
"price"
],
"query": {
"term": {
"included": true
}
},
"aggs": {
"min_price": {
"min": {
"field": "price"
}
},
"max_price": {
"max": {
"field": "price"
}
},
"avg_price": {
"avg": {
"field": "price"
}
}
}
}{
"hits": {
"extent": 4096,
"version": 2,
"features": [
{
"geometry": {
"type": "Point",
"coordinates": [
3208,
3864
]
},
"properties": {
"_id": "1",
"_index": "museums",
"name": "NEMO Science Museum",
"price": 1750
},
"type": 1
},
{
"geometry": {
"type": "Point",
"coordinates": [
3429,
3496
]
},
"properties": {
"_id": "3",
"_index": "museums",
"name": "Nederlands Scheepvaartmuseum",
"price": 1650
},
"type": 1
},
{
"geometry": {
"type": "Point",
"coordinates": [
3429,
3496
]
},
"properties": {
"_id": "4",
"_index": "museums",
"name": "Amsterdam Centre for Architecture",
"price": 0
},
"type": 1
}
]
},
"aggs": {
"extent": 4096,
"version": 2,
"features": [
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
3072,
3072
],
[
4096,
3072
],
[
4096,
4096
],
[
3072,
4096
],
[
3072,
3072
]
]
]
},
"properties": {
"_count": 3,
"max_price.value": 1750.0,
"min_price.value": 0.0,
"avg_price.value": 1133.3333333333333
},
"type": 3
}
]
},
"meta": {
"extent": 4096,
"version": 2,
"features": [
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
0,
0
],
[
4096,
0
],
[
4096,
4096
],
[
0,
4096
],
[
0,
0
]
]
]
},
"properties": {
"_shards.failed": 0,
"_shards.skipped": 0,
"_shards.successful": 1,
"_shards.total": 1,
"aggregations._count.avg": 3.0,
"aggregations._count.count": 1,
"aggregations._count.max": 3.0,
"aggregations._count.min": 3.0,
"aggregations._count.sum": 3.0,
"aggregations.avg_price.avg": 1133.3333333333333,
"aggregations.avg_price.count": 1,
"aggregations.avg_price.max": 1133.3333333333333,
"aggregations.avg_price.min": 1133.3333333333333,
"aggregations.avg_price.sum": 1133.3333333333333,
"aggregations.max_price.avg": 1750.0,
"aggregations.max_price.count": 1,
"aggregations.max_price.max": 1750.0,
"aggregations.max_price.min": 1750.0,
"aggregations.max_price.sum": 1750.0,
"aggregations.min_price.avg": 0.0,
"aggregations.min_price.count": 1,
"aggregations.min_price.max": 0.0,
"aggregations.min_price.min": 0.0,
"aggregations.min_price.sum": 0.0,
"hits.max_score": 0.0,
"hits.total.relation": "eq",
"hits.total.value": 3,
"timed_out": false,
"took": 2
},
"type": 3
}
]
}
}
Render a search application query
Technical preview
Generate an Elasticsearch query using the specified query parameters and the search template associated with the search application or a default template if none is specified.
If a parameter used in the search template is not specified in params, the parameter's default value will be used.
The API returns the specific Elasticsearch query that would be generated and run by calling the search application search API.
You must have read privileges on the backing alias of the search application.
Path parameters
-
name
string Required The name of the search application to render teh query for.
curl \
--request POST 'http://api.example.com/_application/search_application/{name}/_render_query' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"params\": {\n \"query_string\": \"my first query\",\n \"text_fields\": [\n {\n \"name\": \"title\",\n \"boost\": 5\n },\n {\n \"name\": \"description\",\n \"boost\": 1\n }\n ]\n }\n}"'{
"params": {
"query_string": "my first query",
"text_fields": [
{
"name": "title",
"boost": 5
},
{
"name": "description",
"boost": 1
}
]
}
}{
"from": 0,
"size": 10,
"query": {
"multi_match": {
"query": "my first query",
"fields": [
"description^1.0",
"title^5.0"
]
}
},
"explain": false
}
Restore a snapshot
Added in 0.0.0
Restore a snapshot of a cluster or data streams and indices.
You can restore a snapshot only to a running cluster with an elected master node. The snapshot repository must be registered and available to the cluster. The snapshot and cluster versions must be compatible.
To restore a snapshot, the cluster's global metadata must be writable. Ensure there are't any cluster blocks that prevent writes. The restore operation ignores index blocks.
Before you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API:
GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream
If no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices.
If your snapshot contains data from App Search or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot.
Path parameters
-
repository
string Required The name of the repository to restore a snapshot from.
-
snapshot
string Required The name of the snapshot to restore.
Query parameters
-
master_timeout
string The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1. -
wait_for_completion
boolean If
true, the request returns a response when the restore operation completes. The operation is complete when it finishes all attempts to recover primary shards for restored indices. This applies even if one or more of the recovery attempts fail.If
false, the request returns a response when the restore operation initializes.
Body
-
feature_states
array[string] The feature states to restore. If
include_global_stateistrue, the request restores all feature states in the snapshot by default. Ifinclude_global_stateisfalse, the request restores no feature states by default. Note that specifying an empty array will result in the default behavior. To restore no feature states, regardless of theinclude_global_statevalue, specify an array containing only the valuenone(["none"]). -
ignore_index_settings
array[string] The index settings to not restore from the snapshot. You can't use this option to ignore
index.number_of_shards.For data streams, this option applies only to restored backing indices. New backing indices are configured using the data stream's matching index template.
-
include_aliases
boolean If
true, the request restores aliases for any restored data streams and indices. Iffalse, the request doesn’t restore aliases. -
include_global_state
boolean If
true, restore the cluster state. The cluster state includes:- Persistent cluster settings
- Index templates
- Legacy index templates
- Ingest pipelines
- Index lifecycle management (ILM) policies
- Stored scripts
- For snapshots taken after 7.12.0, feature states
If
include_global_stateistrue, the restore operation merges the legacy index templates in your cluster with the templates contained in the snapshot, replacing any existing ones whose name matches one in the snapshot. It completely removes all persistent settings, non-legacy index templates, ingest pipelines, and ILM lifecycle policies that exist in your cluster and replaces them with the corresponding items from the snapshot.Use the
feature_statesparameter to configure how feature states are restored.If
include_global_stateistrueand a snapshot was created without a global state then the restore request will fail. -
index_settings
object -
indices
string | array[string] -
partial
boolean If
false, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.If true, it allows restoring a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty.
-
rename_pattern
string A rename pattern to apply to restored data streams and indices. Data streams and indices matching the rename pattern will be renamed according to
rename_replacement.The rename pattern is applied as defined by the regular expression that supports referencing the original text, according to the
appendReplacementlogic.External documentation -
rename_replacement
string The rename replacement string that is used with the
rename_pattern.
curl \
--request POST 'http://api.example.com/_snapshot/{repository}/{snapshot}/_restore' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"indices\": \"index_1,index_2\",\n \"ignore_unavailable\": true,\n \"include_global_state\": false,\n \"rename_pattern\": \"index_(.+)\",\n \"rename_replacement\": \"restored_index_$1\",\n \"include_aliases\": false\n}"'{
"indices": "index_1,index_2",
"ignore_unavailable": true,
"include_global_state": false,
"rename_pattern": "index_(.+)",
"rename_replacement": "restored_index_$1",
"include_aliases": false
}{
"indices": "index_1"
}
Get the snapshot lifecycle management status
Added in 7.6.0
Query parameters
-
master_timeout
string The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1. -
timeout
string The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1.
curl \
--request GET 'http://api.example.com/_slm/status' \
--header "Authorization: $API_KEY"{
"operation_mode": "RUNNING"
}