[DOCS] Add examples for mget, msearch template

Author: lcawl

specification/_doc_ids/table.csv

@@ -600,8 +600,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

specification/_global/knn_search/KnnSearchRequest.ts

@@ -37,10 +37,17 @@ 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 {
   urls: [
@@ -52,49 +59,52 @@ 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.
+     * @default_server 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/knn_search/KnnSearchResponse.ts

@@ -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/mget/MultiGetRequest.ts

@@ -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
+ * @eoc_id docs-multi-get
  */
 export interface Request extends RequestBase {
   urls: [

specification/_global/mget/MultiGetResponse.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/mget/examples/request/MultiGetRequestExample1.yaml

@@ -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/examples/request/MultiGetRequestExample2.yaml

@@ -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" ]
+        }
+      }
+    ]
+  }

specification/_global/mget/examples/request/MultiGetRequestExample3.yaml

@@ -0,0 +1,21 @@
+summary: Get stored fields
+# method_request: "GET /_mget"
+description: >
+  Run `GET /_mget`.
+  This request retrieves `field1` and `field2` from document 1 and `field3` and `field4` from document 2.
+# type: "request"
+value: |-
+  {
+    "docs": [
+      {
+        "_index": "test",
+        "_id": "1",
+        "stored_fields": [ "field1", "field2" ]
+      },
+      {
+        "_index": "test",
+        "_id": "2",
+        "stored_fields": [ "field3", "field4" ]
+      }
+    ]
+  }

specification/_global/mget/examples/request/MultiGetRequestExample4.yaml

@@ -0,0 +1,22 @@
+summary: Document routing
+# method_request: "GET /_mget?routing=key1"
+description: >
+  Run `GET /_mget?routing=key1`.
+  If routing is used during indexing, you need to specify the routing value to retrieve documents.
+  This request fetches `test/_doc/2` from the shard corresponding to routing key `key1`.
+  It fetches `test/_doc/1` from the shard corresponding to routing key `key2`.
+# type: "request"
+value: |-
+  {
+    "docs": [
+      {
+        "_index": "test",
+        "_id": "1",
+        "routing": "key2"
+      },
+      {
+        "_index": "test",
+        "_id": "2"
+      }
+    ]
+  }

specification/_global/mget/examples/response/PutAutoscalingPolicyResponseExample1.yaml

@@ -0,0 +1,5 @@
+summary: 'A successful response when creating an autoscaling policy.'
+# description: "",
+# type: "response",
+# response_code: 200,
+value: "{\n  \"acknowledged\": true\n}"

specification/_global/msearch_template/MultiSearchTemplateRequest.ts

@@ -24,11 +24,26 @@ import { RequestItem } from './types'
 
 /**
  * Run multiple templated searches.
+ *
+ * Run multiple templated searches with a single request.
+ * If you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.
+ * For example:
+ *
+ * ```
+ * $ cat requests
+ * { "index": "my-index" }
+ * { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
+ * { "index": "my-other-index" }
+ * { "id": "my-other-search-template", "params": { "query_type": "match_all" }}
+ *
+ * $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo
+ * ```
  * @rest_spec_name msearch_template
  * @availability stack since=5.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @index_privileges read
  * @doc_tag search
+ * @doc_id search-multi-search-template
  * @ext_doc_id search-templates
  */
 export interface Request extends RequestBase {
@@ -44,8 +59,8 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Comma-separated list of data streams, indices, and aliases to search.
-     * Supports wildcards (`*`).
+     * A comma-separated list of data streams, indices, and aliases to search.
+     * It supports wildcards (`*`).
      * To search all data streams and indices, omit this parameter or use `*`.
      */
     index?: Indices
@@ -57,12 +72,11 @@ export interface Request extends RequestBase {
      */
     ccs_minimize_roundtrips?: boolean
     /**
-     * Maximum number of concurrent searches the API can run.
+     * The maximum number of concurrent searches the API can run.
      */
     max_concurrent_searches?: long
     /**
      * The type of the search operation.
-     * Available options: `query_then_fetch`, `dfs_query_then_fetch`.
      */
     search_type?: SearchType
     /**
@@ -77,6 +91,25 @@ export interface Request extends RequestBase {
      */
     typed_keys?: boolean
   }
-  /** @codegen_name search_templates */
+  /**
+   * @codegen_name search_templates
+   * The request body must be newline-delimited JSON (NDJSON) in the following format:
+   *
+   * ```
+   * <header>\n
+   * <body>\n
+   * <header>\n
+   * <body>\n
+   * ```
+   *
+   * Each `<header>` and `<body>` pair represents a search request.
+   * The `<header>` supports the same parameters as the multi search API's `<header>`.
+   * The `<body>` supports the same parameters as the search template API's request body.
+   *
+   * The `<header>` contains the parameters used to limit or change the search.
+   * It is required for each search body but can be empty `({})` or a blank line.
+   *
+   * The `<body>` contains the parameters for the search.
+   */
   body: Array<RequestItem>
 }

specification/_global/msearch_template/MultiSearchTemplateResponse.ts

@@ -20,5 +20,12 @@
 import { MultiSearchResult } from '@global/msearch/types'
 
 export class Response<TDocument> {
+  /**
+   * The API returns a 400 status code only if the request itself fails.
+   * If one or more searches in the request fail, the API returns a 200 status code with an error object for each failed search in the response.
+   *
+   * The body contains results for each search, returned in the order submitted.
+   * Each object uses the same properties as the search API's response.
+   */
   body: MultiSearchResult<TDocument>
 }

specification/_global/msearch_template/examples/request/MultiSearchTemplateRequestExample1.yaml

@@ -0,0 +1,9 @@
+# summary:
+# method_request: GET my-index/_msearch/template
+description: Run `GET my-index/_msearch/template` to run multiple templated searches.
+# type: "request"
+value: |-
+  { }
+  { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
+  { }
+  { "id": "my-other-search-template", "params": { "query_type": "match_all" }}

specification/_global/msearch_template/types.ts

@@ -31,7 +31,7 @@ export class TemplateConfig {
    * @server_default false */
   explain?: boolean
   /**
-   * ID of the search template to use. If no source is specified,
+   * The ID of the search template to use. If no `source` is specified,
    * this parameter is required.
    */
   id?: Id
@@ -47,7 +47,7 @@ export class TemplateConfig {
   profile?: boolean
   /**
    * An inline search template. Supports the same parameters as the search API's
-   * request body. Also supports Mustache variables. If no id is specified, this
+   * request body. It also supports Mustache variables. If no `id` is specified, this
    * parameter is required.
    */
   source?: string