[DOCS] Add examples for mget, msearch template APIs (#3615) (#3631)

(cherry picked from commit 9b3c186)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -300,6 +300,7 @@ logstash-centralized-pipeline-management,https://www.elastic.co/guide/en/logstas
 logstash-configuration-file-structure,https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html
 logstash-logstash-settings-file,https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html
 lowercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/lowercase-processor.html
+mapbox-vector-tile,https://github.com/mapbox/vector-tile-spec/blob/master/README.md
 mapping-date-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-date-format.html
 mapping-meta-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-meta-field.html
 mapping-params,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-params.html
@@ -504,6 +505,7 @@ script-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/d
 script-languages,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-script-languages-api.html
 script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.html
 script-put,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/create-stored-script-api.html
+scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/scroll-api.html
 scroll-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results
 search-after,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after
 search-aggregations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations.html
@@ -592,8 +594,9 @@ search-render-query,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 search-count,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-count.html
 search-explain,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-explain.html
 search-field-caps,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-field-caps.html
+search-knn,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search-api.html
 search-multi-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-multi-search.html
-search-multi-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-multi-search.html
+search-multi-search-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/multi-search-template.html
 search-rank-eval,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html
 search-rank-eval,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html
 search-request-body,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-request-body.html

output/openapi/elasticsearch-serverless-openapi.json

@@ -35,11 +35,12 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
  * @availability serverless stability=stable visibility=public
  * @index_privileges view_index_metadata,read
  * @doc_tag search
+ * @doc_id search-field-caps
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.
+     * A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.
      */
     index?: Indices
   }
