How to Use search_after for Pagination in Elasticsearch

Use the search_after parameter in Elasticsearch to paginate results efficiently by providing the sort values of the last document from the previous page. This method requires a consistent sort order and is ideal for deep pagination without performance loss.

Syntax

The search_after parameter is used inside the body of a search request along with a sort clause. It takes an array of values that represent the sort keys of the last document from the previous page.

Example parts:

• sort: Defines the order of results (e.g., by timestamp and _id).
• search_after: An array of values matching the sort fields from the last hit of the previous page.

json

{
  "sort": [
    {"timestamp": "asc"},
    {"_id": "asc"}
  ],
  "search_after": ["2023-06-01T12:00:00", "abc123"]
}

Example

This example shows how to paginate through documents sorted by timestamp and _id. The first query fetches the first page. The second query uses search_after with the last hit's sort values to get the next page.

json

POST /my_index/_search
{
  "size": 2,
  "sort": [
    {"timestamp": "asc"},
    {"_id": "asc"}
  ]
}


# Suppose the last hit from above has sort values ["2023-06-01T12:00:00", "abc123"]

POST /my_index/_search
{
  "size": 2,
  "sort": [
    {"timestamp": "asc"},
    {"_id": "asc"}
  ],
  "search_after": ["2023-06-01T12:00:00", "abc123"]
}

Output

{
  "hits": {
    "hits": [
      {
        "_id": "def456",
        "_source": {"timestamp": "2023-06-01T12:01:00", "message": "Next event"},
        "sort": ["2023-06-01T12:01:00", "def456"]
      },
      {
        "_id": "ghi789",
        "_source": {"timestamp": "2023-06-01T12:02:00", "message": "Another event"},
        "sort": ["2023-06-01T12:02:00", "ghi789"]
      }
    ]
  }
}

Common Pitfalls

• Missing or inconsistent sort clause: search_after requires a stable and consistent sort order, usually including a unique field like _id to avoid duplicates.
• Using from with search_after: These two pagination methods should not be combined.
• Incorrect search_after values: The array must exactly match the sort fields in order and type from the last hit.

json

POST /my_index/_search
{
  "size": 2,
  "sort": [
    {"timestamp": "asc"}
  ],
  "search_after": ["2023-06-01T12:00:00", "abc123"]
}

Quick Reference

Parameter	Description	Notes
sort	Defines the order of results	Must be consistent and include unique fields
search_after	Array of sort values from last hit	Used to fetch next page after last document
size	Number of results per page	Controls page size
from	Offset for pagination	Do not use with search_after

Key Takeaways

Use search_after with a consistent sort order including unique fields for reliable pagination.

Pass the last hit's sort values exactly as the search_after array to get the next page.

Do not combine search_after with from; they are different pagination methods.

search_after is efficient for deep pagination compared to from/size.

Always include a unique field like _id in sort to avoid duplicate or missing results.