/ ELASTIC, ELASTICSEARCH, API

ElasticSearch API cheatsheet

ElasticSearch documentation is exhaustive, but the way it’s structured has some room for improvement. This post is meant as a cheat-sheet entry point into ElasticSearch APIs.<!--more-→

Category Description Call examples

Document API

Single Document API

Adds a new document

 
 PUT /my_index/my_type/1
{
  "my_field" : "my_value"
}

POST /my_index/my_type
{
  ...
}

PUT /my_index/my_type/1/_create
{
  ...
}

Gets an existing document

 
 GET /my_index/my_type/0

Deletes a document

 
 DELETE /my_index/my_type/0

Updates a document

 
 PUT /my_index/my_type/1
{
  ...
}

Multi-Document API

Multi-get

 
 GET /_mget
{
  "docs" : [
    {
      "_index" : "my_index",
      "_type" : "my_type",
      "_id" : "1"
    }
  ]
}

GET /my_index/_mget
{
  "docs" : [
    {
      "_type" : "my_type",
      "_id" : "1"
    }
  ]
}


GET /my_index/my_type/_mget
{
  "docs" : [
    {
      "_id" : "1"
    }
  ]
}

Performs many index/delete operations in one call

Deletes by query

 
 POST /my_index/_delete_by_query
{
  "query": {
    "match": {
      ...
    }
  }
}

Updates by query

 
 POST /my_index/_update_by_query?conflicts=proceed
POST /my_index/_update_by_query?conflicts=proceed
{
  "query": {
    "term": {
      "my_field": "my_value"
    }
  }
}

POST /my_index1,my_index2/my_type1,my_type2/_update_by_query

Reindexes

 
POST /_reindex
{
  "source": {
    "index": "old_index"
  },
  "dest": {
    "index": "new_index"
  }
}

Search API

URI Search

Executes a search with query parameters on the URL

 
 GET /my_index/my_type/_search?q=my_field:my_value
GET /my_index/my_type/_search
{
  "query" : {
    "term" : { "my_field" : "my_value" }
  }
}

Search Shards API

Gets indices/shards of a search would be executed against

 
 GET /my_index/_search_shards

Count API

Executes a count query

 
 GET /my_index/my_type/_count?q=my_field:my_value
GET /my_index/my_type/_count
{
  "query" : {
    "term" : { "my_field" : "my_value" }
  }
}

Validate API

Validates a search query

 
 GET /my_index/my_type/_validate?q=my_field:my_value
GET /my_index/my_type/_validate
{
  "query" : {
    "term" : { "my_field" : "my_value" }
  }
}

Explain API

Provides feedback on computation of a search

 
 GET /my_index/my_type/0/_explain
{
  "query" : {
    "match" : { "message" : "elasticsearch" }
  }
}
GET /my_index/my_type/0/_explain?q=message:elasticsearch

Profile API

Provides timing information on individual components during a search

 
 GET /_search
{
  "profile": true,
  "query" : {
    ...
  }
}

Field Stats API

Finds statistical properties of fields without executing a search

 
 GET /_field_stats?fields=my_field
GET /my_index/_field_stats?fields=my_field
GET /my_index1,my_index2/_field_stats?fields=my_field

Indices API

Index management

Instantiates a new index

 
 PUT /my_index
{
  "settings" : {
    ...
  }
}

Deletes existing indices

 
 DELETE /my_index
DELETE /my_index1,my_index2
DELETE /my_index*
DELETE /_all

Retrieves information about indices

 
 GET /my_index
GET /my_index*
GET my_index/_settings,_mappings

Checks whether an index exists

 
 HEAD /my_index

Closes/opens an index

 
 POST /my_index/_close
POST /my_index/_open

Shrinks an index to a new index with fewer primary shards

Rolls over an alias to a new index if conditions are met

 
 POST /my_index/_rollover
{
  "conditions": {
    ...
  }
}

Mapping management

Adds a new type to an existing index

 
 PUT /my_index/_mapping/new_type
{
  "properties": {
    "my_field": {
      "type": "text"
    }
  }
}

