--- layout: default title: Point in Time API nav_order: 59 has_children: false parent: Point in Time grand_parent: Searching data redirect_from: - /opensearch/point-in-time-api/ - /search-plugins/point-in-time-api/ --- # Point in Time API Use the [Point in Time (PIT)]({{site.url}}{{site.baseurl}}/opensearch/point-in-time/) API to manage PITs. --- #### Table of contents - TOC {:toc} --- ## Create a PIT Introduced 2.4 {: .label .label-purple } Creates a PIT. The `keep_alive` query parameter is required; it specifies how long to keep a PIT. ### Path and HTTP methods ```json POST //_search/point_in_time?keep_alive=1h&routing=&expand_wildcards=&preference= ``` ### Path parameters Parameter | Data type | Description :--- | :--- | :--- target_indexes | String | The name(s) of the target index(es) for the PIT. May contain a comma-separated list or a wildcard index pattern. ### Query parameters Parameter | Data type | Description :--- | :--- | :--- keep_alive | Time | The 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. preference | String | The node or the shard used to perform the search. Optional. Default is random. routing | String | Specifies to route search requests to a specific shard. Optional. Default is the document's `_id`. expand_wildcards | String | The 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_creation | Boolean | Specifies whether to create a PIT with partial failures. Optional. Default is `true`. #### Example request ```json POST /my-index-1/_search/point_in_time?keep_alive=100m ``` #### Example response ```json { "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA", "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "creation_time": 1658146050064 } ``` ### Response fields Field | Data type | Description :--- | :--- | :--- pit_id | [Base64 encoded binary]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary) | The PIT ID. creation_time | long | The 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: ```json 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. {: .note} ## List all PITs Introduced 2.4 {: .label .label-purple } 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 ```json GET /_search/point_in_time/_all ``` #### Example response ```json { "pits": [ { "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAEWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA", "creation_time": 1658146048666, "keep_alive": 6000000 }, { "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFnNOWU43ckt3U3IyaFVpbGE1UWEtMncAFjFyeXBsRGJmVFM2RTB6eVg1aVVqQncAAAAAAAAAAAIWcDVrM3ZIX0pRNS1XejE5YXRPRFhzUQEWc05ZTjdyS3dTcjJoVWlsYTVRYS0ydwAA", "creation_time": 1658146050064, "keep_alive": 6000000 } ] } ``` ### Response fields Field | Data type | Description :--- | :--- | :--- pits | Array of JSON objects | The list of all PITs. Each PIT object contains the following fields. Field | Data type | Description :--- | :--- | :--- pit_id | [Base64 encoded binary]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary) | The PIT ID. creation_time | long | The time the PIT was created, in milliseconds since the epoch. keep_alive | long | The amount of time to keep the PIT, in milliseconds. ## Delete PITs Introduced 2.4 {: .label .label-purple } 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 ```json 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 Field | Data type | Description :--- | :--- | :--- pit_id | [Base64 encoded binary]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary) or an array of binaries | The PIT IDs of the PITs to be deleted. Required. #### Example request: Delete PITs by ID ```json 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. ```json { "pits": [ { "successful": true, "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" }, { "successful": false, "pit_id": "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" } ] } ``` ### Response fields Field | Data type | Description :--- | :--- | :--- successful | Boolean | Whether the delete operation was successful. pit_id | [Base64 encoded binary]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary) | The PIT ID of the PIT to be deleted. ## PIT segments Introduced 2.4 {: .label .label-purple } Similarly to the [CAT Segments API]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-segments), 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 ```json 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 Field | Data type | Description :--- | :--- | :--- pit_id | [Base64 encoded binary]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary) or an array of binaries | The PIT IDs of the PITs whose segments are to be listed. Required. #### Example request: PIT segments of PITs by ID ```json GET /_cat/pit_segments { "pit_id": [ "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA", "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" ] } ``` #### Example response ```json index shard prirep ip segment generation docs.count docs.deleted size size.memory committed searchable version compound index1 0 r 10.212.36.190 _0 0 4 0 3.8kb 1364 false true 8.8.2 true index1 1 p 10.212.36.190 _0 0 3 0 3.7kb 1364 false true 8.8.2 true 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. Setting | Description | Default :--- | :--- | :--- point_in_time.max_keep_alive | A cluster-level setting that specifies the maximum value for the `keep_alive` parameter. | 24h search.max_open_pit_context | A node-level setting that specifies the maximum number of open PIT contexts for the node. | 300