Deep pagination means asking for a page of results that lies very far from the beginning of the sorted list.

When a search matches thousands or millions of documents, you almost never want all of them at once. You want a small window, such as ten or twenty results at a time. Moving from one window to the next is called pagination. Page one shows results one to ten, page two shows eleven to twenty, and so on.

Shallow pagination, such as pages one to five, is cheap and works beautifully in Elasticsearch. Deep pagination is when the requested page is far down the list, for example page ten thousand. The problem is that the cost of a page in Elasticsearch does not depend only on how many results you want. It also depends on how far down the list the page starts. The deeper you go, the more work the cluster must do to give you the same ten results.

This guide explains why this happens, what safety rules Elasticsearch uses to stop you from hurting yourself, and which better tools exist when you truly need to walk through a big result set.

Ordinary pagination in Elasticsearch uses two simple settings in a search request.

The size setting says how many results to return in this response. Its default is ten. The from setting says how many results to skip before starting to return. Its default is zero. So a request with from zero and size ten returns results one to ten. A request with from ten and size ten returns results eleven to twenty.

This is called offset pagination, because you give an offset, which is how many results to skip. Web developers love it because it maps directly to page numbers. Page number times page size, minus one page, gives the offset. It is also how most databases with an offset clause behave.

The simplicity is the trap. From the outside, page one thousand looks identical to page one: same size, just a different number. But inside the cluster the two requests are very different in cost, as the next chapters will show.

To see why deep pages hurt, we must first remember how a search travels through a cluster.

An Elasticsearch index is divided into shards. Each shard holds a slice of the documents and works like a small independent search engine. Because documents are spread over shards, any search must ask every relevant shard for its best results, because the true top ten could be hiding in any shard.

The request first lands on one node, which becomes the coordinating node for this request. Its job is to send the query to all shards, collect their answers, merge them into one final ordered list, and reply to the client. The coordinating node does not hold the data for this. It only organizes the merge.

flowchart TD
  CL["Client asks for page of results"] --> CO["Coordinating node"]
  CO --> S1["Shard 1: its own best results"]
  CO --> S2["Shard 2: its own best results"]
  CO --> S3["Shard 3: its own best results"]
  CO --> S4["Shard 4: its own best results"]
  CO --> S5["Shard 5: its own best results"]
  S1 --> M["Merge into one sorted list"]
  S2 --> M
  S3 --> M
  S4 --> M
  S5 --> M
  M --> R["Return the requested page"]
        

This distributed design is what makes Elasticsearch scale. But it also means that no single shard knows what the global position of any document is. Only the merge step can decide that, and that is where deep pagination gets expensive.

A search runs in two stages. Understanding them shows exactly where the extra work appears.

The normal search type is called query then fetch. In the first stage, the query phase, each shard runs the query and builds a small ranked list of the best matches. Each entry in this list is light: it holds only the document identifier and the values needed for sorting, such as the score. The heavy content of the document is not included.

The shard sends this light list to the coordinating node. The coordinating node merges the lists from all shards and works out the final order. Then comes the second stage, the fetch phase. The coordinating node asks only the shards that own the winning documents to send their full content, such as the source. Only the documents of the final page are fetched.

sequenceDiagram
  participant C as Client
  participant Co as Coordinating Node
  participant S as Each Shard
  C->>Co: Search with from and size
  Co->>S: Query phase: send me your top from plus size entries
  S->>S: Build ranked list of ids and sort values
  S->>Co: Return light list of entries
  Co->>Co: Merge all lists, skip from, keep size
  Co->>S: Fetch phase: send full documents for the winners
  S->>Co: Return the documents
  Co->>C: Return the page
        

Notice a very important detail. In the query phase, each shard is asked for from plus size entries, not just size. That is the key to the whole problem, and we look at it closely next.

Every shard must keep a sorted waiting list that is as long as the offset plus the page size.

Suppose you ask for the page that starts at position ten thousand with size ten. A shard cannot know whether its own best result is close to the global top or far away. The only safe way is to provide its best ten thousand and ten results. Otherwise, if all the global results ranked 10,001 to 10,010 happened to live on one shard, that shard would fail to supply them.

