[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