Retrieves mapping definition for fields

 
 GET /my_index/_mapping/my_type/field/my_field
GET /my_index1,my_index2/_mapping/my_type/field/my_field
GET /_all/_mapping/my_type1,my_type2/field/my_field1,my_field2
GET /_all/_mapping/my_type1*/field/my_field*

Checks whether a type exists

 
 HEAD /my_index/_mapping/my_type

Alias management

Creates an alias over an index

 
 POST /_aliases
{
  "actions" : [
    { "add" :
      { "index" : "my_index", "alias" : "my_alias" }
    }
  ]
}

POST /_aliases
{
  "actions" : [
    { "add" :
      { "index" : ["index1", "index2"] , "alias" : "another_alias" }
    }
  ]
}

Removes an alias

 
 POST /_aliases
{
  "actions" : [
    { "remove" :
      { "index" : "my_index", "alias" : "my_old_alias" }
    }
  ]
}

Index settings

Updates settings of indices

 
 PUT /my_index/_settings
{
  ...
}

Retrieves settings of indices

 
 GET /my_index/_settings

Performs an analysis process of a text and return the tokens

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

Creates a new template

 
 PUT /_template/my_template
{
  ...
}

Deletes an existing template

 
 DELETE /_template/my_template

Gets info about an existing template

 
 GET /_template/my_template

Checks whether a template exists

 
 HEAD /_template/my_template

Replica configuration

Sets index data location on a disk

Monitoring

Provides statistics on indices

 
 GET /_stats
GET /my_index1/_stats
GET /my_index1,my_index2/_stats
GET /my_index1/_stats/flush,merge

Provides info on Lucene segments

 
 GET /_segments
GET /my_index1/_segments
GET /my_index1,my_index2/_segments

Provide recovery info on indices

 
 GET /_recovery
GET /my_index1/_recovery
GET /my_index1,my_index2/_recovery

Provide store info on shard copies of indices

 
 GET /_shard_stores
GET /my_index1/_shard_stores
GET /my_index1,my_index2/_shard_stores

Status management

Clears the cache of indices

 
 POST /_cache/clear
POST /my_index/_cache/clear
POST /my_index1,my_index2/_cache/clear

Explicitly refreshes indices

 
 POST /_refresh
POST /my_index/_refresh
POST /my_index1,my_index2/_refresh

Flushes in-memory transaction log on disk

 
 POST /_flush
POST /my_index/_flush
POST /my_index1,my_index2/_flush

Merge Lucene segments

 
 POST /_forcemerge?max_num_segments=1
POST /my_index/_forcemerge?max_num_segments=1
POST /my_index1,my_index2/_forcemerge?max_num_segments=1

cat API

cat aliases

Shows information about aliases, including filter and routing infos

 
 GET /_cat/aliases?v
GET /_cat/aliases/my_alias?v

cat allocations

Provides a snapshot on how many shards are allocated and how much disk space is used for each node 

 GET /_cat/allocation?v

cat count

Provides quick access to the document count

 
 GET /_cat/count?v
GET /_cat/count/my_index?v

cat fielddata

Shows heap memory currently being used by fielddata

 
 GET /_cat/fielddata?v
GET /_cat/fielddata/my_field1,my_field2?v

cat health

One-line representation of the same information from /_cluster/health

 
 GET /_cat/health?v
GET /_cat/health?v&ts=0

cat indices

Provides a node-spanning cross-section of each index

 
 GET /_cat/indices?v
GET /_cat/indices?v&s=index
GET /_cat/indices?v&health=yellow
GET /_cat/indices/my_index*?v&health=yellow

cat master

Displays the master’s node ID, bound IP address, and node name

 
 GET /_cat/master?v

cat nodeattrs

Shows custom node attributes

 
 GET /_cat/nodeattrs?v
GET /_cat/nodeattrs?v&h=name,id,pid,ip

cat nodes

Shows cluster topology

 
 GET /_cat/nodes?v
GET /_cat/nodes?v&h=name,id,pid,ip

cat pending tasks

Provides the same information as /_cluster/pending_tasks

 
 GET /_cat/pending_tasks?v