So each shard builds a priority queue, which is a sorted list that always keeps the best entries seen so far, with a length of from plus size. The shard scans all matching documents, and for each one it decides whether it belongs among the current best entries. A longer queue means more comparisons and more memory.

Then all shards send their full lists to the coordinating node. The coordinating node builds its own priority queue with the combined entries and picks out the requested slice. It must hold entries from all shards at the same time.

flowchart LR
  subgraph SH["Each of the shards"]
    Q1["Queue of size from plus size"]
  end
  SH -->|"sends from plus size entries"| CQ["Coordinating queue: shards times from plus size entries"]
  CQ -->|"skip first from entries"| OUT["Keep only size entries"]
        

Numbers make the problem impossible to ignore. Let us count how many entries the cluster must handle for different pages.

Take an index with five shards and a page size of ten. The table shows how many entries each shard must produce and how many entries the coordinating node must merge for a few different offsets.

Now see what happens when the number of shards grows. The offset is the same, at 9,990, and the page size is ten.

The cost has two multipliers. One is the depth, which is the offset. The other is the number of shards. A cluster with many shards suffers more from deep pagination, since every shard must send a full list.

The extra work is not abstract. It shows up as real pressure on several resources at once.

The worst part is that the pressure spreads. A single expensive deep request on a coordinating node can slow all other requests on the same node. A few such requests at once can trip the memory protection circuits of the node, which then start refusing other requests too. Users who only wanted page one suddenly get errors, even though the guilty request was for page ten thousand.

Elasticsearch does not let you walk off the cliff. It puts up a fence at ten thousand results.

Every index has a setting called index.max_result_window. Its default is 10,000. The rule is simple: the sum of from and size must not be larger than this value. A request for from 9,990 and size 10 is allowed, because the sum is exactly 10,000. A request for from 10,000 and size 10 is refused with an error that says the result window is too large.

The error message also tells you what to do. It points you to the scroll API for large data sets and to the search after feature for deep pagination, and it mentions that you could raise the setting. This message is the product’s way of teaching you the correct approach at the moment you hit the problem.

Related windows

The same idea protects other features. There is a limit for how many top documents a rescoring step may work on, and a limit for the number of inner hits returned inside a parent result. Each limit exists to keep the amount of hidden work per request within reason.

It is possible to increase the window. It is rarely a good idea.

The setting can be changed per index, and many developers do so the moment they see the error. It feels like a quick fix. But raising the limit only removes the fence. It does not remove the cliff. The cost still grows with the offset, and now there is nothing to stop a single request from asking for a million entries per shard.

Consider what happens if you set the window to one million. A single request with from 999,990 on an index of twenty shards asks the cluster to produce twenty million entries, hold them in memory at the coordinating node, and sort them. A handful of such requests, whether from a buggy client, a curious user, or an automated crawler, can consume the whole heap and take the node down.

Pagination has a second, quieter problem. The pages themselves may not agree with each other.

Offset pagination assumes that the sorted list stays the same between requests. Page one and page two come from two separate searches. If anything changes between them, results can be shown twice or skipped. Three things commonly cause this.

Reducing the bounce

For ties, always add a unique tiebreaker field to the sort, so that the order is fully decided. For different shard copies, use the preference option with a value tied to the user’s session, so the same user is routed to the same shard copies for every page. For changing data, use a frozen view of the index, which is what the point in time feature offers, and which we study soon.

Page counters like “page 3 of 8,421” look harmless, but the number behind them can be costly to compute.

To show “page 3 of 8,421”, the application needs to know how many documents matched in total. Counting exactly requires visiting every matching document on every shard, and the search cannot stop early once it has found enough top results. On a big index, this counting can cost more than finding the top ten.

To avoid this, Elasticsearch by default tracks the total only up to ten thousand hits. If more than ten thousand documents match, the response says the total is at least ten thousand, not the exact number. This lets the engine skip work through smart shortcuts. You can ask for exact counts using the track_total_hits setting, or for a different threshold, but you pay for it in speed.

Scroll was the first tool built for reading very large result sets.

