Elasticsearch Cheat Sheet

Cluster and Cat APIs

Requests on this page use Kibana Dev Tools console form. The Running Queries with curl section shows how to send the same request from a shell.

A single-node cluster reports yellow because replica shards have no second node to live on.

Example: confirm the unassigned replicas on orders, then set its replica count to zero.

GET _cat/shards/orders?v&h=index,shard,prirep,state,unassigned.reason

PUT /orders/_settings
{
  "index": { "number_of_replicas": 0 }
}

In 1bench: the Elasticsearch GUI has an Overview tab with cluster status, each node's heap, CPU and RAM, and unassigned shards, so you are not stitching together five _cat calls.

Index Management

There is no rename API. Reindex or clone into the new name, then switch an alias. PUT /_index_template is the composable template API; the legacy _template endpoint is deprecated.

In this mapping, customer is text for search with a keyword sub-field for sorting and aggregations, and items is nested so each line item matches on its own.

Example: create the orders index used on the rest of this page.

PUT /orders
{
  "settings": { "number_of_shards": 1, "number_of_replicas": 1 },
  "mappings": {
    "properties": {
      "order_id":   { "type": "keyword" },
      "customer":   { "type": "text", "fields": { "keyword": { "type": "keyword" } } },
      "status":     { "type": "keyword" },
      "total":      { "type": "scaled_float", "scaling_factor": 100 },
      "created_at": { "type": "date" },
      "shipped_at": { "type": "date" },
      "items": {
        "type": "nested",
        "properties": {
          "sku": { "type": "keyword" },
          "qty": { "type": "integer" }
        }
      }
    }
  }
}

To change a field type later, create orders_v2 with the new mapping, copy the data, and move an orders_current alias that your app reads from.

POST /_reindex
{
  "source": { "index": "orders" },
  "dest":   { "index": "orders_v2" }
}

POST /_aliases
{
  "actions": [
    { "remove": { "index": "orders",    "alias": "orders_current" } },
    { "add":    { "index": "orders_v2", "alias": "orders_current" } }
  ]
}

Documents

Each bulk line must be a single line of JSON, and the body must end with a newline.

Example: bulk-load two orders, mark one shipped, then cancel pending orders older than 30 days.

POST /_bulk
{ "index": { "_index": "orders", "_id": "1001" } }
{ "order_id": "1001", "customer": "Acme Corp", "status": "paid", "total": 249.90, "created_at": "2026-10-01T09:12:00Z", "items": [ { "sku": "SKU-42", "qty": 2 } ] }
{ "index": { "_index": "orders", "_id": "1002" } }
{ "order_id": "1002", "customer": "Globex", "status": "pending", "total": 89.00, "created_at": "2026-08-14T16:40:00Z", "items": [ { "sku": "SKU-7", "qty": 1 } ] }

POST /orders/_update/1001
{
  "doc": { "status": "shipped", "shipped_at": "2026-10-03T11:00:00Z" }
}

POST /orders/_update_by_query?conflicts=proceed
{
  "query": {
    "bool": {
      "filter": [
        { "term":  { "status": "pending" } },
        { "range": { "created_at": { "lt": "now-30d/d" } } }
      ]
    }
  },
  "script": {
    "source": "ctx._source.status = params.status",
    "params": { "status": "cancelled" }
  }
}

In 1bench: the Elasticsearch GUI lets you edit documents in a table, stage several changes and save them in one _bulk request with version checks, instead of writing an _update call per document.

Query DSL

Every search goes to GET /orders/_search with a query object. Full-text queries analyze your input; term-level queries match the stored value exactly.

Elasticsearch 9.0 removed the old from, to, include_lower and include_upper range parameters and the _knn_search endpoint. Use gte/lte and knn inside _search.

Each query object above goes in the query field of a search request. This one uses date math for the last seven full days in Berlin time:

GET /orders/_search
{
  "query": {
    "range": {
      "created_at": { "gte": "now-7d/d", "lt": "now/d", "time_zone": "Europe/Berlin" }
    }
  }
}

A plain bool on items.sku and items.qty would match across different items; nested keeps them together.

Example: orders that contain at least two units of SKU-42 in the same line item.

GET /orders/_search
{
  "query": {
    "nested": {
      "path": "items",
      "query": {
        "bool": {
          "filter": [
            { "term":  { "items.sku": "SKU-42" } },
            { "range": { "items.qty": { "gte": 2 } } }
          ]
        }
      }
    }
  }
}

In 1bench: the Elasticsearch GUI has a visual query builder with field pickers and type-aware filters, and the DSL it generates opens in a REST console you can edit.

Bool Queries

Put exact conditions (status, dates, IDs) in filter and keep must for text you want ranked. With no must or filter, at least one should clause has to match.

GET /orders/_search
{
  "query": {
    "bool": {
      "should": [
        { "term": { "status": "paid" } },
        { "term": { "status": "shipped" } },
        { "range": { "total": { "gte": 200 } } }
      ],
      "minimum_should_match": 2
    }
  }
}