@@ -52,12 +53,12 @@ export interface Request extends RequestBase {
      */
     allow_no_indices?: boolean
     /**
-     * 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`.
+     * 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`.
      * @server_default open
      */
     expand_wildcards?: ExpandWildcards
     /**
-     * Comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.
+     * A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.
      */
     fields?: Fields
     /**
@@ -71,11 +72,15 @@ export interface Request extends RequestBase {
      */
     include_unmapped?: boolean
     /**
+     * A comma-separated list of filters to apply to the response.
      * @availability stack since=8.2.0
      * @availability serverless
      */
     filters?: string
     /**
+     * A comma-separated list of field types to include.
+     * Any fields that do not match one of these types will be excluded from the results.
+     * It defaults to empty, meaning that all field types are returned.
      * @availability stack since=8.2.0
      * @availability serverless
      */
@@ -90,17 +95,21 @@ export interface Request extends RequestBase {
   }
   body: {
     /**
-     * List of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.
+     * A list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.
      * @availability stack since=8.5.0
      * @availability serverless
      */
     fields?: Fields
     /**
-     * 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.
+     *
+     * IMPORTANT: The filtering is done on a best-effort basis, it uses index statistics and mappings to rewrite queries to `match_none` instead of fully running the request.
+     * For instance a range query over a date field can rewrite to `match_none` if all documents within a shard (including deleted documents) are outside of the provided range.
+     * However, not all queries can rewrite to `match_none` so this API may return an index even if the provided filter matches no document.
      */
     index_filter?: QueryContainer
     /**
-     * Defines ad-hoc runtime fields in the request similar to the way it is done in search requests.
+     * Define ad-hoc runtime fields in the request similar to the way it is done in search requests.
      * These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings.
      * @doc_id runtime-search-request
      * @availability stack since=7.12.0

output/schema/schema.json

@@ -29,6 +29,9 @@ import { FieldCapability } from './types'
  */
 export class Response {
   body: {
+    /**
+     * The list of indices where this field has the same type family, or null if all indices have the same type family for the field.
+     */
     indices: Indices
     fields: Dictionary<Field, Dictionary<string, FieldCapability>>
   }

specification/_doc_ids/table.csv

@@ -0,0 +1,16 @@
+# summary:
+# method_request: "POST my-index-*/_field_caps?fields=rating"
+description: >
+  Run `POST my-index-*/_field_caps?fields=rating` to get field capabilities and filter indices with a query.
+  Indices that rewrite the provided filter to `match_none` on every shard will be filtered from the response.
+# type: "request"
+value: |-
+  {
+    "index_filter": {
+      "range": {
+        "@timestamp": {
+          "gte": "2018"
+        }
+      }
+    }
+  }

specification/_global/field_caps/FieldCapabilitiesRequest.ts

@@ -0,0 +1,38 @@
+summary: Get two fields
+# type: "response"
+description: >
+  A successful response from `GET _field_caps?fields=rating,title`.
+  The field `rating` is defined as a long in `index1` and `index2` and as a `keyword` in `index3` and `index4`.
+  The field `rating` is not aggregatable in `index1`.
+  The field `rating` is not searchable in `index4`.
+  The field `title` is defined as text in all indices.
+# response_code: 200,
+value: |-
+  {
+    "indices": [ "index1", "index2", "index3", "index4", "index5" ],
+    "fields": {
+      "rating": {                                   
+        "long": {
+          "metadata_field": false,
+          "searchable": true,
+          "aggregatable": false,
+          "indices": [ "index1", "index2" ],
+          "non_aggregatable_indices": [ "index1" ]  
+        },
+        "keyword": {
+          "metadata_field": false,
+          "searchable": false,
+          "aggregatable": true,
+          "indices": [ "index3", "index4" ],
+          "non_searchable_indices": [ "index4" ]    
+        }
+      },
+      "title": {                                    
+        "text": {
+          "metadata_field": false,
+          "searchable": true,
+          "aggregatable": false
+        }
+      }
+    }
+  }

specification/_global/field_caps/FieldCapabilitiesResponse.ts

@@ -0,0 +1,36 @@
+summary: Get unmapped fields
+# type: "response"
+description: >
+  A successful response from `GET _field_caps?fields=rating,title&include_unmapped`.
+  The response contains an entry for each field that is present in some indices but not all.
+  For example, the `rating` and `title` fields are unmapped in `index5`.
+# response_code: 200,
+value: |-
+  {
+    "indices": [ "index1", "index2", "index3", "index4", "index5" ],
+    "fields": {
+      "rating": {                                   
+        "long": {
+          "metadata_field": false,
+          "searchable": true,
+          "aggregatable": false,
+          "indices": [ "index1", "index2" ],
+          "non_aggregatable_indices": [ "index1" ]  
+        },
+        "keyword": {
+          "metadata_field": false,
+          "searchable": false,
+          "aggregatable": true,
+          "indices": [ "index3", "index4" ],
+          "non_searchable_indices": [ "index4" ]    
+        }
+      },
+      "title": {                                    
+        "text": {
+          "metadata_field": false,
+          "searchable": true,
+          "aggregatable": false
+        }
+      }
+    }
+  }

specification/_global/field_caps/examples/request/FieldCapabilitiesRequestExample1.yaml

@@ -37,58 +37,68 @@ import { Query } from './_types/Knn'
  *
  * The kNN search API supports restricting the search using a filter.
  * The search will return the top k documents that also match the filter query.
+ *
+ * A kNN search response has the exact same structure as a search API response.
+ * However, certain sections have a meaning specific to kNN search:
+ *
+ * * The document `_score` is determined by the similarity between the query and document vector.
+ * * The `hits.total` object contains the total number of nearest neighbor candidates considered, which is `num_candidates * num_shards`. The `hits.total.relation` will always be `eq`, indicating an exact value.
  * @rest_spec_name knn_search
  * @availability stack since=8.0.0 stability=experimental
  * @deprecated 8.4.0 The kNN search API has been replaced by the `knn` option in the search API.
  * @doc_tag search
+ * @doc_id search-knn
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
      * A comma-separated list of index names to search;
-     * use `_all` or to perform the operation on all indices
+     * use `_all` or to perform the operation on all indices.
      */
     index: Indices
   }
   query_parameters: {
     /**
-     * A comma-separated list of specific routing values
+     * A comma-separated list of specific routing values.
      */
     routing?: Routing
   }
   body: {
     /**
      * Indicates which source fields are returned for matching documents. These
-     * fields are returned in the hits._source property of the search response.
+     * fields are returned in the `hits._source` property of the search response.
+     * @server_default true
      */
     _source?: SourceConfig
     /**
      * The request returns doc values for field names matching these patterns
-     * in the hits.fields property of the response. Accepts wildcard (*) patterns.
+     * in the `hits.fields` property of the response.
+     * It accepts wildcard (`*`) patterns.
      */
     docvalue_fields?: FieldAndFormat[]
     /**
-     * List of stored fields to return as part of a hit. If no fields are specified,
-     * no stored fields are included in the response. If this field is specified, the _source
-     * parameter defaults to false. You can pass _source: true to return both source fields
+     * A list of stored fields to return as part of a hit. If no fields are specified,
+     * no stored fields are included in the response. If this field is specified, the `_source`
+     * parameter defaults to `false`. You can pass `_source: true` to return both source fields
      * and stored fields in the search response.
      */
     stored_fields?: Fields
     /**
      * The request returns values for field names matching these patterns
-     * in the hits.fields property of the response. Accepts wildcard (*) patterns.
+     * in the `hits.fields` property of the response.
+     * It accepts wildcard (`*`) patterns.
      */
     fields?: Fields
     /**
-     * Query to filter the documents that can match. The kNN search will return the top
+     * A query to filter the documents that can match. The kNN search will return the top
      * `k` documents that also match this filter. The value can be a single query or a
      * list of queries. If `filter` isn't provided, all documents are allowed to match.
      * @availability stack since=8.2.0
      * @availability serverless
      */
     filter?: QueryContainer | QueryContainer[]
     /**
-     * kNN query to execute
+     * The kNN query to run.
      * @ext_doc_id query-dsl-knn-query
      */
     knn: Query

specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample1.yaml

@@ -25,28 +25,28 @@ import { ShardStatistics } from '@_types/Stats'
 
 export class Response<TDocument> {
   body: {
-    /** Milliseconds it took Elasticsearch to execute the request. */
+    /** The milliseconds it took Elasticsearch to run the request. */
     took: long
     /**
      * If true, the request timed out before completion;
      * returned results may be partial or empty.
      */
     timed_out: boolean
     /**
-     * Contains a count of shards used for the request.
+     * A count of shards used for the request.
      */
     _shards: ShardStatistics
     /**
-     * Contains returned documents and metadata.
+     * The returned documents and metadata.
      */
     hits: HitsMetadata<TDocument>
     /**
-     * Contains field values for the documents. These fields
+     * The field values for the documents. These fields
      * must be specified in the request using the `fields` parameter.
      */
     fields?: Dictionary<string, UserDefinedValue>
     /**
-     * Highest returned document score. This value is null for requests
+     * The highest returned document score. This value is null for requests
      * that do not sort by score.
      */
     max_score?: double

specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample2.yaml

@@ -28,11 +28,24 @@ import { Operation } from './types'
  * Get multiple JSON documents by ID from one or more indices.
  * If you specify an index in the request URI, you only need to specify the document IDs in the request body.
  * To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.
+ *
+ * **Filter source fields**
+ *
+ * By default, the `_source` field is returned for every document (if stored).
+ * Use the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.
+ * You can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.
+ *
+ * **Get stored fields**
+ *
+ * Use the `stored_fields` attribute to specify the set of stored fields you want to retrieve.
+ * Any requested fields that are not stored are ignored.
+ * You can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.
  * @rest_spec_name mget
  * @availability stack since=1.3.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @index_privileges read
  * @doc_tag document
+ * @doc_id docs-multi-get
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/_global/knn_search/KnnSearchRequest.ts

@@ -21,6 +21,11 @@ import { ResponseItem } from './types'
 
 export class Response<TDocument> {
   body: {
+    /**
+     * The response includes a docs array that contains the documents in the order specified in the request.
+     * The structure of the returned documents is similar to that returned by the get API.
+     * If there is a failure getting a particular document, the error is included in place of the document.
+     */
     docs: ResponseItem<TDocument>[]
   }
 }

specification/_global/knn_search/KnnSearchResponse.ts

@@ -0,0 +1,17 @@
+summary: Get documents by ID
+# method_request: "GET /my-index-000001/_mget"
+description: >
+  Run `GET /my-index-000001/_mget`.
+  When you specify an index in the request URI, only the document IDs are required in the request body.
+# type: "request"
+value: |-
+  {
+    "docs": [
+      {
+        "_id": "1"
+      },
+      {
+        "_id": "2"
+      }
+    ]
+  }

specification/_global/mget/MultiGetRequest.ts

@@ -0,0 +1,31 @@
+summary: Filter source fields
+# method_request: "GET /_mget"
+description: >
+  Run `GET /_mget`.
+  This request sets `_source` to `false` for document 1 to exclude the source entirely.
+  It retrieves `field3` and `field4` from document 2.
+  It retrieves the `user` field from document 3 but filters out the `user.location` field.
+# type: "request"
+value: |-
+  {
+    "docs": [
+      {
+        "_index": "test",
+        "_id": "1",
+        "_source": false
+      },
+      {
+        "_index": "test",
+        "_id": "2",
+        "_source": [ "field3", "field4" ]
+      },
+      {
+        "_index": "test",
+        "_id": "3",
+        "_source": {
+          "include": [ "user" ],
+          "exclude": [ "user.location" ]
+        }
+      }
+    ]
+  }