Skip to content

Commit 5def4b4

Browse files
lcawlleemthompo
andauthored
[OpenAPI] Edit search API summaries (#3080)
Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
1 parent 8dcb736 commit 5def4b4

File tree

21 files changed

+291
-162
lines changed

21 files changed

+291
-162
lines changed

output/openapi/elasticsearch-openapi.json

Lines changed: 92 additions & 51 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

output/openapi/elasticsearch-serverless-openapi.json

Lines changed: 80 additions & 45 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

output/schema/schema.json

Lines changed: 55 additions & 51 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

specification/_doc_ids/table.csv

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -534,6 +534,7 @@ search-validate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}
534534
search-vector-tile-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-vector-tile-api.html
535535
searchable-snapshots-api-mount-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-api-mount-snapshot.html
536536
searchable-snapshots-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-apis.html
537+
search-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html
537538
secure-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/secure-settings.html
538539
security-api-authenticate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-authenticate.html
539540
security-api-change-password,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-change-password.html

specification/_global/clear_scroll/ClearScrollRequest.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ import { RequestBase } from '@_types/Base'
2121
import { ScrollIds } from '@_types/common'
2222

2323
/**
24-
* Clears the search context and results for a scrolling search.
24+
* Clear a scrolling search.
25+
*
26+
* Clear the search context and results for a scrolling search.
2527
* @rest_spec_name clear_scroll
2628
* @availability stack stability=stable
2729
* @availability serverless stability=stable visibility=public

specification/_global/close_point_in_time/ClosePointInTimeRequest.ts

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,12 @@ import { RequestBase } from '@_types/Base'
2121
import { Id } from '@_types/common'
2222

2323
/**
24-
* Closes a point-in-time.
24+
* Close a point in time.
25+
*
26+
* A point in time must be opened explicitly before being used in search requests.
27+
* The `keep_alive` parameter tells Elasticsearch how long it should persist.
28+
* A point in time is automatically closed when the `keep_alive` period has elapsed.
29+
* However, keeping points in time has a cost; close them as soon as they are no longer required for search requests.
2530
* @rest_spec_name close_point_in_time
2631
* @availability stack since=7.10.0 stability=stable
2732
* @availability serverless stability=stable visibility=public

specification/_global/field_caps/FieldCapabilitiesRequest.ts

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,13 @@ import { RuntimeFields } from '@_types/mapping/RuntimeFields'
2323
import { QueryContainer } from '@_types/query_dsl/abstractions'
2424

2525
/**
26-
* The field capabilities API returns the information about the capabilities of fields among multiple indices.
27-
* The field capabilities API returns runtime fields like any other field. For example, a runtime field with a type
28-
* of keyword is returned as any other field that belongs to the `keyword` family.
26+
* Get the field capabilities.
27+
*
28+
* Get information about the capabilities of fields among multiple indices.
29+
*
30+
* For data streams, the API returns field capabilities among the stream’s backing indices.
31+
* It returns runtime fields like any other field.
32+
* For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the `keyword` family.
2933
* @rest_spec_name field_caps
3034
* @availability stack since=5.4.0 stability=stable
3135
* @availability serverless stability=stable visibility=public

specification/_global/knn_search/KnnSearchRequest.ts

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,19 @@ import { FieldAndFormat, QueryContainer } from '@_types/query_dsl/abstractions'
2424
import { Query } from './_types/Knn'
2525

2626
/**
27+
* Run a knn search.
28+
*
29+
* NOTE: The kNN search API has been replaced by the `knn` option in the search API.
30+
*
31+
* Perform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.
32+
* Given a query vector, the API finds the k closest vectors and returns those documents as search hits.
33+
*
34+
* Elasticsearch uses the HNSW algorithm to support efficient kNN search.
35+
* Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.
36+
* This means the results returned are not always the true k closest neighbors.
37+
*
38+
* The kNN search API supports restricting the search using a filter.
39+
* The search will return the top k documents that also match the filter query.
2740
* @rest_spec_name knn_search
2841
* @availability stack since=8.0.0 stability=experimental
2942
* @deprecated 8.4.0

specification/_global/msearch_template/MultiSearchTemplateRequest.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,13 @@ import { long } from '@_types/Numeric'
2323
import { RequestItem } from './types'
2424

2525
/**
26-
* Runs multiple templated searches with a single request.
26+
* Run multiple templated searches.
2727
* @rest_spec_name msearch_template
2828
* @availability stack since=5.0.0 stability=stable
2929
* @availability serverless stability=stable visibility=public
3030
* @index_privileges read
3131
* @doc_tag search
32+
* @ext_doc_id search-templates
3233
*/
3334
export interface Request extends RequestBase {
3435
path_parts: {

specification/_global/open_point_in_time/OpenPointInTimeRequest.ts

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,17 @@ import { QueryContainer } from '@_types/query_dsl/abstractions'
2323
import { Duration } from '@_types/Time'
2424

2525
/**
26-
* A search request by default executes against the most recent visible data of the target indices,
26+
* Open a point in time.
27+
*
28+
* A search request by default runs against the most recent visible data of the target indices,
2729
* which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the
2830
* state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
2931
* search requests using the same point in time. For example, if refreshes happen between
3032
* `search_after` requests, then the results of those requests might not be consistent as changes happening
3133
* between searches are only visible to the more recent point in time.
34+
*
35+
* A point in time must be opened explicitly before being used in search requests.
36+
* The `keep_alive` parameter tells Elasticsearch how long it should persist.
3237
* @rest_spec_name open_point_in_time
3338
* @availability stack since=7.10.0 stability=stable
3439
* @availability serverless stability=stable visibility=public

specification/_global/rank_eval/RankEvalRequest.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ import { ExpandWildcards, Indices } from '@_types/common'
2222
import { RankEvalMetric, RankEvalRequestItem } from './types'
2323

2424
/**
25-
* Enables you to evaluate the quality of ranked search results over a set of typical search queries.
25+
* Evaluate ranked search results.
26+
*
27+
* Evaluate the quality of ranked search results over a set of typical search queries.
2628
* @rest_spec_name rank_eval
2729
* @availability stack since=6.2.0 stability=stable
2830
* @availability serverless stability=stable visibility=public

specification/_global/render_search_template/RenderSearchTemplateRequest.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@ import { RequestBase } from '@_types/Base'
2323
import { Id } from '@_types/common'
2424

2525
/**
26-
* Renders a search template as a search request body.
26+
* Render a search template.
27+
*
28+
* Render a search template as a search request body.
2729
* @rest_spec_name render_search_template
2830
* @availability stack stability=stable
2931
* @availability serverless stability=stable visibility=public

specification/_global/search/SearchRequest.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,9 @@ import { SourceConfig, SourceConfigParam } from './_types/SourceFilter'
5252
import { Suggester } from './_types/suggester'
5353

5454
/**
55-
* Returns search hits that match the query defined in the request.
55+
* Run a search.
56+
*
57+
* Get search hits that match the query defined in the request.
5658
* You can provide search queries using the `q` query string parameter or the request body.
5759
* If both are specified, only the query parameter is used.
5860
* @rest_spec_name search

specification/_global/search_mvt/SearchMvtRequest.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ import { ZoomLevel } from './_types/ZoomLevel'
3232

3333
/**
3434
* Search a vector tile.
35-
* Searches a vector tile for geospatial values.
35+
*
36+
* Search a vector tile for geospatial values.
3637
* @rest_spec_name search_mvt
3738
* @availability stack since=7.15.0 stability=stable
3839
* @availability serverless stability=stable visibility=public

specification/_global/search_shards/SearchShardsRequest.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ import { RequestBase } from '@_types/Base'
2121
import { ExpandWildcards, Indices, Routing } from '@_types/common'
2222

2323
/**
24+
* Get the search shards.
25+
*
26+
* Get the indices and shards that a search request would be run against.
27+
* This information can be useful for working out issues or planning optimizations with routing and shard preferences.
28+
* When filtered aliases are used, the filter is returned as part of the indices section.
2429
* @rest_spec_name search_shards
2530
* @availability stack stability=stable
2631
* @doc_tag search

specification/_global/search_template/SearchTemplateRequest.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,12 @@ import {
3030
import { Duration } from '@_types/Time'
3131

3232
/**
33-
* Runs a search with a search template.
33+
* Run a search with a search template.
3434
* @rest_spec_name search_template
3535
* @availability stack since=2.0.0 stability=stable
3636
* @availability serverless stability=stable visibility=public
3737
* @doc_tag search
38+
* @ext_doc_id search-template
3839
*/
3940
export interface Request extends RequestBase {
4041
path_parts: {

specification/_global/termvectors/TermVectorsRequest.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ import { Filter } from './types'
3232

3333
/**
3434
* Get term vector information.
35-
* Returns information and statistics about terms in the fields of a particular document.
35+
*
36+
* Get information and statistics about terms in the fields of a particular document.
3637
* @rest_spec_name termvectors
3738
* @availability stack stability=stable
3839
* @availability serverless stability=stable visibility=public

specification/async_search/delete/AsyncSearchDeleteRequest.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import { Id } from '@_types/common'
2222

2323
/**
2424
* Delete an async search.
25+
*
2526
* If the asynchronous search is still running, it is cancelled.
2627
* Otherwise, the saved search results are deleted.
2728
* 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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import { Duration } from '@_types/Time'
2323

2424
/**
2525
* Get async search results.
26+
*
2627
* Retrieve the results of a previously submitted asynchronous search request.
2728
* 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.
2829
* @rest_spec_name async_search.get

specification/async_search/status/AsyncSearchStatusRequest.ts

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,9 @@ import { RequestBase } from '@_types/Base'
2121
import { Id } from '@_types/common'
2222

2323
/**
24-
* Get async search status.
25-
* Retrieve the status of a previously submitted async search request given its identifier, without retrieving search results.
24+
* Get the async search status.
25+
*
26+
* Get the status of a previously submitted async search request given its identifier, without retrieving search results.
2627
* If the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.
2728
* @rest_spec_name async_search.status
2829
* @availability stack since=7.11.0 stability=stable

specification/async_search/submit/AsyncSearchSubmitRequest.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ import { Duration } from '@_types/Time'
5454

5555
/**
5656
* Run an async search.
57+
*
5758
* 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.
5859
*
5960
* Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.

0 commit comments

Comments
 (0)