[DOC] Document cat/pit_segments API

[nateynateynate]

What do you want to do?

• Request a change to existing documentation
• Add new documentation

Tell us about your request. Provide a summary of the request.

Related to: opensearch-project/opensearch-api-specification#373

We should probably mention that if the index for which you are creating a PIT doesn't have any data in it, that the call to list the pit_segments either by ID or with _all will return an empty response with a response code of 400.

*Version: List the OpenSearch version to which this issue applies, e.g. 2.14, 2.12--2.14, or all.

2.14

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.

https://opensearch.slack.com/archives/C04UM4D6XN2/p1719956200725049?thread_ts=1719946620.686809&cid=C04UM4D6XN2

[dblock]

There's some confusion I think. I raised a question in Slack on the API, but it was the _cat/pit_segments API. We don't document it, renamed this issue to document that.

curl -k -u admin:$OPENSEARCH_PASSWORD -X PUT https://localhost:9200/foobars
curl -k -u admin:$OPENSEARCH_PASSWORD -X POST https://localhost:9200/foobars/_search/point_in_time?keep_alive=10m

{"pit_id":"w8-CQQEHZm9vYmFycxY3VzQ1bldiSVFhQzdaU0I5OWROd3VnABZQOUkwaUFDSlFFR1o1NzFlUHI1V2FRAAAAAAAAAANRFmNnUndQbUZ5U1FlajVOODE5TEg1U0EBFjdXNDVuV2JJUWFDN1pTQjk5ZE53dWcAAA==","_shards":{"total":1,"successful":1,"skipped":0,"failed":0},"creation_time":1719946495264}

This will return nothing because there are no segments (no data), which deserves to be noted.

curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/pit_segments/_all?format=json

Insert data

$ curl -k -u admin:$OPENSEARCH_PASSWORD -H "Content-type: application/json" -X POST https://localhost:9200/foobars/_doc -d'{"x":1}'

Now it returns something.

[
  {
    "index": "foobars",
    "shard": "0",
    "prirep": "p",
    "ip": "172.21.0.2",
    "segment": "_0",
    "generation": "0",
    "docs.count": "1",
    "docs.deleted": "0",
    "size": "2.9kb",
    "size.memory": "0",
    "committed": "false",
    "searchable": "true",
    "version": "9.10.0",
    "compound": "true"
  }
]

This API also supports getting PIT segments for a specific PIT. With 2 PITs.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/pit_segments/_all?format=json | jq

[
  {
    "index": "foobars",
    "shard": "0",
    "prirep": "p",
    "ip": "172.21.0.2",
    "segment": "_0",
    "generation": "0",
    "docs.count": "1",
    "docs.deleted": "0",
    "size": "2.9kb",
    "size.memory": "0",
    "committed": "true",
    "searchable": "true",
    "version": "9.10.0",
    "compound": "true"
  },
  {
    "index": "foobars",
    "shard": "0",
    "prirep": "p",
    "ip": "172.21.0.2",
    "segment": "_0",
    "generation": "0",
    "docs.count": "1",
    "docs.deleted": "0",
    "size": "2.9kb",
    "size.memory": "0",
    "committed": "false",
    "searchable": "true",
    "version": "9.10.0",
    "compound": "true"
  }
]

It's a GET with a body, yes.

$ curl -k -u admin:$OPENSEARCH_PASSWORD -X GET -H "Content-type: application/json" https://localhost:9200/_cat/pit_segments?format=json -d'{"pit_id":["w8-CQQEHZm9vYmFycxYtUG1HZjB6M1ExcVdnNXc3eFh4NzVnABZBeE1YSDFwblExYXktSXhQV0taZXpnAAAAAAAAAABtFmtuVU9OMWlSVFdlMmFMU2VlSDhBbVEBFi1QbUdmMHozUTFxV2c1dzd4WHg3NWcAAB=="]}' | jq

[
  {
    "index": "foobars",
    "shard": "0",
    "prirep": "p",
    "ip": "172.21.0.2",
    "segment": "_0",
    "generation": "0",
    "docs.count": "1",
    "docs.deleted": "0",
    "size": "2.9kb",
    "size.memory": "0",
    "committed": "false",
    "searchable": "true",
    "version": "9.10.0",
    "compound": "true"
  }
]

Spec test: https://github.com/opensearch-project/opensearch-api-specification/blob/main/tests/cat/pit_segments.yaml