Delete a calendar | Elasticsearch API documentation

Get behavioral analytics collections Deprecated Technical preview; Added in 8.8.0

GET /_application/analytics/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_application/analytics

GET /_application/analytics/{name}

Path parameters

name array[string] Required

A list of analytics collections to limit the returned information

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  event_data_stream object Required
  
  Hide event_data_stream attribute Show event_data_stream attribute object
  
  name string Required

GET /_application/analytics/{name}

GET _application/analytics/my*

resp = client.search_application.get_behavioral_analytics(
    name="my*",
)

const response = await client.searchApplication.getBehavioralAnalytics({
  name: "my*",
});

response = client.search_application.get_behavioral_analytics(
  name: "my*"
)

$resp = $client->searchApplication()->getBehavioralAnalytics([
    "name" => "my*",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my*"

client.searchApplication().getBehavioralAnalytics(g -> g
    .name("my*")
);

Response examples (200)

A successful response from `GET _application/analytics/my*`

{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}

Create a behavioral analytics collection Deprecated Technical preview; Added in 8.8.0

PUT /_application/analytics/{name}

Api key auth Basic auth Bearer auth

Path parameters

name string Required

The name of the analytics collection to be created or updated.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- name string Required

PUT /_application/analytics/{name}

PUT _application/analytics/my_analytics_collection

resp = client.search_application.put_behavioral_analytics(
    name="my_analytics_collection",
)

const response = await client.searchApplication.putBehavioralAnalytics({
  name: "my_analytics_collection",
});

response = client.search_application.put_behavioral_analytics(
  name: "my_analytics_collection"
)

$resp = $client->searchApplication()->putBehavioralAnalytics([
    "name" => "my_analytics_collection",
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection"

client.searchApplication().putBehavioralAnalytics(p -> p
    .name("my_analytics_collection")
);

Get shard allocation information Generally available

GET /_cat/allocation/{node_id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/allocation

GET /_cat/allocation/{node_id}

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.

Required authorization

Cluster privileges: monitor

Path parameters

node_id string | array[string]

A comma-separated list of node identifiers or names used to limit the returned information.

Query parameters

bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
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 :asc or :desc as a suffix to the column name.
local boolean

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.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- shards string
  
  Number of primary and replica shards assigned to the node.
- shards.undesired string | null
  
  Amount of shards that are scheduled to be moved elsewhere in the cluster or -1 other than desired balance allocator is used
  
  One of:
  string-1 string string-2 string | null
- write_load.forecast number | string | null
  
  Sum of index write load forecasts
  
  One of:
  number-1 number string-2 string string-2 string | null
- disk.indices.forecast number | string | null
  
  Sum of shard size forecasts
  
  One of:
  number-1 number string-2 string string-2 string | null
- disk.indices number | string | null
  
  Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards. IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.
  
  One of:
  number-1 number string-2 string string-2 string | null
- disk.used number | string | null
  
  Total disk space in use. Elasticsearch retrieves this metric from the node’s operating system (OS). The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node. Unlike disk.indices, this metric does not double-count disk space for hard-linked files.
  
  One of:
  number-1 number string-2 string string-2 string | null
- disk.avail number | string | null
  
  Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s operating system. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
  
  One of:
  number-1 number string-2 string string-2 string | null
- disk.total number | string | null
  
  Total disk space for the node, including in-use and available space.
  
  One of:
  number-1 number string-2 string string-2 string | null
- disk.percent string | number | null
  
  Total percentage of disk space in use. Calculated as disk.used / disk.total.
  
  One of:
  string-1 string number-2 number string-2 string | null
- host string | null
  
  Network host for the node. Set using the network.host setting.
  
  One of:
  Host string string-2 string | null
- ip string | null
  
  IP address and port for the node.
  
  One of:
  Ip string string-2 string | null
- node string
  
  Name for the node. Set using the node.name setting.
- node.role string | null
  
  Node roles
  
  One of:
  string-1 string string-2 string | null

GET /_cat/allocation/{node_id}

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();

Response examples (200)

A successful response from `GET /_cat/allocation?v=true&format=json`. It shows a single shard is allocated to the one node available.

[
  {
    "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"
  }
]

Get component templates Generally available; Added in 5.1.0

GET /_cat/component_templates/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/component_templates

GET /_cat/component_templates/{name}

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.

Required authorization

Cluster privileges: monitor

Path parameters

name string Required

The name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.

Query parameters

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 :asc or :desc as a suffix to the column name.
local boolean

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.
master_timeout string

The period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string Required
- version string | null Required
  
  One of:
  string-1 string string-2 string | null
- alias_count string Required
- mapping_count string Required
- settings_count string Required
- metadata_count string Required
- included_in string Required

GET /_cat/component_templates/{name}

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();

Response examples (200)

A successful response from `GET _cat/component_templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "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]"
  }
]

Get the cluster health status Generally available

GET /_cat/health

Api key auth Basic auth Bearer auth

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.

Required authorization

Cluster privileges: monitor

Query parameters

time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.
ts boolean

If true, returns HH:MM:SS and Unix epoch timestamps.
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 :asc or :desc as a suffix to the column name.

Responses

200 application/json
Hide response attributes Show response attributes object
- epoch number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  UnitSeconds number string-2 string
  
  Time unit for seconds
- timestamp string
  
  Time of day, expressed as HH:MM:SS
- cluster string
  
  cluster name
- status string
  
  health status
- node.total string
  
  total number of nodes
- node.data string
  
  number of nodes that can store data
- shards string
  
  total number of shards
- pri string
  
  number of primary shards
- relo string
  
  number of relocating nodes
- init string
  
  number of initializing nodes
- unassign.pri string
  
  number of unassigned primary shards
- unassign string
  
  number of unassigned shards
- pending_tasks string
  
  number of pending tasks
- max_task_wait_time string
  
  wait time of longest task pending
- active_shards_percent string
  
  active number of shards in percent

GET /_cat/health

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();

Response examples (200)

A successful response from `GET /_cat/health?v=true&format=json`. By default, it returns `HH:MM:SS` and Unix epoch timestamps.

[
  {
    "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%"
  }
]

Get CAT help Generally available

GET /_cat

Api key auth Basic auth Bearer auth

Get help for the CAT APIs.

Responses

200 application/json

GET /_cat

curl \
 --request GET 'http://api.example.com/_cat' \
 --header "Authorization: $API_KEY"

Get index information Generally available

GET /_cat/indices/{index}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/indices

GET /_cat/indices/{index}

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.

Required authorization

Index privileges: monitor
Cluster privileges: monitor

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, or pb.
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 with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
health string
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.
- unknown
- unavailable
Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
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, or d.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.
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 :asc or :desc as a suffix to the column name.

Responses

200 application/json
Hide response attributes Show response attributes object
- health string
  
  current health status
- status string
  
  open/close status
- index string
  
  index name
- uuid string
  
  index uuid
- pri string
  
  number of primary shards
- rep string
  
  number of replica shards
- docs.count string | null
  
  available docs
  
  One of:
  string-1 string string-2 string | null
- docs.deleted string | null
  
  deleted docs
  
  One of:
  string-1 string string-2 string | null
- creation.date string
  
  index creation date (millisecond value)
- creation.date.string string
  
  index creation date (as string)
- store.size string | null
  
  store size of primaries & replicas
  
  One of:
  string-1 string string-2 string | null
- pri.store.size string | null
  
  store size of primaries
  
  One of:
  string-1 string string-2 string | null
- dataset.size string | null
  
  total size of dataset (including the cache for partially mounted indices)
  
  One of:
  string-1 string string-2 string | null
- completion.size string
  
  size of completion
- pri.completion.size string
  
  size of completion
- fielddata.memory_size string
  
  used fielddata cache
- pri.fielddata.memory_size string
  
  used fielddata cache
- fielddata.evictions string
  
  fielddata evictions
- pri.fielddata.evictions string
  
  fielddata evictions
- query_cache.memory_size string
  
  used query cache
- pri.query_cache.memory_size string
  
  used query cache
- query_cache.evictions string
  
  query cache evictions
- pri.query_cache.evictions string
  
  query cache evictions
- request_cache.memory_size string
  
  used request cache
- pri.request_cache.memory_size string
  
  used request cache
- request_cache.evictions string
  
  request cache evictions
- pri.request_cache.evictions string
  
  request cache evictions
- request_cache.hit_count string
  
  request cache hit count
- pri.request_cache.hit_count string
  
  request cache hit count
- request_cache.miss_count string
  
  request cache miss count
- pri.request_cache.miss_count string
  
  request cache miss count
- flush.total string
  
  number of flushes
- pri.flush.total string
  
  number of flushes
- flush.total_time string
  
  time spent in flush
- pri.flush.total_time string
  
  time spent in flush
- get.current string
  
  number of current get ops
- pri.get.current string
  
  number of current get ops
- get.time string
  
  time spent in get
- pri.get.time string
  
  time spent in get
- get.total string
  
  number of get ops
- pri.get.total string
  
  number of get ops
- get.exists_time string
  
  time spent in successful gets
- pri.get.exists_time string
  
  time spent in successful gets
- get.exists_total string
  
  number of successful gets
- pri.get.exists_total string
  
  number of successful gets
- get.missing_time string
  
  time spent in failed gets
- pri.get.missing_time string
  
  time spent in failed gets
- get.missing_total string
  
  number of failed gets
- pri.get.missing_total string
  
  number of failed gets
- indexing.delete_current string
  
  number of current deletions
- pri.indexing.delete_current string
  
  number of current deletions
- indexing.delete_time string
  
  time spent in deletions
- pri.indexing.delete_time string
  
  time spent in deletions
- indexing.delete_total string
  
  number of delete ops
- pri.indexing.delete_total string
  
  number of delete ops
- indexing.index_current string
  
  number of current indexing ops
- pri.indexing.index_current string
  
  number of current indexing ops
- indexing.index_time string
  
  time spent in indexing
- pri.indexing.index_time string
  
  time spent in indexing
- indexing.index_total string
  
  number of indexing ops
- pri.indexing.index_total string
  
  number of indexing ops
- indexing.index_failed string
  
  number of failed indexing ops
- pri.indexing.index_failed string
  
  number of failed indexing ops
- merges.current string
  
  number of current merges
- pri.merges.current string
  
  number of current merges
- merges.current_docs string
  
  number of current merging docs
- pri.merges.current_docs string
  
  number of current merging docs
- merges.current_size string
  
  size of current merges
- pri.merges.current_size string
  
  size of current merges
- merges.total string
  
  number of completed merge ops
- pri.merges.total string
  
  number of completed merge ops
- merges.total_docs string
  
  docs merged
- pri.merges.total_docs string
  
  docs merged
- merges.total_size string
  
  size merged
- pri.merges.total_size string
  
  size merged
- merges.total_time string
  
  time spent in merges
- pri.merges.total_time string
  
  time spent in merges
- refresh.total string
  
  total refreshes
- pri.refresh.total string
  
  total refreshes
- refresh.time string
  
  time spent in refreshes
- pri.refresh.time string
  
  time spent in refreshes
- refresh.external_total string
  
  total external refreshes
- pri.refresh.external_total string
  
  total external refreshes
- refresh.external_time string
  
  time spent in external refreshes
- pri.refresh.external_time string
  
  time spent in external refreshes
- refresh.listeners string
  
  number of pending refresh listeners
- pri.refresh.listeners string
  
  number of pending refresh listeners
- search.fetch_current string
  
  current fetch phase ops
- pri.search.fetch_current string
  
  current fetch phase ops
- search.fetch_time string
  
  time spent in fetch phase
- pri.search.fetch_time string
  
  time spent in fetch phase
- search.fetch_total string
  
  total fetch ops
- pri.search.fetch_total string
  
  total fetch ops
- search.open_contexts string
  
  open search contexts
- pri.search.open_contexts string
  
  open search contexts
- search.query_current string
  
  current query phase ops
- pri.search.query_current string
  
  current query phase ops
- search.query_time string
  
  time spent in query phase
- pri.search.query_time string
  
  time spent in query phase
- search.query_total string
  
  total query phase ops
- pri.search.query_total string
  
  total query phase ops
- search.scroll_current string
  
  open scroll contexts
- pri.search.scroll_current string
  
  open scroll contexts
- search.scroll_time string
  
  time scroll contexts held open
- pri.search.scroll_time string
  
  time scroll contexts held open
- search.scroll_total string
  
  completed scroll contexts
- pri.search.scroll_total string
  
  completed scroll contexts
- segments.count string
  
  number of segments
- pri.segments.count string
  
  number of segments
- segments.memory string
  
  memory used by segments
- pri.segments.memory string
  
  memory used by segments
- segments.index_writer_memory string
  
  memory used by index writer
- pri.segments.index_writer_memory string
  
  memory used by index writer
- segments.version_map_memory string
  
  memory used by version map
- pri.segments.version_map_memory string
  
  memory used by version map
- segments.fixed_bitset_memory string
  
  memory used by fixed bit sets for nested object field types and export type filters for types referred in _parent fields
- pri.segments.fixed_bitset_memory string
  
  memory used by fixed bit sets for nested object field types and export type filters for types referred in _parent fields
- warmer.current string
  
  current warmer ops
- pri.warmer.current string
  
  current warmer ops
- warmer.total string
  
  total warmer ops
- pri.warmer.total string
  
  total warmer ops
- warmer.total_time string
  
  time spent in warmers
- pri.warmer.total_time string
  
  time spent in warmers
- suggest.current string
  
  number of current suggest ops
- pri.suggest.current string
  
  number of current suggest ops
- suggest.time string
  
  time spend in suggest
- pri.suggest.time string
  
  time spend in suggest
- suggest.total string
  
  number of suggest ops
- pri.suggest.total string
  
  number of suggest ops
- memory.total string
  
  total used memory
- pri.memory.total string
  
  total user memory
- search.throttled string
  
  indicates if the index is search throttled
- bulk.total_operations string
  
  number of bulk shard ops
- pri.bulk.total_operations string
  
  number of bulk shard ops
- bulk.total_time string
  
  time spend in shard bulk
- pri.bulk.total_time string
  
  time spend in shard bulk
- bulk.total_size_in_bytes string
  
  total size in bytes of shard bulk
- pri.bulk.total_size_in_bytes string
  
  total size in bytes of shard bulk
- bulk.avg_time string
  
  average time spend in shard bulk
- pri.bulk.avg_time string
  
  average time spend in shard bulk
- bulk.avg_size_in_bytes string
  
  average size in bytes of shard bulk
- pri.bulk.avg_size_in_bytes string
  
  average size in bytes of shard bulk

GET /_cat/indices/{index}

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();

Response examples (200)

A successful response from `GET /_cat/indices/my-index-*?v=true&s=index&format=json`.

[
  {
    "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 shard recovery information Generally available

GET /_cat/recovery/{index}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/recovery

GET /_cat/recovery/{index}

Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index recovery API.

Required authorization

Index privileges: monitor
Cluster privileges: monitor

Path parameters

index string | array[string] Required

A 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

active_only boolean

If true, the response only includes ongoing shard recoveries.
bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
detailed boolean

If true, the response includes detailed information about shard recoveries.
index string | array[string]

Comma-separated list or wildcard expression of index names to limit the returned information
h string | array[string]
A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:
- index (or i, idx): The name of the index.
- shard (or s, sh): The name of the shard.
- time (or t, ti, primaryOrReplica): The recovery time elasped.
- type: The type of recovery, from a peer or a snapshot.
- stage (or st): The stage of the recovery. Returned values are: INIT, INDEX: recovery of lucene files, either reusing local ones are copying new ones, VERIFY_INDEX: potentially running check index, TRANSLOG: starting up the engine, replaying the translog, FINALIZE: performing final task after all translog ops have been done, DONE
- source_host (or shost): The host address the index is moving from.
- source_node (or snode): The node name the index is moving from.
- target_host (or thost): The host address the index is moving to.
- target_node (or tnode): The node name the index is moving to.
- repository (or tnode): The name of the repository being used. if not relevant 'n/a'.
- snapshot (or snap): The name of the snapshot being used. if not relevant 'n/a'.
- files (or f): The total number of files to recover.
- files_recovered (or fr): The number of files currently recovered.
- files_percent (or fp): The percentage of files currently recovered.
- files_total (or tf): The total number of files.
- bytes (or b): The total number of bytes to recover.
- bytes_recovered (or br): Total number of bytes currently recovered.
- bytes_percent (or bp): The percentage of bytes currently recovered.
- bytes_total (or tb): The total number of bytes.
- translog_ops (or to): The total number of translog ops to recover.
- translog_ops_recovered (or tor): The total number of translog ops currently recovered.
- translog_ops_percent (or top): The percentage of translog ops currently recovered.
- start_time (or start): The start time of the recovery operation.
- start_time_millis (or start_millis): The start time of the recovery operation in eopch milliseconds.
- stop_time (or stop): The end time of the recovery operation. If ongoing '1970-01-01T00:00:00.000Z'
- stop_time_millis (or stop_millis): The end time of the recovery operation in eopch milliseconds. If ongoing '0'
Values are index, i, idx, shard, s, sh, time, t, ti, primaryOrReplica, type, stage, st, source_host, shost, source_node, snode, target_host, thost, target_node, tnode, repository, snapshot, snap, files, f, files_recovered, fr, files_percent, fp, files_total, tf, bytes, b, bytes_recovered, br, bytes_percent, bp, bytes_total, tb, translog_ops, to, translog_ops_recovered, tor, translog_ops_percent, top, start_time, start, start_time_millis, start_millis, stop_time, stop, stop_time_millis, or stop_millis.
s string | array[string]

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.
time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.

Responses

200 application/json
Hide response attributes Show response attributes object
- index string
- shard string
  
  The shard name.
- start_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
- start_time_millis number
  
  Time unit for milliseconds
- stop_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
- stop_time_millis number
  
  Time unit for milliseconds
- time string
  
  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.
- type string
  
  The recovery type.
- stage string
  
  The recovery stage.
- source_host string
  
  The source host.
- source_node string
  
  The source node name.
- target_host string
  
  The target host.
- target_node string
  
  The target node name.
- repository string
  
  The repository name.
- snapshot string
  
  The snapshot name.
- files string
  
  The number of files to recover.
- files_recovered string
  
  The files recovered.
- files_percent string | number
  
  One of:
  string-1 string number-2 number
- files_total string
  
  The total number of files.
- bytes string
  
  The number of bytes to recover.
- bytes_recovered string
  
  The bytes recovered.
- bytes_percent string | number
  
  One of:
  string-1 string number-2 number
- bytes_total string
  
  The total number of bytes.
- translog_ops string
  
  The number of translog operations to recover.
- translog_ops_recovered string
  
  The translog operations recovered.
- translog_ops_percent string | number
  
  One of:
  string-1 string number-2 number

GET /_cat/recovery/{index}

GET _cat/recovery?v=true&format=json

resp = client.cat.recovery(
    v=True,
    format="json",
)

const response = await client.cat.recovery({
  v: "true",
  format: "json",
});

response = client.cat.recovery(
  v: "true",
  format: "json"
)

$resp = $client->cat()->recovery([
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/recovery?v=true&format=json"

client.cat().recovery();

Response examples (200)

A successful response from `GET _cat/recovery?v=true&format=json`. In this example, the source and target nodes are the same because the recovery type is `store`, meaning they were read from local storage on node start.

[
  {
    "index": "my-index-000001 ",
    "shard": "0",
    "time": "13ms",
    "type": "store",
    "stage": "done",
    "source_host": "n/a",
    "source_node": "n/a",
    "target_host": "127.0.0.1",
    "target_node": "node-0",
    "repository": "n/a",
    "snapshot": "n/a",
    "files": "0",
    "files_recovered": "0",
    "files_percent": "100.0%",
    "files_total": "13",
    "bytes": "0b",
    "bytes_recovered": "0b",
    "bytes_percent": "100.0%",
    "bytes_total": "9928b",
    "translog_ops": "0",
    "translog_ops_recovered": "0",
    "translog_ops_percent": "100.0%"
  }
]

A successful response from `GET _cat/recovery?v=true&h=i,s,t,ty,st,shost,thost,f,fp,b,bp&format=json`. You can retrieve information about an ongoing recovery for example when you increase the replica count of an index and bring another node online to host the replicas. In this example, the recovery type is `peer`, meaning the shard recovered from another node. The `files` and `bytes` are real-time measurements.

[
  {
    "i": "my-index-000001",
    "s": "0",
    "t": "1252ms",
    "ty": "peer",
    "st": "done",
    "shost": "192.168.1.1",
    "thost": "192.168.1.1",
    "f": "0",
    "fp": "100.0%",
    "b": "0b",
    "bp": "100.0%",
  }
]

A successful response from `GET _cat/recovery?v=true&h=i,s,t,ty,st,rep,snap,f,fp,b,bp&format=json`. You can restore backups of an index using the snapshot and restore API. You can use the cat recovery API to get information about a snapshot recovery.

[
  {
    "i": "my-index-000001",
    "s": "0",
    "t": "1978ms",
    "ty": "snapshot",
    "st": "done",
    "rep": "my-repo",
    "snap": "snap-1",
    "f": "79",
    "fp": "8.0%",
    "b": "12086",
    "bp": "9.0%"
  }
]

Get index template information Generally available; Added in 5.2.0

GET /_cat/templates/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/templates

GET /_cat/templates/{name}

Get information about the index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. 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 index template API.

Required authorization

Cluster privileges: monitor

Path parameters

name string Required

The name of the template to return. Accepts wildcard expressions. If omitted, all templates are returned.

Query parameters

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 :asc or :desc as a suffix to the column name.
local boolean

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.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string
- index_patterns string
  
  The template index patterns.
- order string
  
  The template application order or priority number.
- version string | null
  
  The template version.
  
  One of:
  VersionString string string-2 string | null
- composed_of string
  
  The component templates that comprise the index template.

GET /_cat/templates/{name}

GET _cat/templates/my-template-*?v=true&s=name&format=json

resp = client.cat.templates(
    name="my-template-*",
    v=True,
    s="name",
    format="json",
)

const response = await client.cat.templates({
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json",
});

response = client.cat.templates(
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json"
)

$resp = $client->cat()->templates([
    "name" => "my-template-*",
    "v" => "true",
    "s" => "name",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/templates/my-template-*?v=true&s=name&format=json"

client.cat().templates();

Response examples (200)

A successful response from `GET _cat/templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "name": "my-template-0",
    "index_patterns": "[te*]",
    "order": "500",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-1",
    "index_patterns": "[tea*]",
    "order": "501",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-2",
    "index_patterns": "[teak*]",
    "order": "502",
    "version": "7",
    "composed_of": "[]"
  }
]

Get cluster-wide settings Generally available

GET /_cluster/settings

Api key auth Basic auth Bearer auth

By default, it returns only settings that have been explicitly defined.

Required authorization

Cluster privileges: monitor

External documentation

Query parameters

flat_settings boolean

If true, returns settings in flat format.
include_defaults boolean

If true, returns default cluster settings from the local 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.

Values are -1 or 0.
timeout string

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- persistent object Required
  
  The settings that persist after the cluster restarts.
  
  Hide persistent attribute Show persistent attribute object
  
  * object Additional properties
- transient object Required
  
  The settings that do not persist after the cluster restarts.
  
  Hide transient attribute Show transient attribute object
  
  * object Additional properties
- defaults object
  
  The default setting values.
  
  Hide defaults attribute Show defaults attribute object
  
  * object Additional properties

GET /_cluster/settings

GET /_cluster/settings?filter_path=persistent.cluster.remote

resp = client.cluster.get_settings(
    filter_path="persistent.cluster.remote",
)

const response = await client.cluster.getSettings({
  filter_path: "persistent.cluster.remote",
});

response = client.cluster.get_settings(
  filter_path: "persistent.cluster.remote"
)

$resp = $client->cluster()->getSettings([
    "filter_path" => "persistent.cluster.remote",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/settings?filter_path=persistent.cluster.remote"

Get the cluster health status Generally available; Added in 1.3.0

GET /_cluster/health/{index}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cluster/health

GET /_cluster/health/{index}

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.

Required authorization

Cluster privileges: monitor,manage

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 with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
level string

Can be one of cluster, indices or shards. Controls the details level of the health information returned.

Values are cluster, indices, or shards.
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.

Values are -1 or 0.
timeout string

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.
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.

Values are all or index-setting.
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, or languid.
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 (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.
- unknown
- unavailable
Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.

Responses

200 application/json
Hide response attributes Show response attributes object
- active_primary_shards number Required
  
  The number of active primary shards.
- active_shards number Required
  
  The total number of active primary and replica shards.
- active_shards_percent string
  
  The ratio of active shards in the cluster expressed as a string formatted percentage.
- active_shards_percent_as_number number Required
  
  The ratio of active shards in the cluster expressed as a percentage.
- cluster_name string Required
- delayed_unassigned_shards number Required
  
  The number of shards whose allocation has been delayed by the timeout settings.
- indices object
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  active_primary_shards number Required
  
  active_shards number Required
  
  initializing_shards number Required
  
  number_of_replicas number Required
  
  number_of_shards number Required
  
  relocating_shards number Required
  
  shards object
  
  Hide shards attribute Show shards attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  active_shards number Required
  
  initializing_shards number Required
  
  primary_active boolean Required
  
  relocating_shards number Required
  
  status string Required
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
  
  unassigned_shards number Required
  
  unassigned_primary_shards number Required
  
  status string Required
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
  
  unassigned_shards number Required
  
  unassigned_primary_shards number Required
- initializing_shards number Required
  
  The number of shards that are under initialization.
- number_of_data_nodes number Required
  
  The number of nodes that are dedicated data nodes.
- number_of_in_flight_fetch number Required
  
  The number of unfinished fetches.
- number_of_nodes number Required
  
  The number of nodes within the cluster.
- number_of_pending_tasks number Required
  
  The number of cluster-level changes that have not yet been executed.
- relocating_shards number Required
  
  The number of shards that are under relocation.
- status string Required
  
  Values are green, GREEN, yellow, YELLOW, red, RED, unknown, or unavailable.
- task_max_waiting_in_queue string
  
  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.
- task_max_waiting_in_queue_millis number
  
  Time unit for milliseconds
- timed_out boolean Required
  
  If false the response returned within the period of time that is specified by the timeout parameter (30s by default)
- unassigned_primary_shards number Required
  
  The number of primary shards that are not allocated.
- unassigned_shards number Required
  
  The number of shards that are not allocated.

GET /_cluster/health/{index}

GET _cluster/health

resp = client.cluster.health()

const response = await client.cluster.health();

response = client.cluster.health

$resp = $client->cluster()->health();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cluster/health"

client.cluster().health(h -> h);

Response examples (200)

A successful response from `GET _cluster/health`. It is the health status of a quiet single node cluster with a single index with one shard and one replica.

{
  "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
}

Clear the archived repositories metering Technical preview; Added in 7.16.0

DELETE /_nodes/{node_id}/_repositories_metering/{max_archive_version}

Api key auth Basic auth Bearer auth

Clear the archived repositories metering information in the cluster.

Required authorization

Cluster privileges: monitor,manage

Path parameters

node_id string | array[string] Required

Comma-separated list of node IDs or names used to limit returned information.
max_archive_version number Required

Specifies the maximum archive_version to be cleared from the archive.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object
  
  Contains statistics about the number of nodes selected by the request.
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Contains repositories metering information for the nodes selected by the request.
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  repository_name string Required
  
  repository_type string Required
  
  Repository type.
  
  repository_location object Required
  
  Hide repository_location attributes Show repository_location attributes object
  
  base_path string Required
  
  container string
  
  Container name (Azure)
  
  bucket string
  
  Bucket name (GCP, S3)
  
  repository_ephemeral_id string Required
  
  Time unit for milliseconds
  
  Time unit for milliseconds
  
  archived boolean Required
  
  A flag that tells whether or not this object has been archived. When a repository is closed or updated the repository metering information is archived and kept for a certain period of time. This allows retrieving the repository metering information of previous repository instantiations.
  
  cluster_version number
  
  request_counts object Required
  
  Hide request_counts attributes Show request_counts attributes object
  
  GetBlobProperties number
  
  Number of Get Blob Properties requests (Azure)
  
  GetBlob number
  
  Number of Get Blob requests (Azure)
  
  ListBlobs number
  
  Number of List Blobs requests (Azure)
  
  PutBlob number
  
  Number of Put Blob requests (Azure)
  
  PutBlock number
  
  Number of Put Block (Azure)
  
  PutBlockList number
  
  Number of Put Block List requests
  
  GetObject number
  
  Number of get object requests (GCP, S3)
  
  ListObjects number
  
  Number of list objects requests (GCP, S3)
  
  InsertObject number
  
  Number of insert object requests, including simple, multipart and resumable uploads. Resumable uploads can perform multiple http requests to insert a single object but they are considered as a single request since they are billed as an individual operation. (GCP)
  
  PutObject number
  
  Number of PutObject requests (S3)
  
  PutMultipartObject number
  
  Number of Multipart requests, including CreateMultipartUpload, UploadPart and CompleteMultipartUpload requests (S3)

DELETE /_nodes/{node_id}/_repositories_metering/{max_archive_version}

curl \
 --request DELETE 'http://api.example.com/_nodes/{node_id}/_repositories_metering/{max_archive_version}' \
 --header "Authorization: $API_KEY"

Get cluster repositories metering Technical preview; Added in 7.16.0

GET /_nodes/{node_id}/_repositories_metering

Api key auth Basic auth Bearer auth

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.

Required authorization

Cluster privileges: monitor,manage

Path parameters

node_id string | array[string] Required

Comma-separated list of node IDs or names used to limit returned information.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object
  
  Contains statistics about the number of nodes selected by the request.
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Contains repositories metering information for the nodes selected by the request.
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  repository_name string Required
  
  repository_type string Required
  
  Repository type.
  
  repository_location object Required
  
  Hide repository_location attributes Show repository_location attributes object
  
  base_path string Required
  
  container string
  
  Container name (Azure)
  
  bucket string
  
  Bucket name (GCP, S3)
  
  repository_ephemeral_id string Required
  
  Time unit for milliseconds
  
  Time unit for milliseconds
  
  archived boolean Required
  
  A flag that tells whether or not this object has been archived. When a repository is closed or updated the repository metering information is archived and kept for a certain period of time. This allows retrieving the repository metering information of previous repository instantiations.
  
  cluster_version number
  
  request_counts object Required
  
  Hide request_counts attributes Show request_counts attributes object
  
  GetBlobProperties number
  
  Number of Get Blob Properties requests (Azure)
  
  GetBlob number
  
  Number of Get Blob requests (Azure)
  
  ListBlobs number
  
  Number of List Blobs requests (Azure)
  
  PutBlob number
  
  Number of Put Blob requests (Azure)
  
  PutBlock number
  
  Number of Put Block (Azure)
  
  PutBlockList number
  
  Number of Put Block List requests
  
  GetObject number
  
  Number of get object requests (GCP, S3)
  
  ListObjects number
  
  Number of list objects requests (GCP, S3)
  
  InsertObject number
  
  Number of insert object requests, including simple, multipart and resumable uploads. Resumable uploads can perform multiple http requests to insert a single object but they are considered as a single request since they are billed as an individual operation. (GCP)
  
  PutObject number
  
  Number of PutObject requests (S3)
  
  PutMultipartObject number
  
  Number of Multipart requests, including CreateMultipartUpload, UploadPart and CompleteMultipartUpload requests (S3)

GET /_nodes/{node_id}/_repositories_metering

curl \
 --request GET 'http://api.example.com/_nodes/{node_id}/_repositories_metering' \
 --header "Authorization: $API_KEY"

Set the connector sync job stats Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_stats

Api key auth Basic auth Bearer auth

Stats include: deleted_document_count, indexed_document_count, indexed_document_volume, and total_document_count. You can also update last_seen. This API is mainly used by the connector service for updating sync job information.

To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job.

application/json

Body Required

deleted_document_count number Required

The number of documents the sync job deleted.
indexed_document_count number Required

The number of documents the sync job indexed.
indexed_document_volume number Required

The total size of the data (in MiB) the sync job indexed.
last_seen string

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.
metadata object
Hide metadata attribute Show metadata attribute object
- * object Additional properties
total_document_count number

The total number of documents in the target index after the sync job finished.

Responses

200 application/json

PUT /_connector/_sync_job/{connector_sync_job_id}/_stats

PUT _connector/_sync_job/my-connector-sync-job/_stats
{
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
}

resp = client.connector.sync_job_update_stats(
    connector_sync_job_id="my-connector-sync-job",
    deleted_document_count=10,
    indexed_document_count=20,
    indexed_document_volume=1000,
    total_document_count=2000,
    last_seen="2023-01-02T10:00:00Z",
)

const response = await client.connector.syncJobUpdateStats({
  connector_sync_job_id: "my-connector-sync-job",
  deleted_document_count: 10,
  indexed_document_count: 20,
  indexed_document_volume: 1000,
  total_document_count: 2000,
  last_seen: "2023-01-02T10:00:00Z",
});

response = client.connector.sync_job_update_stats(
  connector_sync_job_id: "my-connector-sync-job",
  body: {
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
  }
)

$resp = $client->connector()->syncJobUpdateStats([
    "connector_sync_job_id" => "my-connector-sync-job",
    "body" => [
        "deleted_document_count" => 10,
        "indexed_document_count" => 20,
        "indexed_document_volume" => 1000,
        "total_document_count" => 2000,
        "last_seen" => "2023-01-02T10:00:00Z",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"deleted_document_count":10,"indexed_document_count":20,"indexed_document_volume":1000,"total_document_count":2000,"last_seen":"2023-01-02T10:00:00Z"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job/_stats"

client.connector().syncJobUpdateStats(s -> s
    .connectorSyncJobId("my-connector-sync-job")
    .deletedDocumentCount(10L)
    .indexedDocumentCount(20L)
    .indexedDocumentVolume(1000L)
    .lastSeen(l -> l
        .time("2023-01-02T10:00:00Z")
    )
    .totalDocumentCount(2000)
);

Request example

An example body for a `PUT _connector/_sync_job/my-connector-sync-job/_stats` request.

{
    "deleted_document_count": 10,
    "indexed_document_count": 20,
    "indexed_document_volume": 1000,
    "total_document_count": 2000,
    "last_seen": "2023-01-02T10:00:00Z"
}

Downsample an index Technical preview; Added in 8.5.0

POST /{index}/_downsample/{target_index}

Api key auth Basic auth Bearer auth

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.

application/json

Body Required

fixed_interval string Required

A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

Responses

200 application/json

POST /{index}/_downsample/{target_index}

POST /my-time-series-index/_downsample/my-downsampled-time-series-index
{
  "fixed_interval": "1d"
}

resp = client.indices.downsample(
    index="my-time-series-index",
    target_index="my-downsampled-time-series-index",
    config={
        "fixed_interval": "1d"
    },
)

const response = await client.indices.downsample({
  index: "my-time-series-index",
  target_index: "my-downsampled-time-series-index",
  config: {
    fixed_interval: "1d",
  },
});

response = client.indices.downsample(
  index: "my-time-series-index",
  target_index: "my-downsampled-time-series-index",
  body: {
    "fixed_interval": "1d"
  }
)

$resp = $client->indices()->downsample([
    "index" => "my-time-series-index",
    "target_index" => "my-downsampled-time-series-index",
    "body" => [
        "fixed_interval" => "1d",
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"fixed_interval":"1d"}' "$ELASTICSEARCH_URL/my-time-series-index/_downsample/my-downsampled-time-series-index"

client.indices().downsample(d -> d
    .index("my-time-series-index")
    .targetIndex("my-downsampled-time-series-index")
    .config(c -> c
        .fixedInterval(f -> f
            .time("1d")
        )
    )
);

Request example

{
  "fixed_interval": "1d"
}

Create a new document in the index Generally available; Added in 5.0.0

POST /{index}/_create/{id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /{index}/_create/{id}

POST /{index}/_create/{id}

You can index a new JSON document with the /<target>/_doc/ or /<target>/_create/<_id> APIs Using _create guarantees that the document is indexed only if it does not already exist. It returns a 409 response when a document with a same ID already exists in the index. To update an existing document, you must use the /<target>/_doc/ API.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

To add a document using the PUT /<target>/_create/<_id> or POST /<target>/_create/<_id> request formats, you must have the create_doc, create, index, or write index privilege.
To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.

Automatic data stream creation requires a matching index template with data stream enabled.

Automatically create data streams and indices

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.

Automatic index creation is controlled by the action.auto_create_index setting. If it is true, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow.

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. It does not affect the creation of data streams.

Routing

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

Distributed

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

Active shards

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. To alter this behavior per operation, use the wait_for_active_shards request parameter.

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). Specifying a negative value or a number greater than the number of shard copies will throw an error.

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

Required authorization

Index privileges: create

External documentation

Path parameters

index string Required

The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream. If the target doesn't exist and doesn’t match a data stream template, this request creates the index.
id string Required

A unique identifier for the document. To automatically generate a document ID, use the POST /<target>/_doc/ request format.

Query parameters

include_source_on_error boolean

True or false if to include the document source in the error message in case of parsing errors.
pipeline string

The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to _none turns off the default ingest pipeline for this request. If a final pipeline is configured, it will always run regardless of the value of this parameter.
refresh string

If true, Elasticsearch refreshes the affected shards to make this operation visible to search. 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.
require_alias boolean

If true, the destination must be an index alias.
require_data_stream boolean

If true, the request's actions must target a data stream (existing or to be created).
routing string

A custom value that is used to route operations to a specific shard.
timeout string

The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. Elasticsearch waits for at least the specified timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.

This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.

Values are -1 or 0.
version number

The explicit version number for concurrency control. It must be a non-negative long number.
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: 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.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

Values are all or index-setting.

application/json

Body Required

object

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- _index string Required
- _primary_term number
  
  The primary term assigned to the document for the indexing operation.
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- _seq_no number
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number
- _version number Required
- forced_refresh boolean

POST /{index}/_create/{id}

PUT my-index-000001/_create/1
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

resp = client.create(
    index="my-index-000001",
    id="1",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)

const response = await client.create({
  index: "my-index-000001",
  id: 1,
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});

response = client.create(
  index: "my-index-000001",
  id: "1",
  body: {
    "@timestamp": "2099-11-15T13:12:00",
    "message": "GET /search HTTP/1.1 200 1070000",
    "user": {
      "id": "kimchy"
    }
  }
)

$resp = $client->create([
    "index" => "my-index-000001",
    "id" => "1",
    "body" => [
        "@timestamp" => "2099-11-15T13:12:00",
        "message" => "GET /search HTTP/1.1 200 1070000",
        "user" => [
            "id" => "kimchy",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}' "$ELASTICSEARCH_URL/my-index-000001/_create/1"

client.create(c -> c
    .id("1")
    .index("my-index-000001")
    .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
);

Request example

Run `PUT my-index-000001/_create/1` to index a document into the `my-index-000001` index if no document with that ID exists.

{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

Response examples (200)

A successful response from `PUT my-index-000001/_create/1` which indexes a document.

{
   "_index": "my-index-000001",
   "_id": "1",
   "_version": 1,
   "result": "created",
   "_shards": {
     "total": 1,
     "successful": 1,
     "failed": 0
   },
   "_seq_no": 0,
   "_primary_term": 1
}

Update a document Generally available

POST /{index}/_update/{id}

Api key auth Basic auth Bearer auth

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:

Gets the document (collocated with the shard) from the index.
Runs the specified script.
Indexes the result.

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). For usage examples such as partial updates, upserts, and scripted updates, see the External documentation.

Required authorization

Index privileges: write

External documentation

Path parameters

index string Required

The name of the target index. By default, the index is created automatically if it doesn't exist.
id string Required

A unique identifier for the document to be updated.

Query parameters

if_primary_term number

Only perform the operation if the document has this primary term.
if_seq_no number

Only perform the operation if the document has this sequence number.
include_source_on_error boolean

True or false if to include the document source in the error message in case of parsing errors.
lang string

The script language.
refresh string

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.
require_alias boolean

If true, the destination must be an index alias.
retry_on_conflict number

The number of times the operation should be retried when a conflict occurs.
routing string

A custom value used to route operations to a specific shard.
timeout string

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.
wait_for_active_shards number | string

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.
_source boolean | string | array[string]

If false, source retrieval is turned off. You can also specify a comma-separated list of the fields you want to retrieve.
_source_excludes string | array[string]

The source fields you want to exclude.
_source_includes string | array[string]

The source fields you want to retrieve.

application/json

Body Required

detect_noop boolean

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.
doc object

A partial update to an existing document. If both doc and script are specified, doc is ignored.
doc_as_upsert boolean

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.
script object
Hide script attributes Show script attributes object
- source string | object
 
 One of:
 string-1 string SearchRequestBody object
 
 Hide attributes Show attributes
 
 aggregations object
 
 Defines the aggregations that are run as part of the search request.
 
 External documentation
 
 collapse object
 External documentation
 
 explain boolean
 
 If true, the request returns detailed information about score computation as part of a hit.
 
 Default value is false.
 
 ext object
 
 Configuration of search extensions defined by Elasticsearch plugins.
 
 Hide ext attribute Show ext attribute object
 
 * object Additional properties
 
 from number
 
 The starting document offset, which must be non-negative. 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.
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type string
 
 Any of:
 string-1 string string-2 string
 
 Values are plain, fvh, or unified.
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 Default value is .,!? \t\n.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 Default value is 20.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 Default value is Locale.ROOT.
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 Default value is 100.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 Default value is 0.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 Default value is 5.
 
 options object
 
 Hide options attribute Show options attribute object
 
 * object Additional properties
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 Default value is 256.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 Default value is true.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object | array[object] Required
 
 One of:
 object-1 object array-2 array[object]
 
 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.
 
 indices_boost array[object]
 
 Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
 
 External documentation
 
 Hide indices_boost attribute Show indices_boost attribute object
 
 * number Additional properties
 
 docvalue_fields array[object]
 
 An array of wildcard (*) field 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
 
 External documentation
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 knn object | array[object]
 
 The approximate kNN search to run.
 
 One of:
 KnnSearch object array-2 array[object]
 
 Hide attributes Show attributes
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 Hide query_vector_builder attribute Show query_vector_builder attribute object
 
 text_embedding object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter object | array[object]
 
 Filters for the kNN search query
 
 One of:
 QueryContainer object array-2 array[object]
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 Hide inner_hits attributes Show inner_hits attributes object
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 Default value is 3.
 
 from number
 
 Inner hit starting document offset.
 
 Default value is 0.
 
 collapse object
 
 docvalue_fields array[object]
 
 explain boolean
 
 highlight
 
 ignore_unmapped boolean
 
 script_fields object
 
 seq_no_primary_term boolean
 
 fields array[string]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 sort
 
 _source
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 Default value is false.
 
 version boolean
 
 rescore_vector object
 
 Hide rescore_vector attribute Show rescore_vector attribute object
 
 oversample number Required
 
 Applies the specified oversample factor to k on the approximate kNN search
 
 External documentation
 
 Hide attributes Show attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 rescore_vector object
 
 rank object
 
 Hide rank attribute Show rank attribute object
 
 rrf object
 
 Hide rrf attributes Show rrf attributes object
 
 rank_constant number
 
 How much influence documents in individual result sets per query have over the final ranked result set
 
 rank_window_size number
 
 Size of the individual result sets per query
 
 min_score number
 
 The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
 
 post_filter object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 profile boolean
 
 Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
 
 Default value is false.
 
 query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 rescore object | array[object]
 
 Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
 
 One of:
 object-2 object array-2 array[object]
 
 Hide attributes Show attributes
 
 window_size number
 
 query object
 
 learning_to_rank object
 
 retriever object
 
 Hide retriever attributes Show retriever attributes object
 
 standard object
 
 Hide standard attributes Show standard attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 terminate_after number
 
 Maximum number of documents to collect for each shard.
 
 sort
 
 collapse object
 
 knn object
 
 Hide knn attributes Show knn attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 field string Required
 
 The name of the vector field to search against.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number Required
 
 Number of nearest neighbors to return as top hits.
 
 num_candidates number Required
 
 Number of nearest neighbor candidates to consider per shard.
 
 similarity number
 
 The minimum similarity required for a document to be considered a match.
 
 rescore_vector object
 
 rrf object
 
 Hide rrf attributes Show rrf attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 retrievers array[object] Required
 
 A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
 
 rank_constant number
 
 This value determines how much influence documents in individual result sets per query have over the final ranked result set.
 
 rank_window_size number
 
 This value determines the size of the individual result sets per query.
 
 query string
 
 fields array[string]
 
 text_similarity_reranker object
 
 Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 retriever object Required
 
 rank_window_size number
 
 This value determines how many documents we will consider from the nested retriever.
 
 inference_id string
 
 Unique identifier of the inference endpoint created using the inference API.
 
 inference_text string Required
 
 The text snippet used as the basis for similarity comparison
 
 field string Required
 
 The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
 
 rule object
 
 Hide rule attributes Show rule attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 ruleset_ids
 
 match_criteria object Required
 
 The match criteria that will determine if a rule in the provided rulesets should be applied.
 
 retriever object Required
 
 rank_window_size number
 
 This value determines the size of the individual result set.
 
 rescorer object
 
 Hide rescorer attributes Show rescorer attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 retriever object Required
 
 rescore
 
 linear object
 
 Hide linear attributes Show linear attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 retrievers array[object]
 
 Inner retrievers.
 
 rank_window_size number
 
 query string
 
 fields array[string]
 
 normalizer string
 
 Values are none, minmax, or l2_norm.
 
 pinned object
 
 Hide pinned attributes Show pinned attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 _name string
 
 Retriever name.
 
 retriever object Required
 
 ids array[string]
 
 docs array[object]
 
 rank_window_size number
 
 script_fields object
 
 Retrieve a script evaluation (based on different fields) for each hit.
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 ignore_failure boolean
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 size number
 
 The number of hits to return, which must not be negative. 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 property.
 
 Default value is 10.
 
 slice object
 
 Hide slice attributes Show slice attributes object
 
 field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 id string Required
 
 max number Required
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object array-2 array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 boolean-1 boolean SourceFilter object
 
 Hide attributes Show attributes
 
 exclude_vectors boolean
 
 If true, vector fields are excluded from the returned source.
 
 This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.
 
 excludes string | array[string]
 
 includes string | array[string]
 
 fields array[object]
 
 An array of wildcard (*) field 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
 
 Hide fields attributes Show fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 suggest object
 
 Hide suggest attribute Show suggest attribute object
 
 text string
 
 Global suggest text, to avoid repetition when the same text is used in several suggesters
 
 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 property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
 
 If set to 0 (default), the query does not terminate early.
 
 Default value is 0.
 
 timeout string
 
 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.
 
 track_scores boolean
 
 If true, calculate and return document scores, even if the scores are not used for sorting.
 
 Default value is false.
 
 version boolean
 
 If true, the request returns the document version as part of a hit.
 
 Default value is false.
 
 seq_no_primary_term boolean
 
 If true, the request returns sequence number and primary term of the last modification of each hit.
 
 External documentation
 
 stored_fields string | array[string]
 
 pit object
 
 Hide pit attributes Show pit attributes object
 
 id string Required
 
 keep_alive string
 
 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.
 
 runtime_mappings object
 
 Hide runtime_mappings attribute Show runtime_mappings attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 fields object
 
 For type composite
 
 Hide fields attribute Show fields attribute object
 
 * object Additional properties
 
 fetch_fields array[object]
 
 For type lookup
 
 format string
 
 A custom format for date type runtime fields.
 
 input_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_index string
 
 script object
 
 type string Required
 
 Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
 
 stats array[string]
 
 The 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.
- id string
- params object
 
 Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
 Hide params attribute Show params attribute object
 
 * object Additional properties
- lang string
 
 Any of:
 string-1 string string-2 string
 
 Values are painless, expression, mustache, or java.
- options object
 Hide options attribute Show options attribute object
 
 * string Additional properties
scripted_upsert boolean

If true, run the script whether or not the document exists.

Default value is false.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
boolean-1 boolean SourceFilter object
Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]
upsert object

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- _index string Required
- _primary_term number
  
  The primary term assigned to the document for the indexing operation.
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- _seq_no number
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- _version number Required
- forced_refresh boolean
- get object
  
  Hide get attributes Show get attributes object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  found boolean Required
  
  _seq_no number
  
  _primary_term number
  
  _routing string
  
  _source object

POST /{index}/_update/{id}

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);

Request examples

Run `POST test/_update/1` to increment a counter by using a script.

{
  "script" : {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params" : {
      "count" : 4
    }
  }
}

Run `POST test/_update/1` to perform a scripted upsert. When `scripted_upsert` is `true`, the script runs whether or not the document exists.

{
  "scripted_upsert": true,
  "script": {
    "source": """
      if ( ctx.op == 'create' ) {
        ctx._source.counter = params.count
      } else {
        ctx._source.counter += params.count
      }
    """,
    "params": {
      "count": 4
    }
  },
  "upsert": {}
}

Run `POST test/_update/1` to perform a doc as upsert. Instead of sending a partial `doc` plus an `upsert` doc, you can set `doc_as_upsert` to `true` to use the contents of `doc` as the `upsert` value.

{
  "doc": {
    "name": "new_name"
  },
  "doc_as_upsert": true
}

Run `POST test/_update/1` to use a script to add a tag to a list of tags. In this example, it is just a list, so the tag is added even it exists.

{
  "script": {
    "source": "ctx._source.tags.add(params.tag)",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

Run `POST test/_update/1` to use a script to remove a tag from a list of tags. The Painless function to remove a tag takes the array index of the element you want to remove. To avoid a possible runtime error, you first need to make sure the tag exists. If the list contains duplicates of the tag, this script just removes one occurrence.

{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

Run `POST test/_update/1` to use a script to add a field `new_field` to the document.

{
  "script" : "ctx._source.new_field = 'value_of_new_field'"
}

Run `POST test/_update/1` to use a script to remove a field `new_field` from the document.

{
  "script" : "ctx._source.remove('new_field')"
}

Run `POST test/_update/1` to use a script to remove a subfield from an object field.

{
  "script": "ctx._source['my-object'].remove('my-subfield')"
}

Run `POST test/_update/1` to change the operation that runs from within the script. For example, this request deletes the document if the `tags` field contains `green`, otherwise it does nothing (`noop`).

{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
    "lang": "painless",
    "params": {
      "tag": "green"
    }
  }
}

Run `POST test/_update/1` to do a partial update that adds a new field to the existing document.

{
  "doc": {
    "name": "new_name"
  }
}

Run `POST test/_update/1` to perfom an upsert. If the document does not already exist, the contents of the upsert element are inserted as a new document. If the document exists, the script is run.

{
  "script": {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params": {
      "count": 4
    }
  },
  "upsert": {
    "counter": 1
  }
}

Response examples (200)

By default updates that don't change anything detect that they don't change anything and return `"result": "noop"`.

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Get enrich stats Generally available; Added in 7.5.0

GET /_enrich/_stats

Api key auth Basic auth Bearer auth

Returns enrich coordinator statistics and information about enrich policies that are currently executing.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- coordinator_stats array[object] Required
  
  Objects containing information about each coordinating ingest node for configured enrich processors.
  
  Hide coordinator_stats attributes Show coordinator_stats attributes object
  
  executed_searches_total number Required
  
  node_id string Required
  
  queue_size number Required
  
  remote_requests_current number Required
  
  remote_requests_total number Required
- executing_policies array[object] Required
  
  Objects containing information about each enrich policy that is currently executing.
  
  Hide executing_policies attributes Show executing_policies attributes object
  
  name string Required
  
  task object Required Additional properties
  
  Hide task attributes Show task attributes object
  
  action string Required
  
  cancelled boolean
  
  cancellable boolean Required
  
  description string
  
  Human readable text that identifies the particular request that the task is performing. For example, it might identify the search request being performed by a search task. Other kinds of tasks have different descriptions, like _reindex which has the source and the destination, or _bulk which just has the number of requests and the destination indices. Many requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request.
  
  headers object Required
  
  Hide headers attribute Show headers attribute object
  
  * string Additional properties
  
  id number Required
  
  node string Required
  
  running_time string
  
  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.
  
  running_time_in_nanos number
  
  Time unit for nanoseconds
  
  start_time_in_millis number
  
  Time unit for milliseconds
  
  status object
  
  The internal status of the task, which varies from task to task. The format also varies. While the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes. Fields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases.
  
  type string Required
  
  parent_task_id string
- cache_stats array[object] Generally available; Added in 7.16.0
  
  Objects containing information about the enrich cache stats on each ingest node.
  
  Hide cache_stats attributes Show cache_stats attributes object
  
  node_id string Required
  
  count number Required
  
  hits number Required
  
  hits_time_in_millis number
  
  Time unit for milliseconds
  
  misses number Required
  
  misses_time_in_millis number
  
  Time unit for milliseconds
  
  evictions number Required
  
  size_in_bytes number Required

GET /_enrich/_stats

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 async EQL status Generally available; Added in 7.9.0

GET /_eql/search/status/{id}

Api key auth Basic auth Bearer auth

Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

Path parameters

id string Required

Identifier for the search.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string Required
- is_partial boolean Required
  
  If true, the search request is still executing. If false, the search is completed.
- is_running boolean Required
  
  If true, the response does not contain complete search results. This could be because either the search is still running (is_running status is false), or because it is already completed (is_running status is true) and results are partial due to failures or timeouts.
- start_time_in_millis number
  
  Time unit for milliseconds
- expiration_time_in_millis number
  
  Time unit for milliseconds
- completion_status number
  
  For a completed search shows the http status code of the completed search.

GET /_eql/search/status/{id}

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=")
);

Response examples (200)

A successful response for getting status information for an async EQL search.

{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1611690235000,
  "expiration_time_in_millis" : 1611690295000
}

Get EQL search results Generally available; Added in 7.9.0

POST /{index}/_eql/search

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /{index}/_eql/search

POST /{index}/_eql/search

Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

External documentation

Path parameters

index string | array[string] Required

The name of the index to scope the operation

Query parameters

allow_no_indices boolean

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
allow_partial_search_results boolean

If true, returns partial results if there are shard failures. If false, returns an error with no partial results.
allow_partial_sequence_results boolean

If true, sequence queries will return partial results in case of shard failures. If false, they will return no results at all. This flag has effect only if allow_partial_search_results is true.
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 with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
ccs_minimize_roundtrips boolean

Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
keep_alive string

Period for which the search and its results are stored on the cluster.

Values are -1 or 0.
keep_on_completion boolean

If true, the search and its results are stored on the cluster.
wait_for_completion_timeout string

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.

application/json

Body Required

query string Required

EQL query you wish to run.
case_sensitive boolean
event_category_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
tiebreaker_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
timestamp_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
fetch_size number
filter object | array[object]

Query, written in Query DSL, used to filter the events on which the EQL query runs.

One of:
QueryContainer object array-2 array[object]

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
keep_alive string

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.
keep_on_completion boolean
wait_for_completion_timeout string

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.
allow_partial_search_results boolean

Allow query execution also in case of shard failures. If true, the query will keep running and will return results based on the available shards. For sequences, the behavior can be further refined using allow_partial_sequence_results

Default value is true.
allow_partial_sequence_results boolean

This flag applies only to sequences and has effect only if allow_partial_search_results=true. If true, the sequence query will return results based on the available shards, ignoring the others. If false, the sequence query will return successfully, but will always have empty results.

Default value is false.
size number
fields object | array[object]

Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.
One of:
FieldAndFormat object array-2 array[object]
A reference to a field with formatting instructions on how to return the value
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean
A reference to a field with formatting instructions on how to return the value
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean
result_position string

Values are tail or head.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from number
  
  The starting document offset, which must be non-negative. 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.
  
  highlight object
  
  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.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  External documentation
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field 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
  
  External documentation
  
  A reference to a field with formatting instructions on how to return the value
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  rescorer
  
  linear
  
  pinned
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. 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 property.
  
  Default value is 10.
  
  slice object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  fields array[object]
  
  An array of wildcard (*) field 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
  
  A reference to a field with formatting instructions on how to return the value
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  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 property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  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.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive string
  
  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.
  
  runtime_mappings object
  
  stats array[string]
  
  The 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.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
max_samples_per_key number

By default, the response of a sample query contains up to 10 samples, with one sample per unique set of join keys. Use the size parameter to get a smaller or larger set of samples. To retrieve more than one sample per set of join keys, use the max_samples_per_key parameter. Pipes are not supported for sample queries.

Default value is 1.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- is_partial boolean
  
  If true, the response does not contain complete search results.
- is_running boolean
  
  If true, the search request is still executing.
- took number
  
  Time unit for milliseconds
- timed_out boolean
  
  If true, the request timed out before completion.
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object
  
  Hide total attributes Show total attributes object
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  events array[object]
  
  Contains events matching the query. Each object represents a matching event.
  
  Hide events attributes Show events attributes object
  
  _index string Required
  
  _id string Required
  
  _source object Required
  
  Original JSON body passed for the event at index time.
  
  missing boolean
  
  Set to true for events in a timespan-constrained sequence that do not meet a given condition.
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * array[object] Additional properties
  
  sequences array[object]
  
  Contains event sequences matching the query. Each object represents a matching sequence. This parameter is only returned for EQL queries containing a sequence.
  
  Hide sequences attributes Show sequences attributes object
  
  events array[object] Required
  
  Contains events matching the query. Each object represents a matching event.
  
  Hide events attributes Show events attributes object
  
  _index string Required
  
  _id string Required
  
  _source object Required
  
  Original JSON body passed for the event at index time.
  
  missing boolean
  
  Set to true for events in a timespan-constrained sequence that do not meet a given condition.
  
  fields object
  
  join_keys array[object]
  
  Shared field values used to constrain matches in the sequence. These are defined using the by keyword in the EQL query syntax.
- shard_failures array[object]
  
  Contains information about shard failures (if any), in case allow_partial_search_results=true
  
  Hide shard_failures attributes Show shard_failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string

POST /{index}/_eql/search

GET /my-data-stream/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

resp = client.eql.search(
    index="my-data-stream",
    query="\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
)

const response = await client.eql.search({
  index: "my-data-stream",
  query:
    '\n    process where (process.name == "cmd.exe" and process.pid != 2013)\n  ',
});

response = client.eql.search(
  index: "my-data-stream",
  body: {
    "query": "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "
  }
)

$resp = $client->eql()->search([
    "index" => "my-data-stream",
    "body" => [
        "query" => "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "}' "$ELASTICSEARCH_URL/my-data-stream/_eql/search"

client.eql().search(s -> s
    .index("my-data-stream")
    .query(" process where (process.name == \"cmd.exe\" and process.pid != 2013) ")
);

Request examples

Run `GET /my-data-stream/_eql/search` to search for events that have a `process.name` of `cmd.exe` and a `process.pid` other than `2013`.

{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

Run `GET /my-data-stream/_eql/search` to search for a sequence of events. The sequence starts with an event with an `event.category` of `file`, a `file.name` of `cmd.exe`, and a `process.pid` other than `2013`. It is followed by an event with an `event.category` of `process` and a `process.executable` that contains the substring `regsvr32`. These events must also share the same `process.pid` value.

{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}

Response examples (200)

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "AtOJ4UjUBAAx3XR5kcCM",
            "_source": {
              "@timestamp": "2099-12-06T11:04:07.000Z",
              "event": {
                "category": "file",
                "id": "dGCHwoeS",
                "sequence": 2
              },
              "file": {
                "accessed": "2099-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "pid": 2012,
                "name": "cmd.exe",
                "executable": "C:\\Windows\\System32\\cmd.exe"
              }
            }
          },
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "OQmfCaduce8zoHT93o4H",
            "_source": {
              "@timestamp": "2099-12-07T11:07:09.000Z",
              "event": {
                "category": "process",
                "id": "aR3NWVOs",
                "sequence": 4
              },
              "process": {
                "pid": 2012,
                "name": "regsvr32.exe",
                "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
                "executable": "C:\\Windows\\System32\\regsvr32.exe"
              }
            }
          }
        ]
      }
    ]
  }
}

Run an async ES|QL query Generally available; Added in 8.13.0

POST /_query/async

Api key auth Basic auth Bearer auth

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.

Required authorization

Index privileges: read

External documentation

Query parameters

allow_partial_results boolean

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.
delimiter string

The character to use between values within a CSV row. It is valid only for the CSV format.
drop_null_columns boolean

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.
format string

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.

application/json

Body Required

columnar boolean

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.
filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
locale string
params array[number | string | boolean | null]

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.
profile boolean

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.
query string Required

The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
tables object

Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
Hide tables attribute Show tables attribute object
- * object Additional properties
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  integer array[number | array]
  
  One of:
  number-1 number array-2 array[number]
  
  keyword array[string | array]
  
  One of:
  string-1 string array-2 array[string]
  
  long array[number | array]
  
  One of:
  number-1 number array-2 array[number]
  
  double array[number | array]
  
  One of:
  number-1 number array-2 array[number]
include_ccs_metadata boolean

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.
wait_for_completion_timeout string

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.
keep_alive string

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.
keep_on_completion boolean

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- Time unit for milliseconds
- is_partial boolean
- all_columns array[object]
  
  Hide all_columns attributes Show all_columns attributes object
  
  name string Required
  
  type string Required
- columns array[object] Required
  
  Hide columns attributes Show columns attributes object
  
  name string Required
  
  type string Required
- values array[array] Required
  
  A field value.
  
  A field value.
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  total number Required
  
  successful number Required
  
  running number Required
  
  skipped number Required
  
  partial number Required
  
  failed number Required
  
  details object Required
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  Time unit for milliseconds
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  total number Required
  
  successful number
  
  skipped number
  
  failed number
  
  failures array[object]
- profile object
  
  Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.
- id string
  
  The ID of the async query, to be used in subsequent requests to check the status or retrieve results.
  
  Also available in the X-Elasticsearch-Async-Id HTTP header.
- is_running boolean Required
  
  Indicates whether the async query is still running or has completed.
  
  Also available in the X-Elasticsearch-Async-Is-Running HTTP header.

POST /_query/async

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"

Request example

{
  "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
}

Delete an async ES|QL query Generally available; Added in 8.13.0

DELETE /_query/async/{id}

Api key auth Basic auth Bearer auth

If the query is still running, it is cancelled. Otherwise, the stored results are deleted.

If the Elasticsearch security features are enabled, only the following users can use this API to delete a query:

The authenticated user that submitted the original query request
Users with the cancel_task cluster privilege

External documentation

Path parameters

id string Required

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.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_query/async/{id}

DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=

resp = client.esql.async_query_delete(
    id="FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
)

const response = await client.esql.asyncQueryDelete({
  id: "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
});

response = client.esql.async_query_delete(
  id: "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI="
)

$resp = $client->esql()->asyncQueryDelete([
    "id" => "FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI="

Get a specific running ES|QL query information Technical preview; Added in 9.1.0

GET /_query/queries/{id}

Api key auth Basic auth Bearer auth

Returns an object extended information about a running ES|QL query.

Required authorization

Cluster privileges: monitor_esql

Path parameters

id string Required

The query ID

Responses

200 application/json
Hide response attributes Show response attributes object
- id number Required
- node string Required
- start_time_millis number Required
- running_time_nanos number Required
- query string Required
- coordinating_node string Required
- data_nodes array[string] Required

GET /_query/queries/{id}

curl \
 --request GET 'http://api.example.com/_query/queries/{id}' \
 --header "Authorization: $API_KEY"

Run a Fleet search Technical preview; Added in 7.16.0

POST /{index}/_fleet/_fleet_search

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /{index}/_fleet/_fleet_search

POST /{index}/_fleet/_fleet_search

The purpose of the Fleet search API is to provide an API where the search will be run only after the provided checkpoint has been processed and is visible for searches inside of Elasticsearch.

Required authorization

Index privileges: read

Path parameters

index string Required

A single target to search. If the target is an index alias, it must resolve to a single index.

Query parameters

allow_no_indices boolean
analyzer string
analyze_wildcard boolean
batched_reduce_size number
ccs_minimize_roundtrips boolean
default_operator string

Values are and, AND, or, or OR.
df string
docvalue_fields string | array[string]
expand_wildcards string | array[string]
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.
explain boolean
ignore_throttled boolean
ignore_unavailable boolean
lenient boolean
max_concurrent_shard_requests number
preference string
pre_filter_shard_size number
request_cache boolean
routing string
scroll string

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.
search_type string
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.
stats array[string]
stored_fields string | array[string]
suggest_field string

Specifies which field to use for suggestions.
suggest_mode string
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.
suggest_size number
suggest_text string

The source text for which the suggestions should be returned.
terminate_after number
timeout string

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.
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.
track_scores boolean
typed_keys boolean
rest_total_hits_as_int boolean
version boolean
_source boolean | string | array[string]

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.
_source_excludes string | array[string]
_source_includes string | array[string]
seq_no_primary_term boolean
q string
size number
from number
sort string | array[string]
wait_for_checkpoints array[number]

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.
allow_partial_search_results boolean

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.

application/json

Body

aggregations object
collapse object
External documentation
explain boolean

If true, returns detailed information about score computation as part of a hit.

Default value is false.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

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.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 string-1 string string-2 string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
 
 Default value is .,!? \t\n.
- boundary_max_scan number
 
 How far to scan for boundary characters.
 
 Default value is 20.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 Default value is Locale.ROOT.
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
 
 Default value is 100.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 Default value is 0.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 Default value is 5.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 Default value is 256.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 Default value is true.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object | array[object] Required
 
 One of:
 object-1 object array-2 array[object]
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.
indices_boost array[object]

Boosts the _score of documents from specified indices.
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

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
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
min_score number

Minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.
post_filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
profile boolean
query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
rescore object | array[object]
One of:
object-2 object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

Default value is 1.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

Default value is 1.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
Hide attributes Show attributes object

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

Default value is 1.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

Default value is 1.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from number
  
  The starting document offset, which must be non-negative. 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.
  
  highlight object
  
  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.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  External documentation
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field 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
  
  External documentation
  
  A reference to a field with formatting instructions on how to return the value
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  rescorer
  
  linear
  
  pinned
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. 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 property.
  
  Default value is 10.
  
  slice object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  fields array[object]
  
  An array of wildcard (*) field 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
  
  A reference to a field with formatting instructions on how to return the value
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  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 property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  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.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive string
  
  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.
  
  runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  stats array[string]
  
  The 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.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

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.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object array-2 array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source string | object

One of:
string-1 string SearchRequestBody object

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

Hide params attribute Show params attribute object

* object Additional properties

lang string

Any of:
string-1 string string-2 string

Values are painless, expression, mustache, or java.

options object

Hide options attribute Show options attribute object

* string Additional properties

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
boolean-1 boolean SourceFilter object
Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]
fields array[object]

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
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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.
timeout string

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.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.

Default value is false.
version boolean

If true, returns document version as part of a hit.

Default value is false.
seq_no_primary_term boolean

If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  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.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from number
  
  The starting document offset, which must be non-negative. 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.
  
  highlight object
  
  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.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  External documentation
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field 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
  
  External documentation
  
  A reference to a field with formatting instructions on how to return the value
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  rescorer
  
  linear
  
  pinned
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. 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 property.
  
  Default value is 10.
  
  slice object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  fields array[object]
  
  An array of wildcard (*) field 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
  
  A reference to a field with formatting instructions on how to return the value
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  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 property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  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.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive string
  
  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.
  
  runtime_mappings object
  
  stats array[string]
  
  The 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.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- timed_out boolean Required
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object | number
  
  Total hit count information, present only if track_total_hits wasn't false in the search request.
  
  One of:
  TotalHits object number-2 number
  
  Hide attributes Show attributes
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  hits array[object] Required
  
  Hide hits attributes Show hits attributes object
  
  _index string Required
  
  _id string
  
  _score number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  _explanation object
  
  Hide _explanation attributes Show _explanation attributes object
  
  description string Required
  
  details array[object] Required
  
  value number Required
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  * array[string] Additional properties
  
  inner_hits object
  
  Hide inner_hits attribute Show inner_hits attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  hits object Required
  
  matched_queries array[string] | object
  
  One of:
  array-1 array[string] object-2 object
  
  _nested object
  
  Hide _nested attributes Show _nested attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  offset number Required
  
  _nested object
  
  _ignored array[string]
  
  ignored_field_values object
  
  Hide ignored_field_values attribute Show ignored_field_values attribute object
  
  * array[object] Additional properties
  
  _shard string
  
  _node string
  
  _routing string
  
  _source object
  
  _rank number
  
  _seq_no number
  
  _primary_term number
  
  _version number
  
  sort array[number | string | boolean | null]
  
  A field value.
  
  max_score number | string | null
  
  One of:
  number-1 number string-2 string | null
- aggregations object
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  took number
  
  Time unit for milliseconds
  
  timed_out boolean Required
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
- fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
- max_score number
- num_reduce_phases number
- profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  Hide shards attributes Show shards attributes object
  
  aggregations array[object] Required
  
  Hide aggregations attributes Show aggregations attributes object
  
  breakdown object Required
  
  description string Required
  
  time_in_nanos
  
  type string Required
  
  debug object
  
  children array[object]
  
  cluster string Required
  
  dfs object
  
  Hide dfs attributes Show dfs attributes object
  
  statistics object
  
  Hide statistics attributes Show statistics attributes object
  
  type string Required
  
  description string Required
  
  time string
  
  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.
  
  time_in_nanos
  
  breakdown object Required
  
  debug object
  
  children array[object]
  
  knn array[object]
  
  fetch object
  
  Hide fetch attributes Show fetch attributes object
  
  type string Required
  
  description string Required
  
  time_in_nanos number
  
  Time unit for nanoseconds
  
  breakdown object Required
  
  Hide breakdown attributes Show breakdown attributes object
  
  load_source number
  
  load_source_count number
  
  load_stored_fields number
  
  load_stored_fields_count number
  
  next_reader number
  
  next_reader_count number
  
  process_count number
  
  process number
  
  debug object
  
  Hide debug attributes Show debug attributes object
  
  stored_fields array[string]
  
  fast_path number
  
  children array[object]
  
  id string Required
  
  index string Required
  
  node_id string Required
  
  searches array[object] Required
  
  Hide searches attributes Show searches attributes object
  
  collector array[object] Required
  
  query array[object] Required
  
  rewrite_time number Required
  
  shard_id number Required
- pit_id string
- _scroll_id string
- suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  One of:
  object-2 object object-2 object object-2 object
  
  Hide attributes Show attributes
  
  length number Required
  
  offset number Required
  
  text string Required
  
  options
  
  Hide attributes Show attributes
  
  length number Required
  
  offset number Required
  
  text string Required
  
  options
  
  Hide attributes Show attributes
  
  length number Required
  
  offset number Required
  
  text string Required
  
  options
- terminated_early boolean

POST /{index}/_fleet/_fleet_search

curl \
 --request POST 'http://api.example.com/{index}/_fleet/_fleet_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"aggregations":{},"collapse":{},"explain":false,"ext":{"additionalProperty1":{},"additionalProperty2":{}},"from":0,"highlight":{"":"plain","boundary_chars":".,!? \\t\\n","boundary_max_scan":20,"boundary_scanner":"chars","boundary_scanner_locale":"Locale.ROOT","force_source":true,"fragmenter":"simple","fragment_size":100,"highlight_filter":true,"highlight_query":{},"max_fragment_length":42.0,"max_analyzed_offset":42.0,"no_match_size":0,"number_of_fragments":5,"options":{"additionalProperty1":{},"additionalProperty2":{}},"order":"score","phrase_limit":256,"post_tags":["string"],"pre_tags":["string"],"require_field_match":true,"tags_schema":"styled","encoder":"default","fields":{}},"track_total_hits":true,"indices_boost":[{"additionalProperty1":42.0,"additionalProperty2":42.0}],"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"min_score":42.0,"post_filter":{},"profile":true,"query":{},"rescore":{"window_size":42.0,"query":{"rescore_query":{},"query_weight":1,"rescore_query_weight":1,"score_mode":"avg"},"learning_to_rank":{"model_id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}}}},"script_fields":{"additionalProperty1":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"search_after":[42.0],"size":10,"slice":{"field":"string","id":"string","max":42.0},"":true,"fields":[{"field":"string","format":"string","include_unmapped":true}],"suggest":{"text":"string"},"terminate_after":0,"timeout":"string","track_scores":false,"version":false,"seq_no_primary_term":true,"stored_fields":"string","pit":{"id":"string","keep_alive":"string"},"runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","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":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"stats":["string"]}'

Import a dangling index Generally available; Added in 7.9.0

POST /_dangling/{index_uuid}

Api key auth Basic auth Bearer auth

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.

Required authorization

Cluster privileges: manage

Path parameters

index_uuid string Required

The UUID of the index to import. Use the get dangling indices API to locate the UUID.

Query parameters

accept_data_loss boolean Required

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.
master_timeout string

Specify timeout for connection to master

Values are -1 or 0.
timeout string

Explicit operation timeout

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_dangling/{index_uuid}

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")
);

Response examples (200)

A successful response from `POST /_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true`.

{
  "acknowledged": true
}

Get tokens from text analysis Generally available

POST /{index}/_analyze

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_analyze

POST /_analyze

GET /{index}/_analyze

POST /{index}/_analyze

The analyze API performs analysis on a text string and returns the resulting tokens.

Generating excessive amount of tokens may cause a node to run out of memory. The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. If more than this limit of tokens gets generated, an error occurs. The _analyze endpoint without a specified index will always use 10000 as its limit.

Required authorization

Index privileges: index

External documentation

Path parameters

index string Required

Index used to derive the analyzer. If specified, the analyzer or field parameter overrides this value. If no index is specified or the index does not have a default analyzer, the analyze API uses the standard analyzer.

Query parameters

index string

Index used to derive the analyzer. If specified, the analyzer or field parameter overrides this value. If no index is specified or the index does not have a default analyzer, the analyze API uses the standard analyzer.

application/json

Body

analyzer string

The name of the analyzer that should be applied to the provided text. This could be a built-in analyzer, or an analyzer that’s been configured in the index.
attributes array[string]

Array of token attributes used to filter the output of the explain parameter.
char_filter array

Array of character filters used to preprocess characters before the tokenizer.

External documentation
explain boolean

If true, the response includes token attributes and additional details.

Default value is false.
field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
filter array

Array of token filters used to apply after the tokenizer.

External documentation
normalizer string

Normalizer to use to convert text into a single token.
text string | array[string]

One of:
string-1 string array-2 array[string]

Responses

200 application/json
Hide response attributes Show response attributes object
- detail object
  
  Hide detail attributes Show detail attributes object
  
  analyzer object
  
  Hide analyzer attributes Show analyzer attributes object
  
  name string Required
  
  tokens array[object] Required
  
  Hide tokens attributes Show tokens attributes object
  
  bytes string Required
  
  end_offset number Required
  
  keyword boolean
  
  position number Required
  
  positionLength number Required
  
  start_offset number Required
  
  termFrequency number Required
  
  token string Required
  
  type string Required
  
  charfilters array[object]
  
  Hide charfilters attributes Show charfilters attributes object
  
  filtered_text array[string] Required
  
  name string Required
  
  custom_analyzer boolean Required
  
  tokenfilters array[object]
  
  Hide tokenfilters attributes Show tokenfilters attributes object
  
  name string Required
  
  tokens array[object] Required
  
  Hide tokens attributes Show tokens attributes object
  
  bytes string Required
  
  end_offset number Required
  
  keyword boolean
  
  position number Required
  
  positionLength number Required
  
  start_offset number Required
  
  termFrequency number Required
  
  token string Required
  
  type string Required
  
  tokenizer object
  
  Hide tokenizer attributes Show tokenizer attributes object
  
  name string Required
  
  tokens array[object] Required
  
  Hide tokens attributes Show tokens attributes object
  
  bytes string Required
  
  end_offset number Required
  
  keyword boolean
  
  position number Required
  
  positionLength number Required
  
  start_offset number Required
  
  termFrequency number Required
  
  token string Required
  
  type string Required
- tokens array[object]
  
  Hide tokens attributes Show tokens attributes object
  
  end_offset number Required
  
  position number Required
  
  positionLength number
  
  start_offset number Required
  
  token string Required
  
  type string Required

POST /{index}/_analyze

GET /_analyze
{
  "analyzer": "standard",
  "text": "this is a test"
}

resp = client.indices.analyze(
    analyzer="standard",
    text="this is a test",
)

const response = await client.indices.analyze({
  analyzer: "standard",
  text: "this is a test",
});

response = client.indices.analyze(
  body: {
    "analyzer": "standard",
    "text": "this is a test"
  }
)

$resp = $client->indices()->analyze([
    "body" => [
        "analyzer" => "standard",
        "text" => "this is a test",
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"analyzer":"standard","text":"this is a test"}' "$ELASTICSEARCH_URL/_analyze"

client.indices().analyze(a -> a
    .analyzer("standard")
    .text("this is a test")
);

Request examples

You can apply any of the built-in analyzers to the text string without specifying an index.

{
  "analyzer": "standard",
  "text": "this is a test"
}

If the text parameter is provided as array of strings, it is analyzed as a multi-value field.

{
  "analyzer": "standard",
  "text": [
    "this is a test",
    "the second text"
  ]
}

You can test a custom transient analyzer built from tokenizers, token filters, and char filters. Token filters use the filter parameter.

{
  "tokenizer": "keyword",
  "filter": [
    "lowercase"
  ],
  "char_filter": [
    "html_strip"
  ],
  "text": "this is a <b>test</b>"
}

Custom tokenizers, token filters, and character filters can be specified in the request body.

{
  "tokenizer": "whitespace",
  "filter": [
    "lowercase",
    {
      "type": "stop",
      "stopwords": [
        "a",
        "is",
        "this"
      ]
    }
  ],
  "text": "this is a test"
}

Run `GET /analyze_sample/_analyze` to run an analysis on the text using the default index analyzer associated with the `analyze_sample` index. Alternatively, the analyzer can be derived based on a field mapping.

{
  "field": "obj1.field1",
  "text": "this is a test"
}

Run `GET /analyze_sample/_analyze` and supply a normalizer for a keyword field if there is a normalizer associated with the specified index.

{
  "normalizer": "my_normalizer",
  "text": "BaR"
}

If you want to get more advanced details, set `explain` to `true`. It will output all token attributes for each token. You can filter token attributes you want to output by setting the `attributes` option. NOTE: The format of the additional detail information is labelled as experimental in Lucene and it may change in the future.

{
  "tokenizer": "standard",
  "filter": [
    "snowball"
  ],
  "text": "detailed output",
  "explain": true,
  "attributes": [
    "keyword"
  ]
}

Response examples (200)

A successful response for an analysis with `explain` set to `true`.

{
  "detail": {
    "custom_analyzer": true,
    "charfilters": [],
    "tokenizer": {
      "name": "standard",
      "tokens": [
        {
          "token": "detailed",
          "start_offset": 0,
          "end_offset": 8,
          "type": "<ALPHANUM>",
          "position": 0
        },
        {
          "token": "output",
          "start_offset": 9,
          "end_offset": 15,
          "type": "<ALPHANUM>",
          "position": 1
        }
      ]
    },
    "tokenfilters": [
      {
        "name": "snowball",
        "tokens": [
          {
            "token": "detail",
            "start_offset": 0,
            "end_offset": 8,
            "type": "<ALPHANUM>",
            "position": 0,
            "keyword": false
          },
          {
            "token": "output",
            "start_offset": 9,
            "end_offset": 15,
            "type": "<ALPHANUM>",
            "position": 1,
            "keyword": false
          }
        ]
      }
    ]
  }
}

Get index information Generally available

GET /{index}

Api key auth Basic auth Bearer auth

Get information about one or more indices. For data streams, the API returns information about the stream’s backing indices.

Required authorization

Index privileges: view_index_metadata,manage

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.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. 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.
flat_settings boolean

If true, returns settings in flat format.
ignore_unavailable boolean

If false, requests that target a missing index return an error.
include_defaults boolean

If true, return all default settings in the response.
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.

Values are -1 or 0.
features string | array[string] Generally available; Added in 8.1.0

Return only information on specified index features

Supported values include: aliases, mappings, settings

Values are aliases, mappings, or settings.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object
  
  Hide * attributes Show * attributes object
  
  aliases object
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  search_routing string
  
  mappings object
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
  
  settings object
  Index settings
  
  defaults object
  Index settings
  
  data_stream string
  
  lifecycle object
  
  Data stream lifecycle denotes that a data stream is managed by the data stream lifecycle and contains the configuration.
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention string
  
  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.
  
  downsampling object
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  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.
  
  config object Required
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.

GET /{index}

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")
);

Delete an alias Generally available

DELETE /{index}/_aliases/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

DELETE /{index}/_alias/{name}

DELETE /{index}/_aliases/{name}

Removes a data stream or index from an alias.

Required authorization

Index privileges: manage

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*).
name string | array[string] Required

Comma-separated list of aliases to remove. Supports wildcards (*). To remove all aliases, use * or _all.

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.

Values are -1 or 0.
timeout string

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- errors boolean

DELETE /{index}/_aliases/{name}

DELETE my-data-stream/_alias/my-alias

resp = client.indices.delete_alias(
    index="my-data-stream",
    name="my-alias",
)

const response = await client.indices.deleteAlias({
  index: "my-data-stream",
  name: "my-alias",
});

response = client.indices.delete_alias(
  index: "my-data-stream",
  name: "my-alias"
)

$resp = $client->indices()->deleteAlias([
    "index" => "my-data-stream",
    "name" => "my-alias",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-data-stream/_alias/my-alias"

client.indices().deleteAlias(d -> d
    .index("my-data-stream")
    .name("my-alias")
);

Get legacy index templates Deprecated Generally available

GET /_template/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_template

GET /_template/{name}

Get information about one or more index templates.

IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

Required authorization

Cluster privileges: manage_index_templates

External documentation

Path parameters

name string | array[string] Required

Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. To return all index templates, omit this parameter or use a value of _all or *.

Query parameters

flat_settings boolean

If true, returns settings in flat format.
local boolean

If true, the request retrieves information from the local node only.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attributes Show * attributes object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  search_routing string
  
  index_patterns array[string] Required
  
  mappings object Required
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
  
  order number Required
  
  settings object Required
  
  Hide settings attribute Show settings attribute object
  
  * object Additional properties
  
  version number

GET /_template/{name}

GET /_template/.monitoring-*

resp = client.indices.get_template(
    name=".monitoring-*",
)

const response = await client.indices.getTemplate({
  name: ".monitoring-*",
});

response = client.indices.get_template(
  name: ".monitoring-*"
)

$resp = $client->indices()->getTemplate([
    "name" => ".monitoring-*",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_template/.monitoring-*"

client.indices().getTemplate(g -> g
    .name(".monitoring-*")
);

Get mapping definitions Generally available

GET /{index}/_mapping/field/{fields}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_mapping/field/{fields}

GET /{index}/_mapping/field/{fields}

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.

Required authorization

Index privileges: view_index_metadata

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 _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

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.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
include_defaults boolean

If true, return all default settings in the response.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  mappings object Required
  
  Hide mappings attribute Show mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  full_name string Required
  
  mapping object Required

GET /{index}/_mapping/field/{fields}

GET publications/_mapping/field/title

resp = client.indices.get_field_mapping(
    index="publications",
    fields="title",
)

const response = await client.indices.getFieldMapping({
  index: "publications",
  fields: "title",
});

response = client.indices.get_field_mapping(
  index: "publications",
  fields: "title"
)

$resp = $client->indices()->getFieldMapping([
    "index" => "publications",
    "fields" => "title",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/publications/_mapping/field/title"

client.indices().getFieldMapping(g -> g
    .fields("title")
    .index("publications")
);

Response examples (200)

A sucessful response from `GET publications/_mapping/field/title`, which returns the mapping of a field called `title`.

{
   "publications": {
      "mappings": {
          "title": {
             "full_name": "title",
             "mapping": {
                "title": {
                   "type": "text"
                }
             }
          }
       }
   }
}

A successful response from `GET publications/_mapping/field/author.id,abstract,name`. The get field mapping API also supports wildcard notation.

{
   "publications": {
      "mappings": {
        "author.id": {
           "full_name": "author.id",
           "mapping": {
              "id": {
                 "type": "text"
              }
           }
        },
        "abstract": {
           "full_name": "abstract",
           "mapping": {
              "abstract": {
                 "type": "text"
              }
           }
        }
     }
   }
}

A successful response from `GET publications/_mapping/field/a*`.

{
   "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"
               }
            }
         }
      }
   }
}

Get index segments Generally available

GET /{index}/_segments

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_segments

GET /{index}/_segments

Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the stream's backing indices.

Required authorization

Index privileges: monitor

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 _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

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.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.

Responses

200 application/json
Hide response attributes Show response attributes object
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  shards object Required
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number

GET /{index}/_segments

GET /my-index-000001/_segments

resp = client.indices.segments(
    index="my-index-000001",
)

const response = await client.indices.segments({
  index: "my-index-000001",
});

response = client.indices.segments(
  index: "my-index-000001"
)

$resp = $client->indices()->segments([
    "index" => "my-index-000001",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_segments"

client.indices().segments(s -> s
    .index("my-index-000001")
);

Response examples (200)

A successful response for creating a new index for a data stream.

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-my-data-stream-2099.05.06-000001",
  "new_index": ".ds-my-data-stream-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

Get index shard stores Generally available

GET /{index}/_shard_stores

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_shard_stores

GET /{index}/_shard_stores

Get store information about replica shards in one or more indices. For data streams, the API retrieves store information for the stream's backing indices.

The index shard stores API returns the following information:

The node on which each replica shard exists.
The allocation ID for each replica shard.
A unique ID for each replica shard.
Any errors encountered while opening the shard index or from an earlier failure.

By default, the API returns store information only for primary shards that are unassigned or have one or more unassigned replica shards.

Required authorization

Index privileges: monitor

Path parameters

index string | array[string] Required

List of data streams, indices, and aliases used to limit the request.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

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.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
status string | array[string]
List of shard health statuses used to limit the request.

Supported values include:
- green: The primary shard and all replica shards are assigned.
- yellow: One or more replica shards are unassigned.
- red: The primary shard is unassigned.
- all: Return all shards, regardless of health status.
Values are green, yellow, red, or all.

Responses

200 application/json
Hide response attribute Show response attribute object
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  shards object Required
  
  Hide shards attribute Show shards attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  stores array[object] Required

GET /{index}/_shard_stores

GET /_shard_stores?status=green

resp = client.indices.shard_stores(
    status="green",
)

const response = await client.indices.shardStores({
  status: "green",
});

response = client.indices.shard_stores(
  status: "green"
)

$resp = $client->indices()->shardStores([
    "status" => "green",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_shard_stores?status=green"

Response examples (200)

An abbreviated response from `GET /_shard_stores?status=green`.

{
  "indices": {
    "my-index-000001": {
      "shards": {
        "0": {
          "stores": [
            {
              "sPa3OgxLSYGvQ4oPs-Tajw": {
                "name": "node_t0",
                "ephemeral_id": "9NlXRFGCT1m8tkvYCMK-8A",
                "transport_address": "local[1]",
                "external_id": "node_t0",
                "attributes": {},
                "roles": [],
                "version": "8.10.0",
                "min_index_version": 7000099,
                "max_index_version": 8100099
              },
              "allocation_id": "2iNySv_OQVePRX-yaRH_lQ",
              "allocation": "primary",
              "store_exception": {}
            }
          ]
        }
      }
    }
  }
}

Shrink an index Generally available; Added in 5.0.0

POST /{index}/_shrink/{target}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /{index}/_shrink/{target}

POST /{index}/_shrink/{target}

Shrink an index into a new index with fewer primary shards.

Before you can shrink an index:

The index must be read-only.
A copy of every shard in the index must reside on the same node.
The index must have a green health status.

To make shard allocation easier, we recommend you also remove the index's replica shards. You can later re-add replica shards as part of the shrink operation.

The requested number of primary shards in the target index must be a factor of the number of shards in the source index. For example an index with 8 primary shards can be shrunk into 4, 2 or 1 primary shards or an index with 15 primary shards can be shrunk into 5, 3 or 1. If the number of shards in the index is a prime number it can only be shrunk into a single primary shard Before shrinking, a (primary or replica) copy of every shard in the index must be present on the same node.

The current write index on a data stream cannot be shrunk. In order to shrink 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 shrunk.

A shrink operation:

Creates a new target index with the same definition as the source index, but with a smaller number of primary shards.
Hard-links segments from the source index into the target index. If the file system does not support hard-linking, then all segments are copied into the new index, which is a much more time consuming process. Also if using multiple data paths, shards on different data paths require a full copy of segment files if they are not on the same disk since hardlinks do not work across disks.
Recovers the target index as though it were a closed index which had just been re-opened. Recovers shards to the .routing.allocation.initial_recovery._id index setting.

IMPORTANT: Indices can only be shrunk if they satisfy the following requirements:

The target index must not exist.
The source index must have more primary shards than the target index.
The number of primary shards in the target index must be a factor of the number of primary shards in the source index. The source index must have more primary shards than the target index.
The index must not contain more than 2,147,483,519 documents in total across all shards that will be shrunk into a single shard on the target index as this is the maximum number of docs that can fit into a single shard.
The node handling the shrink process must have sufficient free disk space to accommodate a second copy of the existing index.

Required authorization

Index privileges: manage

Path parameters

index string Required

Name of the source index to shrink.
target string Required

Name of the target index to create.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Values are all or index-setting.

application/json

Body

aliases object

The key is the alias name. Index alias names support date math.
Hide aliases attribute Show aliases attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  search_routing string
settings object

Configuration options for the target index.
Hide settings attribute Show settings attribute object
- * object Additional properties

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- shards_acknowledged boolean Required
- index string Required

POST /{index}/_shrink/{target}

POST /my_source_index/_shrink/my_target_index
{
  "settings": {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null
  }
}

resp = client.indices.shrink(
    index="my_source_index",
    target="my_target_index",
    settings={
        "index.routing.allocation.require._name": None,
        "index.blocks.write": None
    },
)

const response = await client.indices.shrink({
  index: "my_source_index",
  target: "my_target_index",
  settings: {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null,
  },
});

response = client.indices.shrink(
  index: "my_source_index",
  target: "my_target_index",
  body: {
    "settings": {
      "index.routing.allocation.require._name": nil,
      "index.blocks.write": nil
    }
  }
)

$resp = $client->indices()->shrink([
    "index" => "my_source_index",
    "target" => "my_target_index",
    "body" => [
        "settings" => [
            "index.routing.allocation.require._name" => null,
            "index.blocks.write" => null,
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"settings":{"index.routing.allocation.require._name":null,"index.blocks.write":null}}' "$ELASTICSEARCH_URL/my_source_index/_shrink/my_target_index"

client.indices().shrink(s -> s
    .index("my_source_index")
    .settings(Map.of("index.blocks.write", JsonData.fromJson("null"),"index.routing.allocation.require._name", JsonData.fromJson("null")))
    .target("my_target_index")
);

Request example

{
  "settings": {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null
  }
}

Create a AI21 inference endpoint Generally available; Added in 9.2.0

PUT /_inference/{task_type}/{ai21_inference_id}

Api key auth Basic auth Bearer auth

Create an inference endpoint to perform an inference task with the ai21 service.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform.

Values are completion or chat_completion.
ai21_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

service string Required

Value is ai21.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- model_id string Required
  The name of the model to use for the inference task. Refer to the AI21 models documentation for the list of supported models and versions. Service has been tested and confirmed to be working for completion and chat_completion tasks with the following models:
  
  jamba-mini
  
  jamba-large
  External documentation
- api_key string
  
  A valid API key for accessing AI21 API.
  
  IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.
- rate_limit object
  
  This setting helps to minimize the number of rate limit errors returned from the service.
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute. By default, the number of requests allowed per minute is set by each service as follows:
  
  alibabacloud-ai-search service: 1000
  
  anthropic service: 50
  
  azureaistudio service: 240
  
  azureopenai service and task type text_embedding: 1440
  
  azureopenai service and task type completion: 120
  
  cohere service: 10000
  
  elastic service and task type chat_completion: 240
  
  googleaistudio service: 360
  
  googlevertexai service: 30000
  
  hugging_face service: 3000
  
  jinaai service: 2000
  
  llama service: 3000
  
  mistral service: 240
  
  openai service and task type text_embedding: 3000
  
  openai service and task type completion: 500
  
  voyageai service: 2000
  
  watsonxai service: 120

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string Required
  
  This parameter is only applicable when using the recursive chunking strategy.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string] Required
  
  A list of strings used as possible split points when chunking text with the recursive strategy.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
- task_settings object
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  Values are completion or chat_completion.

PUT /_inference/{task_type}/{ai21_inference_id}

PUT _inference/completion/ai21-completion
{
  "service": "ai21",
  "service_settings": {
    "api_key": "ai21-api-key",
    "model_id": "jamba-large" 
  }
}

resp = client.inference.put(
    task_type="completion",
    inference_id="ai21-completion",
    inference_config={
        "service": "ai21",
        "service_settings": {
            "api_key": "ai21-api-key",
            "model_id": "jamba-large"
        }
    },
)

const response = await client.inference.put({
  task_type: "completion",
  inference_id: "ai21-completion",
  inference_config: {
    service: "ai21",
    service_settings: {
      api_key: "ai21-api-key",
      model_id: "jamba-large",
    },
  },
});

response = client.inference.put(
  task_type: "completion",
  inference_id: "ai21-completion",
  body: {
    "service": "ai21",
    "service_settings": {
      "api_key": "ai21-api-key",
      "model_id": "jamba-large"
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "completion",
    "inference_id" => "ai21-completion",
    "body" => [
        "service" => "ai21",
        "service_settings" => [
            "api_key" => "ai21-api-key",
            "model_id" => "jamba-large",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"ai21","service_settings":{"api_key":"ai21-api-key","model_id":"jamba-large"}}' "$ELASTICSEARCH_URL/_inference/completion/ai21-completion"

Request examples

Run `PUT _inference/completion/ai21-completion` to create an AI21 inference endpoint that performs a `completion` task.

{
  "service": "ai21",
  "service_settings": {
    "api_key": "ai21-api-key",
    "model_id": "jamba-large" 
  }
}

Run `PUT _inference/chat-completion/ai21-chat-completion` to create a AI21 inference endpoint that performs a `chat_completion` task.

{
  "service": "ai21",
  "service_settings": {
    "api_key": "ai21-api-key",
    "model_id": "jamba-mini" 
  }
}

Create an Anthropic inference endpoint Generally available; Added in 8.16.0

PUT /_inference/{task_type}/{anthropic_inference_id}

Api key auth Basic auth Bearer auth

Create an inference endpoint to perform an inference task with the anthropic service.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The task type. The only valid task type for the model to perform is completion.

Value is completion.
anthropic_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

chunking_settings object

Chunking configuration object
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
- separator_group string Required
  
  This parameter is only applicable when using the recursive chunking strategy.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
- separators array[string] Required
  
  A list of strings used as possible split points when chunking text with the recursive strategy.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
- strategy string
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  Default value is sentence.
  
  External documentation
service string Required

Value is anthropic.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- api_key string Required
  
  A valid API key for the Anthropic API.
- model_id string Required
  
  The name of the model to use for the inference task. Refer to the Anthropic documentation for the list of supported models.
- rate_limit object
  
  This setting helps to minimize the number of rate limit errors returned from the service.
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute. By default, the number of requests allowed per minute is set by each service as follows:
  
  alibabacloud-ai-search service: 1000
  
  anthropic service: 50
  
  azureaistudio service: 240
  
  azureopenai service and task type text_embedding: 1440
  
  azureopenai service and task type completion: 120
  
  cohere service: 10000
  
  elastic service and task type chat_completion: 240
  
  googleaistudio service: 360
  
  googlevertexai service: 30000
  
  hugging_face service: 3000
  
  jinaai service: 2000
  
  llama service: 3000
  
  mistral service: 240
  
  openai service and task type text_embedding: 3000
  
  openai service and task type completion: 500
  
  voyageai service: 2000
  
  watsonxai service: 120
task_settings object
Hide task_settings attributes Show task_settings attributes object
- max_tokens number Required
  
  For a completion task, it is the maximum number of tokens to generate before stopping.
- temperature number
  
  For a completion task, it is the amount of randomness injected into the response. For more details about the supported range, refer to Anthropic documentation.
  
  External documentation
- top_k number
  
  For a completion task, it specifies to only sample from the top K options for each subsequent token. It is recommended for advanced use cases only. You usually only need to use temperature.
- top_p number
  
  For a completion task, it specifies to use Anthropic's nucleus sampling. In nucleus sampling, Anthropic computes the cumulative distribution over all the options for each subsequent token in decreasing probability order and cuts it off once it reaches the specified probability. You should either alter temperature or top_p, but not both. It is recommended for advanced use cases only. You usually only need to use temperature.

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string Required
  
  This parameter is only applicable when using the recursive chunking strategy.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string] Required
  
  A list of strings used as possible split points when chunking text with the recursive strategy.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
- task_settings object
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  Value is completion.

PUT /_inference/{task_type}/{anthropic_inference_id}

PUT _inference/completion/anthropic_completion
{
    "service": "anthropic",
    "service_settings": {
        "api_key": "Anthropic-Api-Key",
        "model_id": "Model-ID"
    },
    "task_settings": {
        "max_tokens": 1024
    }
}

resp = client.inference.put(
    task_type="completion",
    inference_id="anthropic_completion",
    inference_config={
        "service": "anthropic",
        "service_settings": {
            "api_key": "Anthropic-Api-Key",
            "model_id": "Model-ID"
        },
        "task_settings": {
            "max_tokens": 1024
        }
    },
)

const response = await client.inference.put({
  task_type: "completion",
  inference_id: "anthropic_completion",
  inference_config: {
    service: "anthropic",
    service_settings: {
      api_key: "Anthropic-Api-Key",
      model_id: "Model-ID",
    },
    task_settings: {
      max_tokens: 1024,
    },
  },
});

response = client.inference.put(
  task_type: "completion",
  inference_id: "anthropic_completion",
  body: {
    "service": "anthropic",
    "service_settings": {
      "api_key": "Anthropic-Api-Key",
      "model_id": "Model-ID"
    },
    "task_settings": {
      "max_tokens": 1024
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "completion",
    "inference_id" => "anthropic_completion",
    "body" => [
        "service" => "anthropic",
        "service_settings" => [
            "api_key" => "Anthropic-Api-Key",
            "model_id" => "Model-ID",
        ],
        "task_settings" => [
            "max_tokens" => 1024,
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"anthropic","service_settings":{"api_key":"Anthropic-Api-Key","model_id":"Model-ID"},"task_settings":{"max_tokens":1024}}' "$ELASTICSEARCH_URL/_inference/completion/anthropic_completion"

client.inference().put(p -> p
    .inferenceId("anthropic_completion")
    .taskType(TaskType.Completion)
    .inferenceConfig(i -> i
        .service("anthropic")
        .serviceSettings(JsonData.fromJson("{\"api_key\":\"Anthropic-Api-Key\",\"model_id\":\"Model-ID\"}"))
        .taskSettings(JsonData.fromJson("{\"max_tokens\":1024}"))
    )
);

Request example

Run `PUT _inference/completion/anthropic_completion` to create an inference endpoint that performs a completion task.

{
    "service": "anthropic",
    "service_settings": {
        "api_key": "Anthropic-Api-Key",
        "model_id": "Model-ID"
    },
    "task_settings": {
        "max_tokens": 1024
    }
}

Create an Elasticsearch inference endpoint Generally available; Added in 8.13.0

PUT /_inference/{task_type}/{elasticsearch_inference_id}

Api key auth Basic auth Bearer auth

Create an inference endpoint to perform an inference task with the elasticsearch service.

Your Elasticsearch deployment contains preconfigured ELSER and E5 inference endpoints, you only need to create the enpoints using the API if you want to customize the settings.

If you use the ELSER or the E5 model through the elasticsearch service, the API request will automatically download and deploy the model if it isn't downloaded yet.

You might see a 502 bad gateway error in the response when using the Kibana Console. This error usually just reflects a timeout, while the model downloads in the background. You can check the download progress in the Machine Learning UI. If using the Python client, you can set the timeout parameter to a higher value.

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.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform.

Values are rerank, sparse_embedding, or text_embedding.
elasticsearch_inference_id string Required

The unique identifier of the inference endpoint. The must not match the model_id.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

chunking_settings object

Chunking configuration object
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
- separator_group string Required
  
  This parameter is only applicable when using the recursive chunking strategy.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
- separators array[string] Required
  
  A list of strings used as possible split points when chunking text with the recursive strategy.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
- strategy string
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  Default value is sentence.
  
  External documentation
service string Required

Value is elasticsearch.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- adaptive_allocations object
  Hide adaptive_allocations attributes Show adaptive_allocations attributes object
  
  enabled boolean
  
  Turn on adaptive_allocations.
  
  Default value is false.
  
  max_number_of_allocations number
  
  The maximum number of allocations to scale to. If set, it must be greater than or equal to min_number_of_allocations.
  
  min_number_of_allocations number
  
  The minimum number of allocations to scale to. If set, it must be greater than or equal to 0. If not defined, the deployment scales to 0.
- deployment_id string
  
  The deployment identifier for a trained model deployment. When deployment_id is used the model_id is optional.
- model_id string Required
  
  The name of the model to use for the inference task. It can be the ID of a built-in model (for example, .multilingual-e5-small for E5) or a text embedding model that was uploaded by using the Eland client.
  
  External documentation
- num_allocations number
  
  The total number of allocations that are assigned to the model across machine learning nodes. Increasing this value generally increases the throughput. If adaptive allocations are enabled, do not set this value because it's automatically set.
- num_threads number Required
  
  The number of threads used by each model allocation during inference. This setting generally increases the speed per inference request. The inference process is a compute-bound process; threads_per_allocations must not exceed the number of available allocated processors per node. The value must be a power of 2. The maximum value is 32.
task_settings object
Hide task_settings attribute Show task_settings attribute object
- return_documents boolean
  
  For a rerank task, return the document instead of only the index.
  
  Default value is true.

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  separator_group string Required
  
  This parameter is only applicable when using the recursive chunking strategy.
  
  Sets a predefined list of separators in the saved chunking settings based on the selected text type. Values can be markdown or plaintext.
  
  Using this parameter is an alternative to manually specifying a custom separators list.
  
  separators array[string] Required
  
  A list of strings used as possible split points when chunking text with the recursive strategy.
  
  Each string can be a plain string or a regular expression (regex) pattern. The system tries each separator in order to split the text, starting from the first item in the list.
  
  After splitting, it attempts to recombine smaller pieces into larger chunks that stay within the max_chunk_size limit, to reduce the total number of chunks generated.
  
  strategy string
  
  The chunking strategy: sentence, word, none or recursive.
  
  If strategy is set to recursive, you must also specify:
  
  max_chunk_size
  
  either separators orseparator_group
  
  Learn more about different chunking strategies in the linked documentation.
  
  Default value is sentence.
  
  External documentation
- service string Required
  
  The service type
- service_settings object Required
- task_settings object
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  Values are sparse_embedding, text_embedding, or rerank.

PUT /_inference/{task_type}/{elasticsearch_inference_id}

PUT _inference/sparse_embedding/my-elser-model
{
    "service": "elasticsearch",
    "service_settings": {
        "adaptive_allocations": { 
        "enabled": true,
        "min_number_of_allocations": 1,
        "max_number_of_allocations": 4
        },
        "num_threads": 1,
        "model_id": ".elser_model_2" 
    }
}

resp = client.inference.put(
    task_type="sparse_embedding",
    inference_id="my-elser-model",
    inference_config={
        "service": "elasticsearch",
        "service_settings": {
            "adaptive_allocations": {
                "enabled": True,
                "min_number_of_allocations": 1,
                "max_number_of_allocations": 4
            },
            "num_threads": 1,
            "model_id": ".elser_model_2"
        }
    },
)

const response = await client.inference.put({
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
  inference_config: {
    service: "elasticsearch",
    service_settings: {
      adaptive_allocations: {
        enabled: true,
        min_number_of_allocations: 1,
        max_number_of_allocations: 4,
      },
      num_threads: 1,
      model_id: ".elser_model_2",
    },
  },
});

response = client.inference.put(
  task_type: "sparse_embedding",
  inference_id: "my-elser-model",
  body: {
    "service": "elasticsearch",
    "service_settings": {
      "adaptive_allocations": {
        "enabled": true,
        "min_number_of_allocations": 1,
        "max_number_of_allocations": 4
      },
      "num_threads": 1,
      "model_id": ".elser_model_2"
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "sparse_embedding",
    "inference_id" => "my-elser-model",
    "body" => [
        "service" => "elasticsearch",
        "service_settings" => [
            "adaptive_allocations" => [
                "enabled" => true,
                "min_number_of_allocations" => 1,
                "max_number_of_allocations" => 4,
            ],
            "num_threads" => 1,
            "model_id" => ".elser_model_2",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"elasticsearch","service_settings":{"adaptive_allocations":{"enabled":true,"min_number_of_allocations":1,"max_number_of_allocations":4},"num_threads":1,"model_id":".elser_model_2"}}' "$ELASTICSEARCH_URL/_inference/sparse_embedding/my-elser-model"

client.inference().put(p -> p
    .inferenceId("my-elser-model")
    .taskType(TaskType.SparseEmbedding)
    .inferenceConfig(i -> i
        .service("elasticsearch")
        .serviceSettings(JsonData.fromJson("{\"adaptive_allocations\":{\"enabled\":true,\"min_number_of_allocations\":1,\"max_number_of_allocations\":4},\"num_threads\":1,\"model_id\":\".elser_model_2\"}"))
    )
);

Request examples

Run `PUT _inference/sparse_embedding/my-elser-model` to create an inference endpoint that performs a `sparse_embedding` task. The `model_id` must be the ID of one of the built-in ELSER models. The API will automatically download the ELSER model if it isn't already downloaded and then deploy the model.

{
    "service": "elasticsearch",
    "service_settings": {
        "adaptive_allocations": { 
        "enabled": true,
        "min_number_of_allocations": 1,
        "max_number_of_allocations": 4
        },
        "num_threads": 1,
        "model_id": ".elser_model_2" 
    }
}

Run `PUT _inference/rerank/my-elastic-rerank` to create an inference endpoint that performs a rerank task using the built-in Elastic Rerank cross-encoder model. The `model_id` must be `.rerank-v1`, which is the ID of the built-in Elastic Rerank model. The API will automatically download the Elastic Rerank model if it isn't already downloaded and then deploy the model. Once deployed, the model can be used for semantic re-ranking with a `text_similarity_reranker` retriever.

{
    "service": "elasticsearch",
    "service_settings": {
        "model_id": ".rerank-v1", 
        "num_threads": 1,
        "adaptive_allocations": { 
        "enabled": true,
        "min_number_of_allocations": 1,
        "max_number_of_allocations": 4
        }
    }
}

Run `PUT _inference/text_embedding/my-e5-model` to create an inference endpoint that performs a `text_embedding` task. The `model_id` must be the ID of one of the built-in E5 models. The API will automatically download the E5 model if it isn't already downloaded and then deploy the model.

{
    "service": "elasticsearch",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1,
        "model_id": ".multilingual-e5-small" 
    }
}

Run `PUT _inference/text_embedding/my-msmarco-minilm-model` to create an inference endpoint that performs a `text_embedding` task with a model that was uploaded by Eland.

{
    "service": "elasticsearch",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1,
        "model_id": "msmarco-MiniLM-L12-cos-v5" 
    }
}

Run `PUT _inference/text_embedding/my-e5-model` to create an inference endpoint that performs a `text_embedding` task and to configure adaptive allocations. The API request will automatically download the E5 model if it isn't already downloaded and then deploy the model.

{
    "service": "elasticsearch",
    "service_settings": {
        "adaptive_allocations": {
        "enabled": true,
        "min_number_of_allocations": 3,
        "max_number_of_allocations": 10
        },
        "num_threads": 1,
        "model_id": ".multilingual-e5-small"
    }
}

Run `PUT _inference/sparse_embedding/use_existing_deployment` to use an already existing model deployment when creating an inference endpoint.

{
    "service": "elasticsearch",
    "service_settings": {
        "deployment_id": ".elser_model_2"
    }
}

Response examples (200)

A successful response from `PUT _inference/sparse_embedding/use_existing_deployment`. It contains the model ID and the threads and allocations settings from the model deployment.

{
  "inference_id": "use_existing_deployment",
  "task_type": "sparse_embedding",
  "service": "elasticsearch",
  "service_settings": {
    "num_allocations": 2,
    "num_threads": 1,
    "model_id": ".elser_model_2",
    "deployment_id": ".elser_model_2"
  },
  "chunking_settings": {
    "strategy": "sentence",
    "max_chunk_size": 250,
    "sentence_overlap": 1
  }
}

Get license information Generally available

GET /_license

Api key auth Basic auth Bearer auth

Get information about your Elastic license including its type, its status, when it was issued, and when it expires.

If the master node is generating a new cluster state, the get license API may return a 404 Not Found response. If you receive an unexpected 404 response after cluster startup, wait a short period and retry the request.

Query parameters

accept_enterprise boolean Deprecated

If true, this parameter returns enterprise for Enterprise license types. If false, this parameter returns platinum for both platinum and enterprise license types. This behavior is maintained for backwards compatibility. This parameter is deprecated and will always be set to true in 8.x.
local boolean

Specifies whether to retrieve local information. The default value is false, which means the information is retrieved from the master node.

Responses

200 application/json
Hide response attribute Show response attribute object
- license object Required
  
  Hide license attributes Show license attributes object
  
  expiry_date 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.
  
  One of:
  string-1 string UnitMillis number
  
  expiry_date_in_millis number
  
  Time unit for milliseconds
  
  issue_date string | number Required
  
  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.
  
  One of:
  string-1 string UnitMillis number
  
  issue_date_in_millis number
  
  Time unit for milliseconds
  
  issued_to string Required
  
  issuer string Required
  
  max_nodes number | string | null Required
  
  One of:
  number-1 number string-2 string | null
  
  max_resource_units number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  status string Required
  
  Values are active, valid, invalid, or expired.
  
  type string Required
  
  Values are missing, trial, basic, standard, dev, silver, gold, platinum, or enterprise.
  
  uid string Required
  
  start_date_in_millis number
  
  Time unit for milliseconds

GET /_license

GET /_license

resp = client.license.get()

const response = await client.license.get();

response = client.license.get

$resp = $client->license()->get();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_license"

client.license().get(g -> g);

Response examples (200)

A successful response from `GET /_license`.

{
  "license" : {
    "status" : "active",
    "uid" : "cbff45e7-c553-41f7-ae4f-9205eabd80xx",
    "type" : "trial",
    "issue_date" : "2018-10-20T22:05:12.332Z",
    "issue_date_in_millis" : 1540073112332,
    "expiry_date" : "2018-11-19T22:05:12.332Z",
    "expiry_date_in_millis" : 1542665112332,
    "max_nodes" : 1000,
    "max_resource_units" : null,
    "issued_to" : "test",
    "issuer" : "elasticsearch",
    "start_date_in_millis" : -1
  }
}

Get the trial status Generally available; Added in 6.1.0

GET /_license/trial_status

Api key auth Basic auth Bearer auth

Required authorization

Cluster privileges: monitor

Responses

200 application/json
Hide response attribute Show response attribute object
- eligible_to_start_trial boolean Required

GET /_license/trial_status

GET /_license/trial_status

resp = client.license.get_trial_status()

const response = await client.license.getTrialStatus();

response = client.license.get_trial_status

$resp = $client->license()->getTrialStatus();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_license/trial_status"

client.license().getTrialStatus();

Response examples (200)

A successful response from `GET /_license/trial_status`.

{
  "eligible_to_start_trial": true
}

Start a basic license Generally available; Added in 6.3.0

POST /_license/start_basic

Api key auth Basic auth Bearer auth

Start an indefinite basic license, which gives access to all the basic features.

NOTE: In order to start a basic license, you must not currently have a basic license.

If the basic license does not support all of the features that are available with your current license, however, you are notified in the response. You must then re-submit the API request with the acknowledge parameter set to true.

To check the status of your basic license, use the get basic license API.

Required authorization

Cluster privileges: manage

Query parameters

acknowledge boolean

whether the user has acknowledged acknowledge messages (default: false)
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.
timeout string

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- basic_was_started boolean Required
- error_message string
- type string
  
  Values are missing, trial, basic, standard, dev, silver, gold, platinum, or enterprise.
- acknowledge object

POST /_license/start_basic

POST /_license/start_basic?acknowledge=true

resp = client.license.post_start_basic(
    acknowledge=True,
)

const response = await client.license.postStartBasic({
  acknowledge: "true",
});

response = client.license.post_start_basic(
  acknowledge: "true"
)

$resp = $client->license()->postStartBasic([
    "acknowledge" => "true",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_license/start_basic?acknowledge=true"

client.license().postStartBasic(p -> p
    .acknowledge(true)
);

Response examples (200)

A successful response from `POST /_license/start_basic?acknowledge=true`. If you currently have a license with more features than a basic license and you start a basic license, you must pass the acknowledge parameter.

{
  "basic_was_started": true,
  "acknowledged": true
}

Get machine learning memory usage info Generally available; Added in 8.2.0

GET /_ml/memory/{node_id}/_stats

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_ml/memory/_stats

GET /_ml/memory/{node_id}/_stats

Get information about how machine learning jobs and trained models are using memory, on each node, both within the JVM heap, and natively, outside of the JVM.

Required authorization

Cluster privileges: monitor_ml

Path parameters

node_id string Required

The names of particular nodes in the cluster to target. For example, nodeId1,nodeId2 or ml:true

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.

Values are -1 or 0.
timeout string

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.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object Required
  
  Contains statistics about the number of nodes selected by the request.
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  attributes object Required
  
  Hide attributes attribute Show attributes attribute object
  
  * string Additional properties
  
  jvm object Required
  
  Hide jvm attributes Show jvm attributes object
  
  heap_max number | string
  
  One of:
  number-1 number string-2 string
  
  heap_max_in_bytes number Required
  
  Maximum amount of memory, in bytes, available for use by the heap.
  
  java_inference number | string
  
  One of:
  number-1 number string-2 string
  
  java_inference_in_bytes number Required
  
  Amount of Java heap, in bytes, currently being used for caching inference models.
  
  java_inference_max number | string
  
  One of:
  number-1 number string-2 string
  
  java_inference_max_in_bytes number Required
  
  Maximum amount of Java heap, in bytes, to be used for caching inference models.
  
  mem object Required
  
  Hide mem attributes Show mem attributes object
  
  adjusted_total number | string
  
  One of:
  number-1 number string-2 string
  
  adjusted_total_in_bytes number Required
  
  If the amount of physical memory has been overridden using the es.total_memory_bytes system property then this reports the overridden value in bytes. Otherwise it reports the same value as total_in_bytes.
  
  total number | string
  
  One of:
  number-1 number string-2 string
  
  total_in_bytes number Required
  
  Total amount of physical memory in bytes.
  
  ml object Required
  
  Hide ml attributes Show ml attributes object
  
  anomaly_detectors number | string
  
  One of:
  number-1 number string-2 string
  
  anomaly_detectors_in_bytes number Required
  
  Amount of native memory, in bytes, set aside for anomaly detection jobs.
  
  data_frame_analytics number | string
  
  One of:
  number-1 number string-2 string
  
  data_frame_analytics_in_bytes number Required
  
  Amount of native memory, in bytes, set aside for data frame analytics jobs.
  
  max number | string
  
  One of:
  number-1 number string-2 string
  
  max_in_bytes number Required
  
  Maximum amount of native memory (separate to the JVM heap), in bytes, that may be used by machine learning native processes.
  
  native_code_overhead number | string
  
  One of:
  number-1 number string-2 string
  
  native_code_overhead_in_bytes number Required
  
  Amount of native memory, in bytes, set aside for loading machine learning native code shared libraries.
  
  native_inference number | string
  
  One of:
  number-1 number string-2 string
  
  native_inference_in_bytes number Required
  
  Amount of native memory, in bytes, set aside for trained models that have a PyTorch model_type.
  
  name string Required
  
  roles array[string] Required
  
  Roles assigned to the node.
  
  transport_address string Required
  
  ephemeral_id string Required

GET /_ml/memory/{node_id}/_stats

GET _ml/memory/_stats?human

resp = client.ml.get_memory_stats(
    human=True,
)

const response = await client.ml.getMemoryStats({
  human: "true",
});

response = client.ml.get_memory_stats(
  human: "true"
)

$resp = $client->ml()->getMemoryStats([
    "human" => "true",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/memory/_stats?human"

Delete a calendar Generally available; Added in 6.2.0

DELETE /_ml/calendars/{calendar_id}

Api key auth Basic auth Bearer auth

Remove all scheduled events from a calendar, then delete it.

Required authorization

Cluster privileges: manage_ml

Path parameters

calendar_id string Required

A string that uniquely identifies a calendar.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_ml/calendars/{calendar_id}

DELETE _ml/calendars/planned-outages

resp = client.ml.delete_calendar(
    calendar_id="planned-outages",
)

const response = await client.ml.deleteCalendar({
  calendar_id: "planned-outages",
});

response = client.ml.delete_calendar(
  calendar_id: "planned-outages"
)

$resp = $client->ml()->deleteCalendar([
    "calendar_id" => "planned-outages",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages"

client.ml().deleteCalendar(d -> d
    .calendarId("planned-outages")
);

Response examples (200)

A successful response when deleting a calendar.

{
  "acknowledged": true
}

Get behavioral analytics collections Deprecated Technical preview; Added in 8.8.0

Path parameters

Responses

Create a behavioral analytics collection Deprecated Technical preview; Added in 8.8.0

Path parameters

Responses

Get shard allocation information Generally available

Required authorization

Path parameters

Query parameters

Responses

shards.undesired string | null

write_load.forecast number | string | null

disk.indices.forecast number | string | null

disk.indices number | string | null

disk.used number | string | null

disk.avail number | string | null

disk.total number | string | null

disk.percent string | number | null

host string | null

ip string | null

node.role string | null

Get component templates Generally available; Added in 5.1.0

Required authorization

Path parameters

Query parameters

Responses

version string | null Required

Get the cluster health status Generally available

Required authorization

Query parameters

Responses

epoch number | string

Get CAT help Generally available

Responses

Get index information Generally available

Required authorization

Path parameters

Query parameters

Responses

docs.count string | null

docs.deleted string | null

store.size string | null

pri.store.size string | null

dataset.size string | null

Get shard recovery information Generally available

Required authorization

Path parameters

Query parameters

Responses

start_time string | number

stop_time string | number

files_percent string | number

bytes_percent string | number

translog_ops_percent string | number

Get index template information Generally available; Added in 5.2.0

Required authorization

Path parameters

Query parameters

Responses

version string | null

Get cluster-wide settings Generally available

Required authorization

Query parameters

Responses

Get the cluster health status Generally available; Added in 1.3.0

Required authorization

Path parameters

Query parameters

Responses

Clear the archived repositories metering Technical preview; Added in 7.16.0

Required authorization

Path parameters

Responses

reason string | null

Get cluster repositories metering Technical preview; Added in 7.16.0

Required authorization

Path parameters

Responses

reason string | null