cat plugins

Provides a node-spanning view of running plugins per node

 
 GET /_cat/plugins?v
GET /_cat/plugins?v&h=name,id,pid,ip

cat recovery

Shows on-going and completed index shard recoveries

 
 GET /_cat/recovery?v
GET /_cat/recovery?v&h=name,id,pid,ip

cat repositories

Shows snapshot repositories registered in the cluster

 
 GET /_cat/repositories?v

cat thread pool

Shows cluster-wide thread pool statistics per node

 
 GET /_cat/thread_pool?v
GET /_cat/thread_pool?v&h=id,pid,ip

cat shards

Displays shards to nodes relationships

 
 GET /_cat/shards?v
GET /_cat/shards/my_index?v
GET /_cat/shards/my_ind*?v

cat segments

Provides information similar to _segments

 
 GET /_cat/segments?v
GET /_cat/segments/my_index?v
GET /_cat/segments/my_index1,my_index2?v

cat snapshots

Shows snapshots belonging to a repository

 
 /_cat/snapshots/my_repo?v

cat templates

Provides information about existing templates

 
 GET /_cat/templates?v
GET /_cat/templates/my_template
GET /_cat/templates/my_template*

Cluster API

Cluster Health

Gets the status of a cluster’s health

 
 GET /_cluster/health
GET /_cluster/health?wait_for_status=yellow&timeout=50s
GET /_cluster/health/my_index1
GET /_cluster/health/my_index1,my_index2

Cluster State

Gets state information about a cluster

 
 GET /_cluster/state
GET /_cluster/state/version,nodes/my_index1
GET /_cluster/state/version,nodes/my_index1,my_index2
GET /_cluster/state/version,nodes/_all

Cluster Stats

Retrieves statistics from a cluster

 
 GET /_cluster/stats
GET /_cluster/stats?human&pretty

Pending cluster tasks

Returns a list of any cluster-level changes

 
 GET /_cluster/pending_tasks

Cluster Reroute

Executes a cluster reroute allocation

 
 GET /_cluster/reroute {
  ...
}

Cluster Update Settings

Update cluster-wide specific settings

 
 GET /_cluster/settings
{
  "persistent" : {
    ...
  },
  "transient" : {
    ...
  }
}

Node Stats

Retrieves cluster nodes statistics

 
 GET /_nodes/stats
GET /_nodes/my_node1,my_node2/stats
GET /_nodes/127.0.0.1/stats
GET /_nodes/stats/indices,os,process

Node Info

Retrieves cluster nodes information

 
 GET /_nodes
GET /_nodes/my_node1,my_node2
GET /_nodes/_all/indices,os,process
GET /_nodes/indices,os,process
GET /_nodes/my_node1,my_node2/_all

Task Management API

Retrieve information about tasks currently executing on nodes in the cluster

 
 GET /_tasks
GET /_tasks?nodes=my_node1,my_node2
GET /_tasks?nodes=my_node1,my_node2&actions=cluster:*

Nodes Hot Threads

Gets current hot threads on nodes in the cluster

 
 GET /_nodes/hot_threads
GET /_nodes/hot_threads/my_node
GET /_nodes/my_node1,my_node2/hot_threads

Cluster Allocation Explain API

Answers the question "why is this shard unnassigned?"

 
 GET /_cluster/allocation/explain
GET /_cluster/allocation/explain
{
  "index": "myindex",
  "shard": 0,
  "primary": false
}

marks an experimental (respectively new) API that is subject to removal (resp. change) in future versions
Last updated on Feb. 22th
Nicolas Fränkel

Nicolas Fränkel

Nicolas Fränkel is a technologist focusing on cloud-native technologies, DevOps, CI/CD pipelines, and system observability. His focus revolves around creating technical content, delivering talks, and engaging with developer communities to promote the adoption of modern software practices. With a strong background in software, he has worked extensively with the JVM, applying his expertise across various industries. In addition to his technical work, he is the author of several books and regularly shares insights through his blog and open-source contributions.

Read More
—
ElasticSearch API cheatsheet
Share this