Point-in-time API in Elasticsearch

Introduction

The Point-in-time (PIT) API helps you get a stable view of your data at a specific moment. This means your search results won't change even if the data updates while you work.

When you want to page through search results without missing or repeating items.

When your data changes often but you need consistent search results.

When you want to avoid performance issues caused by deep pagination.

When you want to keep a snapshot of your data for a short time during complex queries.

Syntax

Elasticsearch

POST /_search
{
  "pit": {
    "id": "<pit-id>",
    "keep_alive": "1m"
  },
  "query": {
    "match_all": {}
  }
}

You first create a PIT by sending a search request with "pit": {"keep_alive": "1m"}.

Use the returned pit_id in subsequent searches to keep the view consistent.

Examples

Create a PIT for 1 minute and get the first 2 results.

Elasticsearch

POST /my-index/_search
{
  "pit": {
    "keep_alive": "1m"
  },
  "query": {
    "match_all": {}
  },
  "size": 2
}

Use an existing PIT ID to continue searching with the same snapshot.

Elasticsearch

POST /_search
{
  "pit": {
    "id": "46ToAwMDaWFiYzEyMzQ1Ng==",
    "keep_alive": "1m"
  },
  "query": {
    "match": {"field": "value"}
  },
  "size": 2
}

Sample Program

This example shows how to create a PIT and then use its ID to get the next page of results. The keep_alive keeps the PIT valid for 1 minute.

Elasticsearch

POST /my-index/_search
{
  "pit": {
    "keep_alive": "1m"
  },
  "query": {
    "match_all": {}
  },
  "size": 2
}

# Response example (simplified):
# {
#   "pit_id": "46ToAwMDaWFiYzEyMzQ1Ng==",
#   "hits": {
#     "hits": [ ... ]
#   }
# }

# Next search using PIT ID:
POST /_search
{
  "pit": {
    "id": "46ToAwMDaWFiYzEyMzQ1Ng==",
    "keep_alive": "1m"
  },
  "query": {
    "match_all": {}
  },
  "size": 2
}

Important Notes

Always set keep_alive to control how long the PIT stays open.

Remember to close PITs if you no longer need them to free resources.

PITs help avoid inconsistent results during pagination caused by data changes.

Summary

The Point-in-time API gives a stable snapshot of your data for consistent searches.

Use PIT IDs to page through results without missing or repeating items.

Set keep_alive to keep the PIT active for a limited time.