iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
opensearch-docs-cn/_search-plugins/point-in-time-api.md

9.6 KiB
Raw Blame History

layout title nav_order has_children parent redirect_from
default Point in Time API 59 false Point in Time
/opensearch/point-in-time-api/

Point in Time API

Use the Point in Time (PIT) 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

POST /<target_indexes>/_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

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 fields

Field Data type Description
pit_id Base64 encoded 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:

GET /_search
{
  "size": 10000,
  "query": {
    "match" : {
      "user.id" : "elkbee"
    }
  },
  "pit": {
    "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
    "keep_alive": "100m"
  },
  "sort": [ 
    {"@timestamp": {"order": "asc", "format": "strict_date_optional_time_nanos"}},
    {"_shard_doc": "desc"}
  ],
  "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

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 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 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

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 or an array of binaries The PIT IDs of the PITs to be deleted. Required.

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 fields

Field Data type Description
successful Boolean Whether the delete operation was successful.
pit_id Base64 encoded binary The PIT ID of the PIT to be deleted.

PIT segments

Introduced 2.4 {: .label .label-purple }

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

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 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

GET /_cat/pit_segments

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

Example response

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