Add more search edits

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
@@ -512,6 +513,7 @@ routing,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-ge
 run-as-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html
 runtime-search-request,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html
 script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.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

output/openapi/elasticsearch-serverless-openapi.json

@@ -35,6 +35,7 @@ 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 {
   urls: [
@@ -49,7 +50,7 @@ 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
   }
@@ -62,12 +63,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
     /**
@@ -81,11 +82,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
      */
@@ -100,17 +105,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

@@ -31,14 +31,22 @@ 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.
+ *
+ * **Artificial documents**
+ *
+ * You can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.
+ * The mapping used is determined by the specified `_index`.
  * @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 +61,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 +93,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
     /**
@@ -109,7 +117,7 @@ export interface Request extends RequestBase {
      */
     version?: VersionNumber
     /**
-     * Specific version type.
+     * The version type.
      */
     version_type?: VersionType
   }

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

@@ -0,0 +1,21 @@
+summary: Get multiple term vectors
+# method_request: "POST /my-index-000001/_mtermvectors"
+description: >
+  Run `POST /my-index-000001/_mtermvectors`.
+  When 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/field_caps/examples/response/FieldCapabilitiesResponseExample2.yaml

@@ -0,0 +1,23 @@
+summary: Artificial documents
+# method_request: "POST /_mtermvectors"
+description: >
+  Run `POST /_mtermvectors` to generate term vectors for artificial documents.
+  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/mget/examples/response/PutAutoscalingPolicyResponseExample1.yaml

@@ -44,7 +44,8 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.
+     * A  comma-separated list of data streams, indices, and index aliases used to limit the request.
+     * Wildcard (`*`) expressions are supported.
      * To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.
      */
     index?: Indices

specification/_global/mtermvectors/MultiTermVectorsRequest.ts

@@ -39,7 +39,9 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name scroll
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @index_privileges read
  * @doc_tag search
+ * @doc_id scroll-api
  * @ext_doc_id scroll-search-results
  */
 export interface Request extends RequestBase {
@@ -60,7 +62,7 @@ export interface Request extends RequestBase {
   }
   query_parameters: {
     /**
-     * Period to retain the search context for scrolling.
+     * The period to retain the search context for scrolling.
      * @doc_id scroll-search-results
      * @server_default 1d
      */
@@ -75,12 +77,12 @@ export interface Request extends RequestBase {
   }
   body: {
     /**
-     * Period to retain the search context for scrolling.
+     * The period to retain the search context for scrolling.
      * @doc_id scroll-search-results
      * @server_default 1d
      */
     scroll?: Duration
-    /** Scroll ID of the search. */
+    /** The scroll ID of the search. */
     scroll_id: ScrollId
   }
 }

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

@@ -0,0 +1,8 @@
+#
+# method_request: "GET /_search/scroll"
+description: Run `GET /_search/scroll` to get the next batch of results for a scrolling search.
+# type: "request"
+value: |-
+  {
+    "scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
+  }

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

@@ -75,6 +75,7 @@ import { Suggester } from './_types/suggester'
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
  * @index_privileges read
+ * @doc_id search-search
  * @ext_doc_id ccs-privileges
  */
 export interface Request extends RequestBase {