Example: Acme orders over 100 from this year, excluding cancelled ones, with shipped orders ranked first.

GET /orders/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "customer": "acme" } }
      ],
      "filter": [
        { "range": { "total": { "gt": 100 } } },
        { "range": { "created_at": { "gte": "now/y" } } }
      ],
      "must_not": [
        { "term": { "status": "cancelled" } }
      ],
      "should": [
        { "term": { "status": { "value": "shipped", "boost": 2 } } }
      ]
    }
  }
}

Aggregations

Set "size": 0 when you only want the buckets, not the hits.

terms returns the top 10 buckets by default. Raise size, or use composite to page through all of them.

GET /orders/_search
{
  "size": 0,
  "aggs": {
    "by_customer": {
      "terms": { "field": "customer.keyword", "size": 5 },
      "aggs": {
        "latest_order": {
          "top_hits": {
            "size": 1,
            "sort": [ { "created_at": "desc" } ],
            "_source": ["order_id", "total", "status"]
          }
        }
      }
    }
  }
}

Example: monthly revenue for the past year, with the top three customers by spend inside each month.

GET /orders/_search
{
  "size": 0,
  "query": { "range": { "created_at": { "gte": "now-1y/M" } } },
  "aggs": {
    "by_month": {
      "date_histogram": { "field": "created_at", "calendar_interval": "month" },
      "aggs": {
        "revenue": { "sum": { "field": "total" } },
        "top_customers": {
          "terms": {
            "field": "customer.keyword",
            "size": 3,
            "order": { "spend": "desc" }
          },
          "aggs": { "spend": { "sum": { "field": "total" } } }
        }
      }
    }
  }
}

Sorting and Pagination

from + size cannot go past 10,000 (index.max_result_window). Past that, use search_after.

GET /orders/_search
{
  "from": 20,
  "size": 10,
  "_source": ["order_id", "customer", "total"],
  "sort": [ { "created_at": "desc" } ]
}

Open a point in time, search without an index in the path, then pass the last hit's sort values as search_after for the next page. Each response returns the current pit_id to use next.

Example: walk through every order newest first with a point in time and search_after.

POST /orders/_pit?keep_alive=1m

GET /_search
{
  "size": 1000,
  "pit": { "id": "<pit_id from the previous response>", "keep_alive": "1m" },
  "sort": [ { "created_at": "desc" } ],
  "search_after": [1790845920000, 4294967298]
}

DELETE /_pit
{
  "id": "<pit_id>"
}

KQL

KQL (Kibana Query Language) is what you type in the Kibana search bar. It only filters: no aggregations, no sorting. Text fields are analyzed; keyword, numeric and date values must match exactly.

and, or and not are not case-sensitive. KQL has no fuzzy or regex search; switch the search bar to Lucene syntax for customer:acme~ or /regex/.

Example: paid orders over 100 from the last 30 days that have not shipped yet.

status: paid and total > 100 and created_at >= now-30d and not shipped_at: *

Running Queries with curl

Kibana Dev Tools takes METHOD /path and a JSON body. From a shell, the same request becomes a curl call to port 9200. Since 8.0, security is on by default: HTTPS with a generated CA and the elastic user.

Example: fetch five paid orders in Dev Tools, then send the same request from a shell with curl.

GET /orders/_search
{
  "query": { "term": { "status": "paid" } },
  "size": 5
}

curl -s -u "elastic:$ELASTIC_PASSWORD" --cacert http_ca.crt \
  -H 'Content-Type: application/json' \
  -X GET 'https://localhost:9200/orders/_search?pretty' \
  -d '{
    "query": { "term": { "status": "paid" } },
    "size": 5
  }'

ES|QL answers a related question, top customers by paid revenue, and returns rows and columns instead of hits:

POST /_query?format=txt
{
  "query": "FROM orders | WHERE status == \"paid\" | STATS revenue = SUM(total) BY customer.keyword | SORT revenue DESC | LIMIT 10"
}

OpenSearch Compatibility

OpenSearch forked from Elasticsearch 7.10.2. Most of this page carries over; these are the parts that do not.

Gotchas

• term on a text field usually finds nothing. Text is stored as lowercase tokens, so { "term": { "customer": "Acme Corp" } } misses. Use match on customer, or term on customer.keyword.
• from + size stops at 10,000, and hits.total stops counting at 10,000 with "relation": "gte". Use search_after for deep pages and track_total_hits or _count for exact totals.
• You cannot change a field's type once it is mapped. Add a new field or reindex into a new index behind an alias.
• New writes show up in search only after a refresh (every second by default). GET /orders/_doc/1001 sees them right away; _search may not.
• DELETE /orders and _delete_by_query cannot be undone without a snapshot. Wildcard deletes such as DELETE /orders-* fail by default because action.destructive_requires_name is true, so do not turn it off to save typing.
• terms bucket counts and cardinality are approximate on multi-shard indexes. Check doc_count_error_upper_bound before reporting exact numbers.