Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 43 ยท Cluster and Scale

Query Performance and Tuning

Make Elasticsearch searches faster: use filters and caches, read the profile API, avoid wildcard and script queries, size shards and tune refresh and bulk.

A search that takes 20 ms on a laptop can take two seconds on a busy cluster with a hundred million documents. Most slow searches are slow for a small number of well-known reasons: too much scoring, expensive query types, too many tiny shards, or an index that is busy merging. The good news is that the fixes are mostly cheap.

This lesson gives you a checklist, from the highest payoff to the lowest. You will learn what a filter really saves, how to read a profile, which queries to avoid, and how to size shards and tune writes. The key ideas are tested in small stand-ins, because the real engine cannot run on this site.

Requests below are read-only. The runnable examples are JavaScript models: they count the work done, not real milliseconds. Always measure on your own data with your own queries before and after a change.

Measure before you tune

Tune in this order

Measure Find the slow query first.
Profile See where the time goes.
Cut work Filters, fewer fields, smaller results.
Fix layout Shards, merges, hardware.

Layout changes are the most expensive, so try them last.

1 / 2

Start with numbers. Every search response contains a took field (milliseconds spent inside the cluster) and timed_out. Enable the slow log for an index to record every query above a threshold:

HTTP
PUT /products/_settings
{
  "index.search.slowlog.threshold.query.warn": "2s",
  "index.search.slowlog.threshold.query.info": "500ms"
}

Then pick one slow query and look inside it with the profile API.

The profile API

Add "profile": true to a search and the response lists, per shard, how long each part of the query tree took:

HTTP
GET /products/_search
{
  "profile": true,
  "query": {
    "bool": {
      "must":   [ { "match": { "name": "trail shoe" } } ],
      "filter": [ { "term": { "in_stock": true } } ]
    }
  }
}

In the response, profile.shards[].searches[].query[] is a tree. Each node has a type (such as BooleanQuery or TermQuery), a time_in_nanos, and a breakdown that shows where time went (for example creating scorers, advancing through postings, scoring). Read it like this:

  • Find the node with the biggest time_in_nanos. That clause is your suspect.
  • If most time is in the scoring steps, you may not need scores for that clause at all (use a filter).
  • If most time is in building a scorer or matching, the query type itself is expensive (wildcard, regex, script).
  • aggregations and collector sections show aggregation and collection cost separately.

Profiling slows the query down, so use it for diagnosis only, never in production traffic. The shape of the output is also not a stable contract; do not parse it in application code.

Use filters whenever you do not need a score

In Query DSL basics you met query context and filter context. For performance the difference is large:

  • A filter clause answers yes or no. No BM25 score is computed.
  • Filter results can be cached as a bitset per segment in the node query cache, so the same filter on the next request is nearly free. Elasticsearch caches filters that are reused often enough, on segments big enough to be worth it.
  • Date range filters that use "now" change every millisecond and are not cacheable. Round them (now/d or now-1h/h) so many requests share one cache entry.
HTTP
GET /logs/_search
{
  "query": {
    "bool": {
      "filter": [
        { "term":  { "level": "error" } },
        { "range": { "@timestamp": { "gte": "now-1h/h" } } }
      ]
    }
  }
}

Put exact-value conditions (status, category, tenant, date range) in filter, and keep only the real full-text part in must. Also use keyword, numeric or date fields for exact matching, and a term query on them, instead of a match on a text field.

JS Counting the work: scoring versus filtering

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Both versions return the same hits. Version 2 scores far fewer documents, because the cheap filter runs first and only survivors reach the scorer. The real engine is cleverer (it iterates postings lists in a smart order), but the principle is the same: do less work per document, and only for documents that still matter.

Queries to avoid or use carefully

Query Why it is slow Better choice
wildcard with a leading * Has to inspect every term in the dictionary wildcard field type, n-grams, or edge n-grams
regexp, fuzzy on huge fields Expands to many terms Limit max_expansions, prefix length
script query / script_score Runs code for every candidate document Precompute a field at index time
query_string from user input Unbounded features, risk of expensive clauses simple_query_string or a match query
Very large terms lists Thousands of terms to look up Terms lookup, or restructure the data
Deep from + size Each shard must build from + size hits search_after (sorting and pagination)
track_total_hits: true on huge results Must count every match Leave the default (counts up to 10,000), or set a number

Two more habits: return fewer fields (_source filtering, or "_source": false plus fields), and request only the aggregations you display. Large size values in terms aggregations also cost memory and time.

Index-time choices that speed up searches

Searching is cheaper when the work was done earlier:

  • Map fields for how they are queried. An ID or status code is a keyword, not text. Numbers you never range-query (like a ZIP code) are better as keyword. See mappings and field types.
  • Precompute values you would otherwise compute in a script, such as price_with_tax or a popularity_bucket.
  • Index sorting (index.sort.field) stores documents in a chosen order inside each segment, so a query that sorts on that field can stop early. It is set at index creation, cannot be changed later, and makes indexing somewhat slower.
  • Force merge read-only indexes (POST /logs-2026.01/_forcemerge?max_num_segments=1). Fewer segments mean less per-segment overhead. As the segments lesson warned, never do this on an index that still receives writes.
  • Avoid nested fields and joins unless you truly need them: each nested object is a hidden document (nested fields).
  • Use preference (for example a session ID) so repeated searches by the same user hit the same shard copies and benefit from warm caches.

Sizing shards

Each shard is a complete Lucene index with its own memory and file handles. Both extremes hurt:

  • Too many small shards: every search fans out to every shard, and each shard has fixed overhead. A cluster with thousands of tiny shards wastes heap and slows the master node.
  • Too few huge shards: recovery and rebalancing are slow, and one search cannot use more than one thread per shard.

