Add examples to search and open PIT APIs (elastic#3561) (elastic#3571)

(cherry picked from commit 9ea2901)

specification/_doc_ids/table.csv

@@ -66,6 +66,7 @@ ccr-put-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/refere
 ccr-put-follow,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-put-follow.html
 ccr-resume-auto-follow-pattern,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ccr-resume-auto-follow-pattern.html
 ccs-network-delays,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#ccs-network-delays
+ccs-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-cert.html#remote-clusters-privileges-ccs
 clean-up-snapshot-repo,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html#snapshots-repository-cleanup
 clear-repositories-metering-archive-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-repositories-metering-archive-api.html
 clear-scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-scroll-api.html
@@ -151,6 +152,7 @@ docs-termvectors,https://www.elastic.co/guide/en/elasticsearch/reference/{branch
 docs-update-by-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update-by-query.html
 docs-update,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update.html
 document-input-parameters,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-mlt-query.html#_document_input_parameters
+docvalue-fields,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#docvalue-fields
 dot-expand-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/dot-expand-processor.html
 drop-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/drop-processor.html
 enrich-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/enrich-processor.html
@@ -286,6 +288,7 @@ json-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/
 k-precision,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#k-precision
 k-recall,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#k-recall
 kv-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/kv-processor.html
+knn-approximate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search.html#approximate-knn
 knn-inner-hits,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search.html#nested-knn-search-inner-hits
 license-management,https://www.elastic.co/guide/en/kibana/{branch}/managing-licenses.html
 logstash-api-delete-pipeline,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/logstash-api-delete-pipeline.html
@@ -450,6 +453,7 @@ query-dsl-span-not-query,https://www.elastic.co/guide/en/elasticsearch/reference
 query-dsl-span-or-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-or-query.html
 query-dsl-span-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-term-query.html
 query-dsl-span-within-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-span-within-query.html
+query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-sparse-vector-query.html
 query-dsl-term-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-term-query.html
 query-dsl-terms-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-terms-query.html
 query-dsl-terms-set-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-terms-set-query.html
@@ -472,6 +476,7 @@ redact-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch
 regexp-syntax,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/regexp-syntax.html
 register-repository,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html
 registered-domain-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/registered-domain-processor.html
+relevance-scores,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-filter-context.html#relevance-scores
 remove-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remove-processor.html
 remote-clusters-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-api-key.html
 rename-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rename-processor.html
@@ -675,6 +680,7 @@ security-user-cache,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html
 set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html
 shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html
+shard-request-cache,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shard-request-cache.html
 simulate-ingest-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-ingest-api.html
 simulate-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-pipeline-api.html
 slice-scroll,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#slice-scroll
@@ -702,7 +708,7 @@ snapshot-repo-verify-integrity,https://www.elastic.co/guide/en/elasticsearch/ref
 sort-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-processor.html
 sort-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html
 sort-tiebreaker,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html#eql-search-specify-a-sort-tiebreaker
-query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-sparse-vector-query.html
+source-filtering,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#source-filtering
 split-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/split-processor.html
 sql-async-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html
 sql-async-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html
@@ -722,6 +728,7 @@ start-trial,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sta
 stop-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-dfanalytics.html
 stop-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-trained-model-deployment.html
 stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-transform.html
+stored-fields,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-fields.html#stored-fields
 synonym-rule-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-synonym-rule.html
 synonym-rule-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-synonym-rule.html
 synonym-rule-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonym-rule.html

specification/_global/open_point_in_time/OpenPointInTimeRequest.ts

@@ -33,13 +33,40 @@ import { Duration } from '@_types/Time'
  * between searches are only visible to the more recent point in time.
  *
  * A point in time must be opened explicitly before being used in search requests.
- * The `keep_alive` parameter tells Elasticsearch how long it should persist.
+ *
+ * A subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time.
+ *
+ * Just like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits.
+ * If you want to retrieve more hits, use PIT with `search_after`.
+ *
+ * IMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.
+ *
+ * When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception.
+ * To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.
+ *
+ * **Keeping point in time alive**
+ *
+ * The `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.
+ * The value does not need to be long enough to process all data — it just needs to be long enough for the next request.
+ *
+ * Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments.
+ * Once the smaller segments are no longer needed they are deleted.
+ * However, open point-in-times prevent the old segments from being deleted since they are still in use.
+ *
+ * TIP: Keeping older segments alive means that more disk space and file handles are needed.
+ * Ensure that you have configured your nodes to have ample free file handles.
+ *
+ * Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request.
+ * Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.
+ * Note that a point-in-time doesn't prevent its associated indices from being deleted.
+ * You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.
  * @rest_spec_name open_point_in_time
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id point-in-time-api
  * @index_privileges read
  * @doc_tag search
+ * @doc_id point-in-time-api
  */
 export interface Request extends RequestBase {
   urls: [
@@ -53,7 +80,7 @@ export interface Request extends RequestBase {
   }
   query_parameters: {
     /**
-     * Extends the time to live of the corresponding point in time.
+     * Extend the length of time that the point in time persists.
      */
     keep_alive: Duration
     /**
@@ -62,22 +89,23 @@ export interface Request extends RequestBase {
      */
     ignore_unavailable?: boolean
     /**
-     * Specifies the node or shard the operation should be performed on.
-     * Random by default.
+     * The node or shard the operation should be performed on.
+     * By default, it is random.
      */
     preference?: string
     /**
-     * Custom value used to route operations to a specific shard.
+     * A custom value that is used to route operations to a specific shard.
      */
     routing?: Routing
     /**
-     * Type of index that wildcard patterns can match.
+     * The type of index that wildcard patterns can match.
      * If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
-     * Supports comma-separated values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.
+     * It supports comma-separated values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`.
      * @server_default open
      */
     expand_wildcards?: ExpandWildcards
     /**
+     * Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT.
      * If `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.
      * If `true`, the point in time will contain all the shards that are available at the time of the request.
      * @server_default false
@@ -86,7 +114,7 @@ export interface Request extends RequestBase {
   }
   body: {
     /**
-     * Allows to filter indices if the provided query rewrites to `match_none` on every shard.
+     * Filter indices if the provided query rewrites to `match_none` on every shard.
      */
     index_filter?: QueryContainer
   }

specification/_global/open_point_in_time/examples/response/OpenPointInTimeResponseExample1.yaml

@@ -0,0 +1,16 @@
+# summary:
+description: >
+  A successful response from `POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true`.
+  It includes a summary of the total number of shards, as well as the number of successful shards when creating the PIT.
+# type: response
+# response_code: ''
+value: |-
+  {
+    "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=",
+    "_shards": {
+      "total": 10,
+      "successful": 10,
+      "skipped": 0,
+      "failed": 0
+    }
+  }