[Backport 8.x] [DOCS] Add examples and descriptions for explain, termvector, search APIs

specification/_doc_ids/table.csv

@@ -596,6 +596,7 @@ search-request-body,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 search-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-search.html
 search-shards,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-shards.html
 search-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html
+search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template-api.html
 search-terms-enum,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-terms-enum.html
 search-validate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-validate.html
 search-vector-tile-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-vector-tile-api.html

specification/_global/explain/ExplainRequest.ts

@@ -25,11 +25,14 @@ import { Operator } from '@_types/query_dsl/Operator'
 
 /**
  * Explain a document match result.
- * Returns information about why a specific document matches, or doesn’t match, a query.
+ * Get information about why a specific document matches, or doesn't match, a query.
+ * It computes a score explanation for a query and a specific document.
  * @rest_spec_name explain
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @index_privileges read
  * @doc_tag search
+ * @doc_id search-explain
  */
 export interface Request extends RequestBase {
   urls: [
@@ -40,67 +43,76 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Defines the document ID.
+     * The document identifier.
      */
     id: Id
     /**
-     * Index names used to limit the request.
+     * Index names that are used to limit the request.
      * Only a single index name can be provided to this parameter.
      */
     index: IndexName
   }
   query_parameters: {
     /**
-     * Analyzer to use for the query string.
-     * This parameter can only be used when the `q` query string parameter is specified.
+     * The analyzer to use for the query string.
+     * This parameter can be used only when the `q` query string parameter is specified.
      */
     analyzer?: string
     /**
      * If `true`, wildcard and prefix queries are analyzed.
+     * This parameter can be used only when the `q` query string parameter is specified.
      * @server_default false
      */
     analyze_wildcard?: boolean
     /**
      * The default operator for query string query: `AND` or `OR`.
+     * This parameter can be used only when the `q` query string parameter is specified.
      * @server_default OR
      */
     default_operator?: Operator
     /**
-     * Field to use as default where no field prefix is given in the query string.
+     * The field to use as default where no field prefix is given in the query string.
+     * This parameter can be used only when the `q` query string parameter is specified.
      */
     df?: string
     /**
      * If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
+     * This parameter can be used only when the `q` query string parameter is specified.
      * @server_default false
      */
     lenient?: 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.
+     * It is random by default.
      */
     preference?: string
     /**
-     * Custom value used to route operations to a specific shard.
+     * A custom value used to route operations to a specific shard.
      */
     routing?: Routing
     /**
-     * True or false to return the `_source` field or not, or a list of fields to return.
+     * `True` or `false` to return the `_source` field or not or a list of fields to return.
      */
     _source?: SourceConfigParam
     /**
      * A comma-separated list of source fields to exclude from the response.
+     * You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.
+     * If the `_source` parameter is `false`, this parameter is ignored.
      */
     _source_excludes?: Fields
     /**
      * A comma-separated list of source fields to include in the response.
+     * If this parameter is specified, only these source fields are returned.
+     * You can exclude fields from this subset using the `_source_excludes` query parameter.
+     * If the `_source` parameter is `false`, this parameter is ignored.
      */
     _source_includes?: Fields
     /**
      * A comma-separated list of stored fields to return in the response.
      */
     stored_fields?: Fields
     /**
-     * Query in the Lucene query string syntax.
+     * The query in the Lucene query string syntax.
      */
     q?: string
   }

specification/_global/explain/examples/request/ExplainRequestExample1.yaml

@@ -0,0 +1,12 @@
+# summary:
+# method_request: GET /my-index-000001/_explain/0
+description: >
+  Run `GET /my-index-000001/_explain/0` with the request body.
+  Alternatively, run `GET /my-index-000001/_explain/0?q=message:elasticsearch`
+# type: request
+value: |-
+  {
+    "query" : {
+      "match" : { "message" : "elasticsearch" }
+    }
+  }

specification/_global/explain/examples/response/ExplainResponseExample1.yaml

@@ -0,0 +1,74 @@
+# summary:
+description: A successful response from `GET /my-index-000001/_explain/0`.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "_index":"my-index-000001",
+    "_id":"0",
+    "matched":true,
+    "explanation":{
+        "value":1.6943598,
+        "description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
+        "details":[
+          {
+              "value":1.6943598,
+              "description":"score(freq=1.0), computed as boost * idf * tf from:",
+              "details":[
+                {
+                    "value":2.2,
+                    "description":"boost",
+                    "details":[]
+                },
+                {
+                    "value":1.3862944,
+                    "description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
+                    "details":[
+                      {
+                          "value":1,
+                          "description":"n, number of documents containing term",
+                          "details":[]
+                      },
+                      {
+                          "value":5,
+                          "description":"N, total number of documents with field",
+                          "details":[]
+                      }
+                    ]
+                },
+                {
+                    "value":0.5555556,
+                    "description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
+                    "details":[
+                      {
+                          "value":1.0,
+                          "description":"freq, occurrences of term within document",
+                          "details":[]
+                      },
+                      {
+                          "value":1.2,
+                          "description":"k1, term saturation parameter",
+                          "details":[]
+                      },
+                      {
+                          "value":0.75,
+                          "description":"b, length normalization parameter",
+                          "details":[]
+                      },
+                      {
+                          "value":3.0,
+                          "description":"dl, length of field",
+                          "details":[]
+                      },
+                      {
+                          "value":5.4,
+                          "description":"avgdl, average length of field",
+                          "details":[]
+                      }
+                    ]
+                }
+              ]
+          }
+        ]
+    }
+  }