The scroll API works in two steps. First you run a normal search and add a scroll parameter with a time, such as one minute. Elasticsearch then takes a snapshot of the index as it looks at that moment and keeps a search context alive on every shard. The response includes a scroll identifier. Then you repeatedly send this identifier to get the next batch. Each batch continues exactly where the last one ended, and the data does not change during the scroll, even if documents are added or deleted, because you are reading the frozen snapshot.

Scroll avoids the deep pagination cost, because each shard remembers where it stopped and simply continues. Nobody needs to rebuild a big queue for every batch.

sequenceDiagram
  participant C as Client
  participant Co as Coordinating Node
  participant S as Shards
  C->>Co: Search with scroll time and size
  Co->>S: Run query and keep search contexts open
  S->>Co: First batch and cursor positions
  Co->>C: Batch 1 with scroll id
  C->>Co: Send scroll id for next batch
  Co->>S: Continue from saved position
  S->>Co: Next batch
  Co->>C: Batch 2 with scroll id
  C->>Co: Clear scroll when finished
  Co->>S: Release contexts
        

Scroll solved the cost problem but introduced a resource problem. It is meant for machines, not for web pages.

Each open scroll pins a search context on every shard, and this context keeps the segments that existed at the moment of the search from being deleted. Elasticsearch normally merges small segments and removes the old ones to save disk and memory. While a scroll is open, the old segments must stay, so disk space and file handles are held longer than usual. A busy index with many long scrolls can accumulate a surprising amount of stale data.

Point in time separates the frozen view from the paging cursor. That separation is the secret of the modern approach.

A point in time, shortened to PIT, is a lightweight handle that freezes the state of an index, or a set of indices, at the moment you open it. Any search that uses this handle sees exactly the same documents, regardless of what is indexed, updated, or deleted afterwards. You open a PIT with a keep alive time, and you close it when finished.

Unlike scroll, a PIT does not carry a position or a result queue with it. It is only the frozen view. This makes it much lighter, and it means you can run any number of different searches against the same frozen view. Position tracking is left to another feature, the search after cursor, which we cover next.

flowchart TD
  O["Open PIT with keep alive"] --> ID["Receive PIT id: frozen view of the index"]
  ID --> S1["Search 1 using the PIT id"]
  ID --> S2["Search 2 using the PIT id"]
  ID --> S3["Search 3 using the PIT id"]
  S1 --> CL["Close PIT when done"]
  S2 --> CL
  S3 --> CL
        

A PIT still holds old segments while it is open, so it should be closed when the job finishes. But because it does not carry a result queue on each shard, it is cheaper to keep open than a scroll.

Search after replaces “skip this many” with “continue after this exact item”. That small change removes the depth cost.

Instead of telling Elasticsearch how many results to skip, you tell it the sort values of the last result you have seen. The request says, “give me the next ten results whose sort position comes after these values.” Because each shard can apply this as a filter on its own sorted data, it only needs to find the next ten results after that point, not the first ten thousand.

This is known as keyset pagination or cursor pagination. Every request uses from equal to zero, and the cursor carries the position. So the queue size at every shard is only the page size, no matter how deep you are in the list.

Together, point in time and search after give cheap pages and a consistent view. This is the current recommended approach for deep pagination.

The PIT provides the frozen view, so documents do not shift while the user is paging. Search after provides the moving position, so each page costs the same. The two features complement each other, and neither alone solves both problems.

sequenceDiagram
  participant C as Client
  participant E as Elasticsearch
  C->>E: Open point in time with keep alive
  E->>C: PIT id
  C->>E: Search with PIT id, sort, size, no search after
  E->>C: Page 1 with sort values of each hit and PIT id
  C->>E: Search with PIT id, same sort, search after last hit values
  E->>C: Page 2 with sort values and PIT id
  C->>E: Repeat with newest PIT id and last hit values
  E->>C: Empty page means the end
  C->>E: Close point in time
        

Step by step

A cursor only works if every document has a single, unambiguous place in the sort order.

Suppose you sort by date, and a hundred documents share exactly the same date. The last hit of page one has that date, and you ask for everything “after” that date. The engine cannot tell which of the hundred documents you already saw, so it may skip some or repeat some. To fix this, you add a second sort field that is unique for every document. This is the tiebreaker. With a tiebreaker, no two documents share the same full sort key, so the cursor points to exactly one position.

Four tools exist. The right one depends on who is reading and what they need.

flowchart TD
  A["Need results beyond the first few pages?"] -->|"No"| B["Use from and size"]
  A -->|"Yes"| C{"Who consumes the data?"}
  C -->|"A person in a user interface"| D{"Do they need random page jumps?"}
  D -->|"No: next and previous, load more"| E["PIT plus search after"]
  D -->|"Yes: numbered pages"| F["Cap the depth, refine filters, or use windows by date"]
  C -->|"A program: export, copy, reindex"| G["PIT plus search after, or scroll for simple jobs"]
        

For most modern applications the answer is short: use offset pagination for the first pages, and PIT with search after when you need to go deeper or when the view must be consistent. Scroll remains available and is fine for simple one-time jobs, but the documentation now recommends the newer pair for deep pagination.

When you must read millions of documents fast, one cursor is too slow. Slicing lets several workers read at once.

A slice is a portion of the result set. If you ask for four slices, the result set is divided into four disjoint parts that together cover everything exactly once. Each worker reads one slice with its own cursor. Slicing is available for scroll, and it is also available for searches that use a PIT.

The split is decided by hashing a document identifier, so it is roughly even. Each worker sends the same query, the same PIT or scroll setup, and a slice number out of the total number of slices. The workers run in parallel and never overlap.

flowchart LR
  Q["One query, one frozen view"] --> W1["Worker 1: slice 0 of 4"]
  Q --> W2["Worker 2: slice 1 of 4"]
  Q --> W3["Worker 3: slice 2 of 4"]
  Q --> W4["Worker 4: slice 3 of 4"]
  W1 --> OUT["Combined complete export"]
  W2 --> OUT
  W3 --> OUT
  W4 --> OUT
        

Deep pagination does not only happen with documents. It also appears when you list very many groups.

A terms aggregation returns the top groups, for example the top customers by number of orders. It has a size but no offset. If you ask for a size of one million, each shard must build a huge table of counts, and the coordinating node must merge them, which is the same kind of problem in a different shape. The cluster also has a limit on the total number of buckets a single response may contain, to protect memory.

The tool for walking through many groups is the composite aggregation. It returns groups in a fixed order in small pages, and each response includes an after key, which is the cursor to give in the next request. This is keyset pagination for buckets. It also lets you group by several fields together.

The best fix for deep pagination is often in the application, not in the cluster.

If you use search after, your own API must decide how to hand the cursor to clients.

The raw cursor is the list of sort values of the last hit, together with the PIT identifier. Exposing this directly to browsers is not wise, since it reveals internal details, and clients could tamper with it. A better approach is to wrap it in an opaque token: a single encoded string that your server creates and later decodes. The client just passes the token back, without understanding it.

Going backwards

Search after moves forward. To go to the previous page, one common trick is to reverse every sort direction and use the first hit of the current page as the cursor, then reverse the returned list before showing it. Another simple approach is to keep the cursors of pages you have already visited in the client and reuse them when the user goes back.

Deep pagination is not unique to Elasticsearch. Every database that supports offset paging has it.

In a relational database, an offset clause tells the engine to skip a number of rows. The engine cannot jump to that position. It must produce the rows in order and count past the skipped ones. On a big table, an offset of a million rows means reading and discarding a million rows before returning the ten you asked for. The well-known cure is keyset pagination, also called the seek method: filter by the last seen key using a condition such as “key greater than last key”, with an index on that key, and take the next ten.

The distributed nature of Elasticsearch adds a multiplier. In a single-node database, a deep offset wastes work in one place. In Elasticsearch, the waste is repeated on every shard and then again at the merge. That is why the ten-thousand limit exists by default.

Pagination decisions are made at several layers. Each layer can help or hurt.

flowchart TD
  U["Browser or mobile app"] -->|"page number or cursor token"| G["Gateway or backend API"]
  G -->|"validates depth, rate limits, builds query"| CO["Coordinating node"]
  CO --> D["Data nodes with shards"]
  G -.->|"caches popular first pages"| CA["Cache"]
        