A common rule of thumb is to aim for shards in the tens of gigabytes (roughly 10 to 50 GB, and for time-series data often up to about 50 GB per shard), and to keep the total number of shards per node moderate rather than in the thousands. Treat these as starting points, not laws: benchmark with realistic data. For many small indexes, consider one index with a tenant field and a filter, rather than one index per tenant (see data modeling). The number of primary shards is fixed at index creation (changing it means shrink, split or reindex), while replicas can change at any time (shards and replicas).

Replicas also help read throughput: more copies mean more places to run searches. They do not make a single query faster, and they make indexing more expensive.

Diagnosing oversharding

Oversharding is the most common scaling mistake. Signs: thousands of shards per node, a sluggish master, heap pressure with little data, and searches that touch dozens of tiny indexes. A useful guideline is to keep the shard count per node proportional to heap (on the order of 20 shards or fewer per GB of heap), but the real answer comes from measurement.

HTTP
GET /_cat/shards?v&s=store:asc&h=index,shard,prirep,store
GET /_cluster/stats?filter_path=indices.shards.total,indices.count

Cures: use rollover so time-series indexes grow to a proper size before a new one starts, shrink or merge old indexes with the shrink API or reindex, and use fewer primaries for small indexes (one is often enough below 10 GB).

Circuit breakers

Elasticsearch protects itself from running out of heap with circuit breakers. Before a request allocates a lot of memory, the matching breaker estimates the cost and, if it would pass the limit, rejects the request with a circuit_breaking_exception (HTTP 429) instead of letting the node die with an out-of-memory error. The main ones are the parent breaker (the total heap limit, 95% of the heap by default with real-memory accounting), request (per-request structures such as aggregation buckets) and fielddata.

HTTP
GET /_nodes/stats/breaker

A rising tripped counter means something is too heavy: a terms aggregation with a huge size, sorting or aggregating on a text field, or too many concurrent requests. Fix the query or add capacity; raising the limits only postpones the outage.

Disk pressure

Search speed depends on the file cache and on free disk. When a node passes the watermarks described in Shards, Replicas and Clusters, shards stop arriving and later indexes turn read-only. Keep 20 to 30% free, since merges temporarily need extra space, and use index lifecycle management to delete or move old data before the disk fills.

Rejected thread pools

Each kind of work (search, write, get) has a thread pool with a fixed number of threads and a bounded queue. When both are full, new requests get HTTP 429 es_rejected_execution_exception.

HTTP
GET /_cat/thread_pool/search,write?v&h=node_name,name,active,queue,rejected

Rejections mean demand beyond capacity: too many bulk writers, expensive queries, or slow disks. Slow the clients down (back off and retry, smaller bulks), reduce per-query cost, or add nodes. Increasing queue sizes only hides the problem behind higher latency. Also check the network: large responses and replication traffic can saturate a link, so measure transfer time separately from query time (the took field covers only the search itself).

A queue-and-rejection stand-in

This model has 2 workers and a queue of 3. A burst of requests shows what a bounded queue does. It is a simplified model, not Elasticsearch code.

JS Why bounded queues reject

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Tuning writes: refresh and bulk

Indexing speed matters during imports. The usual recipe for a large one-off load:

HTTP
PUT /products/_settings
{ "index": { "refresh_interval": "-1", "number_of_replicas": 0 } }
  • Send documents with the bulk API in batches (often 5 to 15 MB per request; find your own sweet spot by trying a few sizes).
  • Use several parallel workers, and back off when you receive 429 responses.
  • Disable refresh and drop replicas during the load, then restore them ("refresh_interval": "1s", replicas back to 1) and refresh once.
  • Let Elasticsearch generate IDs when you do not need your own, because it can skip checking for existing IDs.
  • Avoid mapping every field as both text and keyword if you only search one way.
JS Why one refresh per document is expensive

Press Run (or Ctrl + Enter) to see the console output here.

No output.

This is only counting, but it shows why refresh=true on every write floods the index with tiny segments that the background merges then have to clean up, competing with your searches for disk and CPU.

A short tuning checklist

  1. Find slow queries with the slow log and took.
  2. Profile one. Which clause dominates?
  3. Move yes/no conditions to filter; round dates; use keyword for exact values.
  4. Remove wildcard, script and deep-pagination patterns.
  5. Reduce _source, size and aggregation cardinality.
  6. Check shard count and size; merge read-only indexes.
  7. For bulk loads, relax refresh and replicas, and use bulk batches.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is a filter usually faster than the same condition in a must clause?

    A filter only decides whether a document matches. No relevance score is computed, and Elasticsearch can cache the result for reuse.
  2. 2. Which query is the most likely to be slow because it must inspect a large part of the term dictionary?

    A leading wildcard cannot use the sorted term dictionary to jump to a starting point, so many terms are checked.
  3. 3. What is the profile API for?

    profile: true adds a timing breakdown for the query tree, so you can find the expensive clause. It adds overhead, so use it only for diagnosis.
  4. 4. You are importing 50 million documents once. Which setting change is a good idea during the import?

    Disabling refresh (and often replicas) during the load avoids creating many tiny segments. Restore the settings afterwards.

Summary

  • Measure first: took, the slow log and the profile API show which clause costs the most.
  • Put yes/no conditions in filter: no scoring, and results can be cached. Round now in date ranges.
  • Avoid leading wildcards, regexes, script queries, deep from + size and unbounded query_string input.
  • Do work at index time: right field types, precomputed fields, index sorting, and force merge for read-only indexes.
  • Size shards in the tens of gigabytes, and avoid thousands of tiny shards.
  • For bulk loads, use the bulk API, relax refresh and replicas, then restore them.

Next: calling all of this from your application in Using Elasticsearch from Code.