specification/_global/mtermvectors/MultiTermVectorsRequest.ts

@@ -31,14 +31,17 @@ import { Operation } from './types'
 /**
  * Get multiple term vectors.
  *
+ * Get multiple term vectors with a single request.
  * You can specify existing documents by index and ID or provide artificial documents in the body of the request.
  * You can specify the index in the request body or request URI.
  * The response contains a `docs` array with all the fetched termvectors.
  * Each element has the structure provided by the termvectors API.
  * @rest_spec_name mtermvectors
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @index_privileges read
  * @doc_tag document
+ * @doc_id docs-multi-termvectors
  */
 export interface Request extends RequestBase {
   urls: [
@@ -53,15 +56,15 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Name of the index that contains the documents.
+     * The name of the index that contains the documents.
      */
     index?: IndexName
   }
   query_parameters: {
     ids?: Id[]
     /**
-     * Comma-separated list or wildcard expressions of fields to include in the statistics.
-     * Used as the default list unless a specific field list is provided in the `completion_fields` or `fielddata_fields` parameters.
+     * A comma-separated list or wildcard expressions of fields to include in the statistics.
+     * It is used as the default list unless a specific field list is provided in the `completion_fields` or `fielddata_fields` parameters.
      */
     fields?: Fields
     /**
@@ -85,8 +88,8 @@ export interface Request extends RequestBase {
      */
     positions?: 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.
+     * It is random by default.
      */
     preference?: string
     /**
@@ -96,7 +99,7 @@ export interface Request extends RequestBase {
      */
     realtime?: boolean
     /**
-     * Custom value used to route operations to a specific shard.
+     * A custom value used to route operations to a specific shard.
      */
     routing?: Routing
     /**
@@ -109,17 +112,17 @@ export interface Request extends RequestBase {
      */
     version?: VersionNumber
     /**
-     * Specific version type.
+     * The version type.
      */
     version_type?: VersionType
   }
   body: {
     /**
-     * Array of existing or artificial documents.
+     * An array of existing or artificial documents.
      */
     docs?: Operation[]
     /**
-     * Simplified syntax to specify documents by their ID if they're in the same index.
+     * A simplified syntax to specify documents by their ID if they're in the same index.
      */
     ids?: Id[]
   }

specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample1.yaml

@@ -0,0 +1,21 @@
+summary: Get multi term vectors
+# method_request: POST /my-index-000001/_mtermvectors
+description: >
+  Run `POST /my-index-000001/_mtermvectors`.
+  If you specify an index in the request URI, the index does not need to be specified for each documents in the request body.
+# type: request
+value: |-
+  {
+    "docs": [
+        {
+          "_id": "2",
+          "fields": [
+              "message"
+          ],
+          "term_statistics": true
+        },
+        {
+          "_id": "1"
+        }
+    ]
+  }

specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample2.yaml

@@ -0,0 +1,16 @@
+summary: Simplified syntax
+# method_request: POST /my-index-000001/_mtermvectors
+description: >
+  Run `POST /my-index-000001/_mtermvectors`.
+  If all requested documents are in same index and the parameters are the same, you can use a simplified syntax.
+# type: request
+value: |-
+  {
+    "ids": [ "1", "2" ],
+    "parameters": {
+      "fields": [
+        "message"
+      ],
+      "term_statistics": true
+    }
+  }

specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample3.yaml

@@ -0,0 +1,23 @@
+summary: Artificial documents
+# method_request: POST /_mtermvectors
+description: >
+  Run `POST /_mtermvectors` to generate term vectors for artificial documents provided in the body of the request.
+  The mapping used is determined by the specified `_index`.
+# type: request
+value: |-
+  {
+    "docs": [
+        {
+          "_index": "my-index-000001",
+          "doc" : {
+              "message" : "test test test"
+          }
+        },
+        {
+          "_index": "my-index-000001",
+          "doc" : {
+            "message" : "Another test ..."
+          }
+        }
+    ]
+  }

specification/_global/render_search_template/RenderSearchTemplateRequest.ts

@@ -29,7 +29,9 @@ import { Id } from '@_types/common'
  * @rest_spec_name render_search_template
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @index_privileges read
  * @doc_tag search
+ * @doc_id render-search-template-api
  */
 export interface Request extends RequestBase {
   urls: [
@@ -44,12 +46,18 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * ID of the search template to render.
+     * The ID of the search template to render.
      * If no `source` is specified, this or the `id` request body parameter is required.
      */
     id?: Id
   }
   body: {
+    /**
+     * The ID of the search template to render.
+     * If no `source` is specified, this or the `<template-id>` request path parameter is required.
+     * If you specify both this parameter and the `<template-id>` parameter, the API uses only `<template-id>`.
+     */
+    id?: Id
     file?: string
     /**
      * Key-value pairs used to replace Mustache variables in the template.
@@ -59,7 +67,7 @@ export interface Request extends RequestBase {
     params?: Dictionary<string, UserDefinedValue>
     /**
      * An inline search template.
-     * Supports the same parameters as the search API's request body.
+     * It supports the same parameters as the search API's request body.
      * These parameters also support Mustache variables.
      * If no `id` or `<templated-id>` is specified, this parameter is required.
      */