Point in time API
editPoint in time API
editA search request by default executes against the most recent visible data of the target indices, which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple search requests using the same point in time. For example, if refreshes happen between search_after requests, then the results of those requests might not be consistent as changes happening between searches are only visible to the more recent point in time.
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
read
index privilege for the target data stream, index, or index alias.
Examples
editA point in time must be opened explicitly before being used in search requests. The
keep_alive parameter tells Elasticsearch how long it should keep a point in time alive,
e.g. ?keep_alive=5m
.
POST /my-index-000001/_pit?keep_alive=1m
The result from the above request includes a id
, which should
be passed to the id
of the pit
parameter of a search request.
POST /_search { "size": 100, "query": { "match" : { "title" : "elasticsearch" } }, "pit": { "id": "46ToAwMDaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQNpZHkFdXVpZDIrBm5vZGVfMwAAAAAAAAAAKgFjA2lkeQV1dWlkMioGbm9kZV8yAAAAAAAAAAAMAWICBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", "keep_alive": "1m" } }
A search request with the |
|
The |
|
The |
The open point in time request and each subsequent search request can
return different id
; thus always use the most recently received id
for the
next search request.
Keeping point in time alive
editThe keep_alive
parameter, which is passed to a open point in time request and
search request, extends the time to live of the corresponding point in time.
The value (e.g. 1m
, see Time units) does not need to be long enough to
process all data — it just needs to be long enough for the next request.
Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments. Once the smaller segments are no longer needed they are deleted. However, open point-in-times prevent the old segments from being deleted since they are still in use.
Keeping older segments alive means that more disk space and file handles are needed. Ensure that you have configured your nodes to have ample free file handles. See File Descriptors.
Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request. Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.
You can check how many point-in-times (i.e, search contexts) are open with the nodes stats API:
GET /_nodes/stats/indices/search
Close point in time API
editPoint-in-time is automatically closed when its keep_alive
has
been elapsed. However keeping point-in-times has a cost, as discussed in the
previous section. Point-in-times should be closed
as soon as they are no longer used in search requests.
DELETE /_pit { "id" : "46ToAwMDaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQNpZHkFdXVpZDIrBm5vZGVfMwAAAAAAAAAAKgFjA2lkeQV1dWlkMioGbm9kZV8yAAAAAAAAAAAMAWIBBXV1aWQyAAA=" }
The API returns the following response: