Point in Time

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

Table of contents

• Create a PIT
  • Endpoints
  • Path parameters
  • Query parameters
  • Response body fields
• Extend a PIT time
• List all PITs
  • Cross-cluster behavior
  • Response body fields
• Delete PITs
  • Cross-cluster behavior
  • Request body fields
  • Response body fields
• Security model
  • Alias permissions
  • Data stream permissions

Create a PIT

Introduced 2.4

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

Endpoints

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

Path parameters

Query parameters

Example request

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

Example response

{
    "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "creation_time": 1658146050064
}

Response body fields

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:

GET /_search
{
  "size": 10000,
  "query": {
    "match" : {
      "user.id" : "elkbee"
    }
  },
  "pit": {
    "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
    "keep_alive": "100m"
  },
  "sort": [ 
    {"@timestamp": {"order": "asc"}}
  ],
  "search_after": [  
    "2021-05-20T05:30:04.832Z"
  ]
}

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

GET /_search/point_in_time/_all

Example response

{
    "pits": [
        {
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAEWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
            "creation_time": 1658146048666,
            "keep_alive": 6000000
        },
        {
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA",
            "creation_time": 1658146050064,
            "keep_alive": 6000000
        }
    ]
}

Response body fields

Each PIT object contains the following fields.

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.

Example request: Delete all PITs

DELETE /_search/point_in_time/_all

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

Request body fields

Example request: Delete PITs by ID

DELETE /_search/point_in_time

{
    "pit_id": [
        "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA",
        "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
    ]
}

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.

{
    "pits": [
        {
            "successful": true,
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
        },
        {
            "successful": false,
            "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA"
        }
    ]
}

Response body fields

Security model

This section describes the permissions needed to use PIT API operations if you are running OpenSearch with the Security plugin enabled.

You can access all PIT API operations using the point_in_time_full_access role. If this role doesn’t meet your needs, mix and match individual PIT permissions to suit your use case. Each action corresponds to an operation in the REST API. For example, the indices:data/read/point_in_time/create permission lets you create a PIT. The following are the possible permissions:

• indices:data/read/point_in_time/create – Create API
• indices:data/read/point_in_time/delete – Delete API
• indices:data/read/point_in_time/readall – List All PITs API
• indices:data/read/search – Search API
• indices:monitor/point_in_time/segments – PIT Segments API

For all API operations, such as list all and delete all, the user needs the all indexes (*) permission. For API operations such as search, create PIT, or delete list, the user only needs individual index permissions.

The PIT IDs always contain the underlying (resolved) indexes when saved. The following sections describe the required permissions for aliases and data streams.

Alias permissions

For aliases, users must have either index or alias permissions for any PIT operation.

Data stream permissions

For data streams, users must have both the data stream and the data stream’s backing index permissions for any PIT operation. For example, the user must have permissions for the data-stream-11 data stream and for its backing index .ds-my-data-stream11-000001.

If users have the data stream permissions only, they will be able to create a PIT, but they will not be able to use the PIT ID for other operations, such as search, without the backing index permissions.