A good rule is that clients should never talk to Elasticsearch directly for user-facing search. A backend in between can enforce the maximum page size and depth in one place, and it can change the pagination method later without changing the client.

A request that is expensive to serve but cheap to send is an invitation to abuse.

Deep pagination fits this pattern perfectly. A single short request with a large offset can consume a lot of memory and processing on the cluster. Attackers can send many such requests to slow or crash a service. But harm does not need bad intent. A search engine crawler that follows the next page links of a public site can walk to page after page, and slowly push the deep cost higher and higher.

You can find deep pagination problems before users complain, if you watch the right signals.

Track at the application level too

Elasticsearch does not give you a ready-made chart of the offsets that users request. So log the requested page number and page size in your own backend. A simple chart of the ninety-fifth and ninety-ninth percentile of the requested depth quickly shows whether deep pagination is happening. Add an alert when a single client crosses a threshold of deep requests in a short time.

Common symptoms, their likely causes, and what to do first.

Your index design decides how painful deep pages are. Shard count is the biggest lever.

Recall that the merge cost is proportional to the number of shards. An index with one hundred small shards will suffer from deep pagination ten times more than the same data in ten well-sized shards. Over-sharding is a common mistake, because each shard is a full search engine with its own overhead, and every search touches all of them.

These habits keep search fast and pagination safe.

These mistakes appear again and again in real incidents.

A checklist to keep beside you when designing paged search.

Every pagination method trades something for something else.

Offset pagination

PIT plus search after

The summary is that cursor methods trade freedom of navigation for predictable cost. Since real users rarely jump around deeply, and machines never need to, that trade is nearly always a good one.

These stories show the problem and its cure in familiar settings.

Some beliefs about pagination cause avoidable trouble. Let us test them.

Let us put two requests side by side and follow every step. The only difference is the offset, yet the journey is very different.

Both requests ask for ten results, sorted by relevance, on an index with ten shards. Request A asks for page one, with an offset of zero. Request B asks for page one thousand, with an offset of 9,990. Both are allowed, since request B just fits inside the default window.

flowchart LR
  subgraph A["Request A: from 0, size 10"]
    A1["Each shard builds a queue of 10"] --> A2["Coordinator merges 100 entries"] --> A3["Fetch 10 documents"]
  end
  subgraph B["Request B: from 9,990, size 10"]
    B1["Each shard builds a queue of 10,000"] --> B2["Coordinator merges 100,000 entries"] --> B3["Fetch 10 documents"]
  end
        

The fetch phase is identical, because only ten documents are needed. The query phase for request B does one thousand times more sorting work. And if fifty people request pages this deep at the same time, the shards and the coordinating node must build fifty such queues at the same time, in the same heap.

Deep pagination hurts other users through shared queues. Understanding those queues explains the strange slowdowns.

Every data node has a fixed number of worker threads dedicated to search, and a waiting line called a queue for requests that arrive while all workers are busy. Each shard-level part of a search takes a thread for as long as it runs. A deep page makes each shard part run longer, because building a long queue takes time. That means threads are occupied for longer, and the waiting line grows.

When the waiting line is full, the node refuses new search work and returns a rejection to the caller. Ordinary, cheap searches are then rejected just because they arrived while a few deep requests were holding all the threads. The victims are innocent users of the search box, while the cause was somebody browsing page ten thousand.

Built-in helpers

Elasticsearch has several features that soften the blow. The coordinating node merges shard results in batches instead of all at once, using a setting that controls the batch size, so that memory does not spike as much on wide searches. Searches can be given a timeout, and can return partial results if some shards are slow. Adaptive replica selection routes requests towards shard copies that respond faster. These help, but they do not remove the underlying cost of a deep page.

Good pagination starts in the mapping. A few small decisions make cursors reliable and cheap.

Cursor pagination depends on sorting, and sorting depends on doc values, the column-style structure that stores each field’s value per document. So every field that appears in your sort must be a type that has doc values, such as a keyword, a number, or a date. A field that is only analyzed text cannot be used.

Sorting by relevance score

