[OpenAPI] Edit search API summaries (#3080)

lcawl · leemthompo · web-flow · commit 5def4b4b401f · 2024-11-05T16:49:24.000Z
Co-authored-by: Liam Thompson &lt;32779855+leemthompo@users.noreply.github.com&gt;
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
diff --git a/output/schema/schema.json b/output/schema/schema.json
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
@@ -534,6 +534,7 @@ search-validate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}
 search-vector-tile-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-vector-tile-api.html
 searchable-snapshots-api-mount-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-mount-snapshot.html
 searchable-snapshots-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-apis.html
+search-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html
 secure-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/secure-settings.html
 security-api-authenticate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-authenticate.html
 security-api-change-password,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-change-password.html
diff --git a/specification/_global/clear_scroll/ClearScrollRequest.ts b/specification/_global/clear_scroll/ClearScrollRequest.ts
@@ -21,7 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { ScrollIds } from '@_types/common'
 
 /**
- * Clears the search context and results for a scrolling search.
+ * Clear a scrolling search.
+ *
+ * Clear the search context and results for a scrolling search.
  * @rest_spec_name clear_scroll
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/_global/close_point_in_time/ClosePointInTimeRequest.ts b/specification/_global/close_point_in_time/ClosePointInTimeRequest.ts
@@ -21,7 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Closes a point-in-time.
+ * Close a point in time.
+ *
+ * A point in time must be opened explicitly before being used in search requests.
+ * The `keep_alive` parameter tells Elasticsearch how long it should persist.
+ * A point in time is automatically closed when the `keep_alive` period has elapsed.
+ * However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.
  * @rest_spec_name close_point_in_time
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/_global/field_caps/FieldCapabilitiesRequest.ts b/specification/_global/field_caps/FieldCapabilitiesRequest.ts
@@ -23,9 +23,13 @@ import { RuntimeFields } from '@_types/mapping/RuntimeFields'
 import { QueryContainer } from '@_types/query_dsl/abstractions'
 
 /**
- * The field capabilities API returns the information about the capabilities of fields among multiple indices.
- * The field capabilities API returns runtime fields like any other field. For example, a runtime field with a type
- * of keyword is returned as any other field that belongs to the `keyword` family.
+ * Get the field capabilities.
+ *
+ * Get information about the capabilities of fields among multiple indices.
+ *
+ * For data streams, the API returns field capabilities among the stream’s backing indices.
+ * It returns runtime fields like any other field.
+ * For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the `keyword` family.
  * @rest_spec_name field_caps
  * @availability stack since=5.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/_global/knn_search/KnnSearchRequest.ts b/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
diff --git a/specification/_global/msearch_template/MultiSearchTemplateRequest.ts b/specification/_global/msearch_template/MultiSearchTemplateRequest.ts
@@ -23,12 +23,13 @@ import { long } from '@_types/Numeric'
 import { RequestItem } from './types'
 
 /**
- * Runs multiple templated searches with a single request.
+ * Run multiple templated searches.
  * @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
+ * @ext_doc_id search-templates
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/_global/open_point_in_time/OpenPointInTimeRequest.ts b/specification/_global/open_point_in_time/OpenPointInTimeRequest.ts
@@ -23,12 +23,17 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
 import { Duration } from '@_types/Time'
 
 /**
- * A search request by default executes against the most recent visible data of the target indices,
+ * Open a point in time.
+ *
+ * A search request by default runs against the most recent visible data of the target indices,
  * which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the
  * state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
  * search requests using the same point in time. For example, if refreshes happen between
  * `search_after` requests, then the results of those requests might not be consistent as changes happening
  * between searches are only visible to the more recent point in time.
+ *
+ * A point in time must be opened explicitly before being used in search requests.
+ * The `keep_alive` parameter tells Elasticsearch how long it should persist.
  * @rest_spec_name open_point_in_time
  * @availability stack since=7.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/_global/rank_eval/RankEvalRequest.ts b/specification/_global/rank_eval/RankEvalRequest.ts
@@ -22,7 +22,9 @@ import { ExpandWildcards, Indices } from '@_types/common'
 import { RankEvalMetric, RankEvalRequestItem } from './types'
 
 /**
- * Enables you to evaluate the quality of ranked search results over a set of typical search queries.
+ * Evaluate ranked search results.
+ *
+ * Evaluate the quality of ranked search results over a set of typical search queries.
  * @rest_spec_name rank_eval
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/_global/render_search_template/RenderSearchTemplateRequest.ts b/specification/_global/render_search_template/RenderSearchTemplateRequest.ts
@@ -23,7 +23,9 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Renders a search template as a search request body.
+ * Render a search template.
+ *
+ * Render a search template as a search request body.
  * @rest_spec_name render_search_template
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/_global/search/SearchRequest.ts b/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
diff --git a/specification/_global/search_mvt/SearchMvtRequest.ts b/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
diff --git a/specification/_global/search_shards/SearchShardsRequest.ts b/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
diff --git a/specification/_global/search_template/SearchTemplateRequest.ts b/specification/_global/search_template/SearchTemplateRequest.ts
@@ -30,11 +30,12 @@ import {
 import { Duration } from '@_types/Time'
 
 /**
- * Runs a search with a search template.
+ * Run a search with a search template.
  * @rest_spec_name search_template
  * @availability stack since=2.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_tag search
+ * @ext_doc_id search-template
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/_global/termvectors/TermVectorsRequest.ts b/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
diff --git a/specification/async_search/delete/AsyncSearchDeleteRequest.ts b/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.
diff --git a/specification/async_search/get/AsyncSearchGetRequest.ts b/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
diff --git a/specification/async_search/status/AsyncSearchStatusRequest.ts b/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
diff --git a/specification/async_search/submit/AsyncSearchSubmitRequest.ts b/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.
