Point in Time API

Use the Point in Time (PIT) API to manage PITs.


Create a PIT

Introduced 2.4

Creates a PIT. The keep_alive query parameter is required; it specifies how long to keep a PIT.

Path and HTTP methods

  1. POST /<target_indexes>/_search/point_in_time?keep_alive=1h&routing=&expand_wildcards=&preference=

Path parameters

ParameterData typeDescription
target_indexesStringThe name(s) of the target index(es) for the PIT. May contain a comma-separated list or a wildcard index pattern.

Query parameters

ParameterData typeDescription
keep_aliveTimeThe amount of time to keep the PIT. Every time you access a PIT by using the Search API, the PIT lifetime is extended by the amount of time equal to the keep_alive parameter. Required.
preferenceStringThe node or the shard used to perform the search. Optional. Default is random.
routingStringSpecifies to route search requests to a specific shard. Optional. Default is the document’s _id.
expand_wildcardsStringThe type of index that can match the wildcard pattern. Supports comma-separated values. Valid values are the following:
- all: Match any index or data stream, including hidden ones.
- open: Match open, non-hidden indexes or non-hidden data streams.
- closed: Match closed, non-hidden indexes or non-hidden data streams.
- hidden: Match hidden indexes or data streams. Must be combined with open, closed or both open and closed.
- none: No wildcard patterns are accepted.
Optional. Default is open.
allow_partial_pit_creationBooleanSpecifies whether to create a PIT with partial failures. Optional. Default is true.

Example request

  1. POST /my-index-1/_search/point_in_time?keep_alive=100m

Example response

  1. {
  2. "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
  3. "_shards": {
  4. "total": 1,
  5. "successful": 1,
  6. "skipped": 0,
  7. "failed": 0
  8. },
  9. "creation_time": 1658146050064
  10. }

Response fields

FieldData typeDescription
pit_idBase64 encoded binaryThe PIT ID.
creation_timelongThe time the PIT was created, in milliseconds since the epoch.

Extend a PIT time

You can extend a PIT time by providing a keep_alive parameter in the pit object when you perform a search:

  1. GET /_search
  2. {
  3. "size": 10000,
  4. "query": {
  5. "match" : {
  6. "user.id" : "elkbee"
  7. }
  8. },
  9. "pit": {
  10. "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==",
  11. "keep_alive": "100m"
  12. },
  13. "sort": [
  14. {"@timestamp": {"order": "asc", "format": "strict_date_optional_time_nanos"}},
  15. {"_shard_doc": "desc"}
  16. ],
  17. "search_after": [
  18. "2021-05-20T05:30:04.832Z"
  19. ]
  20. }

The keep_alive parameter in a search request is optional. It specifies the amount by which to extend the time to keep a PIT.

List all PITs

Introduced 2.4

Returns all PITs in the OpenSearch cluster.

Cross-cluster behavior

The List All PITs API returns only local PITs or mixed PITs (PITs created in both local and remote clusters). It does not return fully remote PITs.

Example request

  1. GET /_search/point_in_time/_all

Example response

  1. {
  2. "pits": [
  3. {
  4. "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAEWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
  5. "creation_time": 1658146048666,
  6. "keep_alive": 6000000
  7. },
  8. {
  9. "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
  10. "creation_time": 1658146050064,
  11. "keep_alive": 6000000
  12. }
  13. ]
  14. }

Response fields

FieldData typeDescription
pitsArray of JSON objectsThe list of all PITs.

Each PIT object contains the following fields.

FieldData typeDescription
pit_idBase64 encoded binaryThe PIT ID.
creation_timelongThe time the PIT was created, in milliseconds since the epoch.
keep_alivelongThe amount of time to keep the PIT, in milliseconds.

Delete PITs

Introduced 2.4

Deletes one, several, or all PITs. PITs are automatically deleted when the keep_alive time period elapses. However, to deallocate resources, you can delete a PIT using the Delete PIT API. The Delete PIT API supports deleting a list of PITs by ID or deleting all PITs at once.

Cross-cluster behavior

The Delete PITs by ID API fully supports deleting cross-cluster PITs.

The Delete All PITs API deletes only local PITs or mixed PITs (PITs created in both local and remote clusters). It does not delete fully remote PITs.

Sample Request: Delete all PITs

  1. DELETE /_search/point_in_time/_all

If you want to delete one or several PITs, specify their PIT IDs in the request body.

Request fields

FieldData typeDescription
pit_idBase64 encoded binary or an array of binariesThe PIT IDs of the PITs to be deleted. Required.

Example request: Delete PITs by ID

  1. DELETE /_search/point_in_time
  2. {
  3. "pit_id": [
  4. "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA",
  5. "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
  6. ]
  7. }

Example response

For each PIT, the response contains a JSON object with a PIT ID and a successful field that specifies whether the deletion was successful. Partial failures are treated as failures.

  1. {
  2. "pits": [
  3. {
  4. "successful": true,
  5. "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
  6. },
  7. {
  8. "successful": false,
  9. "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
  10. }
  11. ]
  12. }

Response fields

FieldData typeDescription
successfulBooleanWhether the delete operation was successful.
pit_idBase64 encoded binaryThe PIT ID of the PIT to be deleted.

PIT segments

Introduced 2.4

Similarly to the CAT Segments API, the PIT Segments API provides low-level information about the disk utilization of a PIT by describing its Lucene segments. The PIT Segments API supports listing segment information of a specific PIT by ID or of all PITs at once.

Example request: PIT segments of all PITs

  1. GET /_cat/pit_segments/_all

If you want to list segments for one or several PITs, specify their PIT IDs in the request body.

Request fields

FieldData typeDescription
pit_idBase64 encoded binary or an array of binariesThe PIT IDs of the PITs whose segments are to be listed. Required.

Example request: PIT segments of PITs by ID

  1. GET /_cat/pit_segments
  2. {
  3. "pit_id": [
  4. "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA",
  5. "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
  6. ]
  7. }

Example response

  1. index shard prirep ip segment generation docs.count docs.deleted size size.memory committed searchable version compound
  2. index1 0 r 10.212.36.190 _0 0 4 0 3.8kb 1364 false true 8.8.2 true
  3. index1 1 p 10.212.36.190 _0 0 3 0 3.7kb 1364 false true 8.8.2 true
  4. index1 2 r 10.212.74.139 _0 0 2 0 3.6kb 1364 false true 8.8.2 true

PIT settings

You can specify the following settings for a PIT.

SettingDescriptionDefault
point_in_time.max_keep_aliveA cluster-level setting that specifies the maximum value for the keep_alive parameter.24h
search.max_open_pit_contextA node-level setting that specifies the maximum number of open PIT contexts for the node.300