Sorting by relevance is the default, and it works with cursors too. But scores can be almost equal for many documents, and they can differ slightly between shard copies. With a frozen view and a tiebreaker, relevance-sorted cursors work fine. Without them, expect some jitter. Also remember that users rarely need relevance beyond the first few pages, so a limit on depth for relevance-sorted searches is very reasonable.

Sometimes a search is heavy for reasons other than paging. Asynchronous search can make such requests friendlier.

The async search API lets you submit a search and get back an identifier immediately instead of waiting for the final result. You can then poll for progress, and even read partial results while shards are still working. This is useful for large searches over many indices, or over slow storage tiers, where waiting on one long open connection is awkward.

Async search does not remove the cost of deep pagination. It changes only how you wait. But it pairs well with the other tools. For example, a heavy exploratory search can run asynchronously with a timeout, and the user sees progress and partial data while the cluster works in the background.

Many tools around Elasticsearch already handle this problem for you. Knowing how helps you use them correctly.

Do not guess how your cluster behaves at depth. Measure it, and test correctness as well as speed.

If your application already uses deep offsets, you can move to cursors safely in steps.

Use this list in design reviews and before release. Each item prevents a real incident that teams have met in production.

Keep these plain-language definitions handy. They make conversations with teammates and documentation much easier to follow.

When a teammate says “we hit the window”, they mean offset plus size went over the limit. When they say “we need a cursor”, they mean the team should stop skipping and start continuing. Sharing this vocabulary makes design discussions shorter and clearer.

It is the fact that the cost of a page grows with how far down the results it starts. Each shard must build a list of from plus size entries, and the coordinating node must merge all of those lists, only to throw away everything except the final page.

The default result window setting limits from plus size to ten thousand, to protect memory and latency. It is a safety limit, and the error tells you to use scroll or search after for deeper traversal.

Only in narrow cases with few shards, low traffic, and trusted users. In general it just removes the safety fence, while the cost still grows with depth and shard count.

Scroll keeps a snapshot and a position on the servers and is meant for batch jobs. Search after is stateless and uses the sort values of the last hit as the cursor. With a point in time, search after also gives a consistent view.

A lightweight frozen view of one or more indices. Searches that use its identifier all see the same data, even if documents change afterwards. It must be closed when finished.

If several documents share the same sort values, the cursor cannot point to one exact position, so documents may be skipped or repeated. A unique second sort field, or the automatic one that comes with a point in time, fixes this.

Not directly. You can only continue from a known position. If you need jumps, cap the depth and offer filters, or use offset pagination for the shallow pages.

Either store the cursors of pages already visited and reuse them, or run the query with the sort order reversed starting from the first hit of the current page, then reverse the results before showing them.

Because the data may have changed, sort values may tie, or different copies of a shard may answer. Use a point in time, a unique tiebreaker, and a stable preference value per session.

Not much. The fetch phase retrieves only the documents of the final page. The heavy cost is in the query phase, where every shard builds a long list of entries.

Yes. The coordinating node must merge from plus size entries from every shard, so the merge cost grows with the shard count. Right-sizing shards helps all searches.

Use a point in time with search after, and use slices to read in parallel. A simple scroll is also fine for a one-time copy. Do not use large offsets.

Use a composite aggregation. Each response includes an after key, which you send in the next request to continue from where you stopped.

Show an approximate value such as more than ten thousand. Exact counts require visiting every matching document, which is costly for large result sets and rarely valuable to users.

Validate and cap page depth and size in your backend, apply rate limits, and use crawler rules and interface design that do not invite bots to walk thousands of result pages.

Use the search slow log, watch coordinating node heap and garbage collection, track breaker trips and rejections, and log the requested depth in your own application so you can chart and alert on it.

The deep pagination problem exists because offset pagination in a distributed search engine forces every shard to build a sorted list as long as the offset plus the page size, and forces the coordinating node to merge all of those lists, only to keep a handful of results. The cost grows with the depth of the page and with the number of shards, and it is paid again for every page. Elasticsearch protects itself with a default result window of ten thousand. The healthy way forward is to use offset pagination only for shallow pages and to use a point in time with search after for deep traversal, with a unique tiebreaker, closed contexts, and limits at your backend. Like the librarian in our opening story, the cluster works best when you give it a bookmark to continue from, instead of asking it to count from the beginning every time.