What Elasticsearch Query Limits Should You Know?

Result Size Limit

Elasticsearch limits the number of documents returned by a search query. The size parameter defaults to 10 . Setting a larger size increases memory, CPU, and disk usage.

The maximum result window is 10,000 documents. Exceeding this produces an illegal_argument_exception with the message "Result window is too large, from + size must be less than or equal to: [10000]". The limit is controlled by the index.max_result_window setting to prevent deep pagination performance issues.

Solutions for deep pagination:

(1) Use search_after

The search_after parameter enables deep pagination without increasing from or size, offering better performance.

GET /my-index/_search
{
  "size": 1000,
  "query": { "match": { "title": "Elasticsearch" } },
  "sort": [ { "timestamp": "asc" }, { "_id": "asc" } ],
  "search_after": [1609459200000, "my_document_id"]
}

(2) Use the Scroll API

Scroll is suited for bulk data extraction (e.g., full export). It keeps a server‑side snapshot to ensure consistency while iterating.

GET /my-index/_search?scroll=1m
{
  "size": 1000,
  "query": { "match": { "title": "Elasticsearch" } }
}

Note: Scroll is not appropriate for real‑time user requests because it consumes server resources.

Max Clause Count

Lucene, the core engine, protects the cluster from overly large boolean queries. Early Elasticsearch versions capped max_clause_count at 1024 ; from version 7.0 the default became 4096 . Queries exceeding the limit raise an exception.

In Elasticsearch 8.0+, the setting indices.query.bool.max_clause_count is deprecated and no longer influences query behavior. The system now dynamically determines the maximum clause count based on thread‑pool size and JVM heap.

Typical configuration on a node with 30 GB RAM and 48 CPUs yields a maximum clause count of roughly 27,000 . Larger heaps increase the limit, while larger thread pools may reduce it.

Field Data Limits

Aggregations and sorting may load field values into heap memory. High‑cardinality fields can cause OutOfMemoryError.

(1) Limit field‑data cache size

Set indices.fielddata.cache.size to cap the cache, e.g., indices.fielddata.cache.size: 40%, restricting field‑data to 40 % of the heap.

(2) Use pre‑aggregated metrics

For frequently aggregated fields, compute metrics at index time and store them as a separate field to reduce real‑time aggregation load.

(3) Avoid aggregating text fields

Prefer keyword fields for aggregation because text fields require analysis.

Join Operations Limits

Complex nested or parent‑child queries increase load and may trigger the max_clause_count limit.

Best Practices

Avoid relational‑thinking; Elasticsearch is document‑oriented.

Use nested or parent‑child sparingly, as they add indexing and query overhead.

Flatten data structures where possible, placing related data in a single document.

Perform joins at the application layer when necessary.

Query Throughput Limits

Throughput depends on node count, hardware, and query complexity. Exceeding capacity raises response times or HTTP 429 errors.

Example Calculation

Query latency: 1 s

Data nodes: 3

Search threads per node: 13

Maximum throughput ≈ 3 × 13 / 1 = 39 queries/second .

Protection Mechanisms

Search queue: when full, Elasticsearch returns HTTP 429.

Circuit breaker: aborts operations that exceed memory or heap thresholds.

Optimization Recommendations

Monitor query latency and resource usage with Kibana or Elastic Stack Monitoring.

Identify and rewrite slow queries; add appropriate indexes.

Scale the cluster (add nodes) or upgrade CPU, memory, and storage.

Set sensible request timeouts.

When receiving HTTP 429, implement exponential backoff instead of immediate retries.

Understanding these limits and applying the suggested configurations, monitoring, and data‑model design helps keep Elasticsearch clusters stable and performant.