/ 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

Developer Advocate with 15+ years experience consulting for many different customers, in a wide range of contexts (such as telecoms, banking, insurances, large retail and public sector). Usually working on Java/Java EE and Spring technologies, but with focused interests like Rich Internet Applications, Testing, CI/CD and DevOps. Also double as a trainer and triples as a book author.

Read More
—
ElasticSearch API cheatsheet
Share this