[OpenAPI] More search summary edits

Author: lcawl

specification/_global/knn_search/KnnSearchRequest.ts

@@ -24,6 +24,19 @@ import { FieldAndFormat, QueryContainer } from '@_types/query_dsl/abstractions'
 import { Query } from './_types/Knn'
 
 /**
+ * Run a knn search.
+ * 
+ * NOTE: The kNN search API has been replaced by the `knn` option in the search API.
+ *
+ * Perform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.
+ * Given a query vector, the API finds the k closest vectors and returns those documents as search hits.
+ *
+ * Elasticsearch uses the HNSW algorithm to support efficient kNN search.
+ * Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.
+ * This means the results returned are not always the true k closest neighbors.
+ *
+ * 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.
  * @rest_spec_name knn_search
  * @availability stack since=8.0.0 stability=experimental
  * @deprecated 8.4.0

specification/_global/search/SearchRequest.ts

@@ -52,7 +52,9 @@ import { SourceConfig, SourceConfigParam } from './_types/SourceFilter'
 import { Suggester } from './_types/suggester'
 
 /**
- * Returns search hits that match the query defined in the request.
+ * Run a search.
+ *
+ * Get search hits that match the query defined in the request.
  * You can provide search queries using the `q` query string parameter or the request body.
  * If both are specified, only the query parameter is used.
  * @rest_spec_name search

specification/_global/search_mvt/SearchMvtRequest.ts

@@ -32,7 +32,8 @@ import { ZoomLevel } from './_types/ZoomLevel'
 
 /**
  * Search a vector tile.
- * Searches a vector tile for geospatial values.
+ *
+ * Search a vector tile for geospatial values.
  * @rest_spec_name search_mvt
  * @availability stack since=7.15.0 stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/search_shards/SearchShardsRequest.ts

@@ -21,6 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { ExpandWildcards, Indices, Routing } from '@_types/common'
 
 /**
+ * Get the search shards.
+ * 
+ * Get the indices and shards that a search request would be run against.
+ * This information can be useful for working out issues or planning optimizations with routing and shard preferences.
+ * When filtered aliases are used, the filter is returned as part of the indices section.
  * @rest_spec_name search_shards
  * @availability stack stability=stable
  * @doc_tag search

specification/_global/termvectors/TermVectorsRequest.ts

@@ -32,7 +32,8 @@ import { Filter } from './types'
 
 /**
  * Get term vector information.
- * Returns information and statistics about terms in the fields of a particular document.
+ *
+ * Get information and statistics about terms in the fields of a particular document.
  * @rest_spec_name termvectors
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public

specification/async_search/delete/AsyncSearchDeleteRequest.ts

@@ -22,6 +22,7 @@ import { Id } from '@_types/common'
 
 /**
  * Delete an async search.
+ *
  * If the asynchronous search is still running, it is cancelled.
  * Otherwise, the saved search results are deleted.
  * If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the `cancel_task` cluster privilege.

specification/async_search/get/AsyncSearchGetRequest.ts

@@ -23,6 +23,7 @@ import { Duration } from '@_types/Time'
 
 /**
  * Get async search results.
+ *
  * Retrieve the results of a previously submitted asynchronous search request.
  * If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
  * @rest_spec_name async_search.get

specification/async_search/status/AsyncSearchStatusRequest.ts

@@ -21,8 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Get async search status.
- * Retrieve the status of a previously submitted async search request given its identifier, without retrieving search results.
+ * Get the async search status.
+ *
+ * Get the status of a previously submitted async search request given its identifier, without retrieving search results.
  * If the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.
  * @rest_spec_name async_search.status
  * @availability stack since=7.11.0 stability=stable

specification/async_search/submit/AsyncSearchSubmitRequest.ts

@@ -54,6 +54,7 @@ import { Duration } from '@_types/Time'
 
 /**
  * Run an async search.
+ *
  * When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.
  *
  * Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.