Adds Point in Time documentation

[kolchfa-aws]

Fixes #674

Checklist

• [x ] By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
  For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[dhruv16dhr]

Should we not mention the default keep-alive timeout and how we can extend the same ??

[bharath-techie]

added comment above for extending keep alive via search api. right now keep alive is mandatory in create pit.

[kolchfa-aws]

Done.

[bharath-techie]

Can we also add a snippet where user can extend keep alive using search API.

```json
GET /_search
{
  "size": 10000,
  "query": {
    "match" : {
      "user.id" : "elkbee"
    }
  },
  "pit": {
    "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
    "keep_alive": "100m" <--- //optional to extend a PIT's keep alive. The new expiry will be last accessed time + max of (request keep alive , current keep alive )
  },
  "sort": [ 
    {"@timestamp": {"order": "asc", "format": "strict_date_optional_time_nanos"}},
    {"_shard_doc": "desc"}
  ]
}

[bharath-techie]

Can we also add info about these cluster settings.

• We limit the maximum keep-alive of a PIT using a cluster level setting point_in_time.max_keep_alive (defaults to 24h . Users can change it as required.])
• We limit the number of open PIT contexts on each node using a node level setting search.max_open_pit_context (Defaults to 300.)

[bharath-techie]

Lets update these fields as follows :

• open_pit_contexts -> search.point_in_time_current
• pit_time_in_millis -> search.point_in_time_time
• pit_total -> search.point_in_time_total

[bharath-techie]

Lets update these fields as follows :

open_pit_contexts -> search.point_in_time_current
pit_time_in_millis -> search.point_in_time_time
pit_total -> search.point_in_time_total

[bharath-techie]

id -> pit_id

[bharath-techie]

id -> pit_id

[pranikum]

Creates a PIT. The required query parameter keep_alive specifies how long to keep this PIT.

[Arpit-Bandejiya]

use point_in_time_total instead of search.point_in_time_total

[Arpit-Bandejiya]

same as above

[Arpit-Bandejiya]

same as above

[Arpit-Bandejiya]

The results for _node/stats for search attribute is:

"search": {
                    "open_contexts": 0,
                    "query_total": 0,
                    "query_time_in_millis": 0,
                    "query_current": 0,
                    "fetch_total": 0,
                    "fetch_time_in_millis": 0,
                    "fetch_current": 0,
                    "scroll_total": 0,
                    "scroll_time_in_millis": 0,
                    "scroll_current": 0,
                    "point_in_time_total": 0,
                    "point_in_time_time_in_millis": 0,
                    "point_in_time_current": 0,
                    "suggest_total": 0,
                    "suggest_time_in_millis": 0,
                    "suggest_current": 0
                }

please remove search.

[Arpit-Bandejiya]

PIT do not support preference.

[bharath-techie]

This is for create PIT, which does support preference. please add it back @kolchfa-aws

[Arpit-Bandejiya]

Can we give a comment that this is optional in search to give more stress? and provide it's default value as well?

[kolchfa-aws]

I will add the note below the request that the parameter is optional. What is the default value?

[Arpit-Bandejiya]

1m is the default value

[bharath-techie]

In search it should be completely optional. there is no default val as of now.

[Arpit-Bandejiya]

Can we give an example of list all PITS api here?

[kolchfa-aws]

The example is in the "sample request" section below.

[Arpit-Bandejiya]

should we mention in comments that this one is local PIT or remote pit? @bharath-techie

[bharath-techie]

Lets not do that for now, it might be confusing for user.

[Arpit-Bandejiya]

@bharath-techie @dhruv16dhr Should we have the cross cluster behaviour in different section for PIT apis? Defining it like this can be confusing for a new user since we are giving sample example under cross-cluster behaviour for delete and list PITS

[bharath-techie]

I feel like as a user , they might miss reading upon cross cluster behavior if its down below.

[Arpit-Bandejiya]

this should be PITs by ID I think. @bharath-techie please do give your view.

[bharath-techie]

Yeah this should be "PIT segments for list of PITs"

[vagimeli]

Minimal edits. Looks good.

[vagimeli]

If "Settings" isn't a proper name, lowercase it.

[vagimeli]

Change to read "PIT search"

[vagimeli]

Lowercase "Security"

[vagimeli]

Change "don't" to "doesn't"

[vagimeli]

Should this read "List all PIT APIs?"

[kolchfa-aws]

The API name is "list all PITs"

[natebower]

Or is it "List All PITs API" (it's capitalized in an earlier instance)?

[vagimeli]

Is "ISM" a noun or acronym? If an acronym, define it.

[ariamarble]

Suggested change

	Field | Data Type | Description |
	Field | Data Type | Description

[kolchfa-aws]

Implemented, although this does not make a difference in rendering :)

[ariamarble]

should "Segments" be capitalized in this section?

[kolchfa-aws]

That's the API name so should be capitalized.

[natebower]

I had the same question. There are previous headings, for example, "Delete all PITs", where we did not capitalize them as the name of the API. If the headings are intended to reflect the names of the APIs, let's capitalize them consistently, and would it make sense to include "API" in the headings for maximum clarity?

[kolchfa-aws]

Good point. Since there is no "official" name, I will make these sentence case and assume they refer to the action.

[ariamarble]

As there are no items past this one should we just say "Run a search query with a PIT ID:" ?

[ariamarble]

Suggested change

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

[ariamarble]

LGTM other than my comments

[natebower]

@kolchfa-aws Please see my comments and changes and let me know if you have any questions. Thanks!

[natebower]

"The amount of time"?

[natebower]

If we are defining Point in Time as PIT, we should define it on first appearance and then use the acronym thereafter. Please apply to all files.

[natebower]

Suggested change

	Use the [Point in Time (PIT)]({{site.url}}{{site.baseurl}}/opensearch/point-in-time/) API to manage Points in Time.
	Use the [Point in Time (PIT)]({{site.url}}{{site.baseurl}}/opensearch/point-in-time/) API to manage PITs.

[natebower]

Suggested change

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

[natebower]

Suggested change

	creation_time | long | The time the PIT was created in milliseconds since the epoch.
	creation_time | long | The time the PIT was created, in milliseconds since the epoch.

[natebower]

Suggested change

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

[natebower]

Suggested change

	[Create PIT]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#create-a-pit) | `POST /<target_indexes>/_search/point_in_time?keep_alive=1h` | Creates a Point in Time.
	[Create PIT]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#create-a-pit) | `POST /<target_indexes>/_search/point_in_time?keep_alive=1h` | Creates a PIT.

[natebower]

Suggested change

	[List PIT]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#list-all-pits) | `GET /_search/point_in_time/_all` | Lists all Points in Time.
	[List PIT]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#list-all-pits) | `GET /_search/point_in_time/_all` | Lists all PITs.

[natebower]

Suggested change

	[Delete PIT]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#delete-pits) | `DELETE /_search/point_in_time`<br> `DELETE /_search/point_in_time/_all` | Deletes a Point in Time or all Points in Time.
	[Delete PIT]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#delete-pits) | `DELETE /_search/point_in_time`<br> `DELETE /_search/point_in_time/_all` | Deletes a PIT or all PITs.

[natebower]

Suggested change

	[PIT segments]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#pit-segments) | `GET /_cat/pit_segments/_all` | Provides information about the disk utilization of a Point in Time by describing its Lucene segments.
	[PIT segments]({{site.url}}{{site.baseurl}}/opensearch/point-in-time-api#pit-segments) | `GET /_cat/pit_segments/_all` | Provides information about the disk utilization of a PIT by describing its Lucene segments.