From 183d75dd352d1128640bec396f4d9f1b9defa55a Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Mon, 15 Sep 2025 14:04:11 +0100 Subject: [PATCH 01/11] adding info api docs Signed-off-by: Anton Rubin --- _api-reference/cluster-api/info.md | 72 ++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 _api-reference/cluster-api/info.md diff --git a/_api-reference/cluster-api/info.md b/_api-reference/cluster-api/info.md new file mode 100644 index 00000000000..dfc844107e7 --- /dev/null +++ b/_api-reference/cluster-api/info.md @@ -0,0 +1,72 @@ +--- +layout: default +title: Info +nav_order: 65 +parent: Cluster APIs +has_children: false +--- + +# Info API + +The `/` API retrieves information about the running OpenSearch cluster and node, including version, build details, and cluster name. +This is the simplest way to verify that a cluster is reachable and to discover the OpenSearch version. + +## Endpoints + +```json +GET / +HEAD / +``` + +- `GET /` returns a JSON body with cluster and version details. +- `HEAD /` returns only an HTTP status (200 if reachable), useful for lightweight health checks. + +## Example request + +Get version and build information from the cluster. + +```json +GET / +``` +{% include copy-curl.html %} + +## Example response + +```json +{ + "name": "opensearch-node1", + "cluster_name": "opensearch-cluster", + "cluster_uuid": "sQj1b9cZQICv0b8iYc3y5A", + "version": { + "distribution": "opensearch", + "number": "3.2.0", + "build_type": "tar", + "build_hash": "abc123def456", + "build_date": "2025-06-18T12:34:56.000Z", + "build_snapshot": false, + "lucene_version": "9.10.0", + "minimum_wire_compatibility_version": "7.10.0", + "minimum_index_compatibility_version": "7.0.0" + }, + "tagline": "The OpenSearch Project: https://opensearch.org/" +} +``` + +## Response body fields + +Field | Type | Description +:--- | :--- | :--- +name | String | The name of the node that served the request. +cluster_name | String | The name of the cluster. +cluster_uuid | String | Universally unique identifier of the cluster. +tagline | String | The tagline string. +version | Object | The object containing version and build metadata. +version.distribution | String | The distribution identifier, typically `opensearch`. +version.number | String | The openSearch version number, for example, `3.2.0`. +version.build_type | String | The distribution type. +version.build_hash | String | The commit hash the build was created from. +version.build_date | String | The build timestamp in ISO 8601 format. +version.build_snapshot | Boolean | Whether the build is a snapshot build. +version.lucene_version | String | The lucene version used by this build. +version.minimum_wire_compatibility_version | String | The minimum compatible transport protocol version. +version.minimum_index_compatibility_version | String | The minimum index version that can be read. From 424ddb0f45d43e4c9441d2d81bdacbf719870f59 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Mon, 15 Sep 2025 14:18:23 +0100 Subject: [PATCH 02/11] Revert "adding info api docs" This reverts commit 197c1fdc57f002edd8c76d1003ffe70a3c6804d8. Signed-off-by: Anton Rubin --- _api-reference/cluster-api/info.md | 72 ------------------------------ 1 file changed, 72 deletions(-) delete mode 100644 _api-reference/cluster-api/info.md diff --git a/_api-reference/cluster-api/info.md b/_api-reference/cluster-api/info.md deleted file mode 100644 index dfc844107e7..00000000000 --- a/_api-reference/cluster-api/info.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: default -title: Info -nav_order: 65 -parent: Cluster APIs -has_children: false ---- - -# Info API - -The `/` API retrieves information about the running OpenSearch cluster and node, including version, build details, and cluster name. -This is the simplest way to verify that a cluster is reachable and to discover the OpenSearch version. - -## Endpoints - -```json -GET / -HEAD / -``` - -- `GET /` returns a JSON body with cluster and version details. -- `HEAD /` returns only an HTTP status (200 if reachable), useful for lightweight health checks. - -## Example request - -Get version and build information from the cluster. - -```json -GET / -``` -{% include copy-curl.html %} - -## Example response - -```json -{ - "name": "opensearch-node1", - "cluster_name": "opensearch-cluster", - "cluster_uuid": "sQj1b9cZQICv0b8iYc3y5A", - "version": { - "distribution": "opensearch", - "number": "3.2.0", - "build_type": "tar", - "build_hash": "abc123def456", - "build_date": "2025-06-18T12:34:56.000Z", - "build_snapshot": false, - "lucene_version": "9.10.0", - "minimum_wire_compatibility_version": "7.10.0", - "minimum_index_compatibility_version": "7.0.0" - }, - "tagline": "The OpenSearch Project: https://opensearch.org/" -} -``` - -## Response body fields - -Field | Type | Description -:--- | :--- | :--- -name | String | The name of the node that served the request. -cluster_name | String | The name of the cluster. -cluster_uuid | String | Universally unique identifier of the cluster. -tagline | String | The tagline string. -version | Object | The object containing version and build metadata. -version.distribution | String | The distribution identifier, typically `opensearch`. -version.number | String | The openSearch version number, for example, `3.2.0`. -version.build_type | String | The distribution type. -version.build_hash | String | The commit hash the build was created from. -version.build_date | String | The build timestamp in ISO 8601 format. -version.build_snapshot | Boolean | Whether the build is a snapshot build. -version.lucene_version | String | The lucene version used by this build. -version.minimum_wire_compatibility_version | String | The minimum compatible transport protocol version. -version.minimum_index_compatibility_version | String | The minimum index version that can be read. From c3dbb1e8d6a08d0fbddb982bccbdf3ba084fb5dd Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Thu, 18 Sep 2025 16:16:17 +0100 Subject: [PATCH 03/11] expanding examples on search API Signed-off-by: Anton Rubin --- .gitignore | 1 + _api-reference/search-apis/search.md | 92 ++++++++++++++-------------- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/.gitignore b/.gitignore index 92f01c5fca9..09b607173de 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ _site .jekyll-metadata .DS_Store Gemfile.lock +.bundle .idea *.iml .jekyll-cache diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index 94516765719..2bfb82ff525 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -30,51 +30,47 @@ All parameters are optional. Parameter | Type | Description :--- | :--- | :--- -allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. -allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. -analyzer | String | Analyzer to use in the query string. -analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. -batched_reduce_size | Integer | How many shard results to reduce on a node. Default is 512. -cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-settings/). Default is -1. -ccs_minimize_roundtrips | Boolean | Whether to minimize roundtrips between a node and remote clusters. Default is `true`. -default_operator | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR. -df | String | The default field in case a field prefix is not provided in the query string. -docvalue_fields | String | The fields that OpenSearch should return using their docvalue forms. -expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open. -explain | Boolean | Whether to return details about how OpenSearch computed the document's score. Default is `false`. -from | Integer | The starting index to search from. Default is 0. -ignore_throttled | Boolean | Whether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is `true`. -ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`. -include_named_queries_score | Boolean | Whether to return scores for named queries. Default is `false`. -lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. -max_concurrent_shard_requests | Integer | How many concurrent shard requests this request should execute on each node. Default is 5. -phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. -pre_filter_shard_size | Integer | A prefilter size threshold that triggers a prefilter operation if the request exceeds the threshold. Default is 128 shards. -preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The `preference` query parameter](#the-preference-query-parameter). -q | String | Lucene query string’s query. -request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. -rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. -routing | String | Value used to route the update by query operation to a specific shard. -scroll | Time | How long to keep the search context open. -search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. -seq_no_primary_term | Boolean | Whether to return sequence number and primary term of the last operation of each document hit. -size | Integer | How many results to include in the response. -sort | List | A comma-separated list of <field> : <direction> pairs to sort by. -_source | String | Whether to include the `_source` field in the response. -_source_excludes | List | A comma-separated list of source fields to exclude from the response. -_source_includes | List | A comma-separated list of source fields to include in the response. -stats | String | Value to associate with the request for additional logging. -stored_fields | Boolean | Whether the get operation should retrieve fields stored in the index. Default is `false`. -suggest_field | String | Fields OpenSearch can use to look for similar terms. -suggest_mode | String | The mode to use when searching. Available options are `always` (use suggestions based on the provided terms), `popular` (use suggestions that have more occurrences), and `missing` (use suggestions for terms not in the index). -suggest_size | Integer | How many suggestions to return. -suggest_text | String | The source that suggestions should be based off of. -terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is 0. -timeout | Time | How long the operation should wait for a response from active shards. Default is `1m`. -track_scores | Boolean | Whether to return document scores. Default is `false`. -track_total_hits | Boolean or Integer | Whether to return how many documents matched the query. -typed_keys | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. -version | Boolean | Whether to include the document version as a match. +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true&size=0` | +allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false&size=0` | +analyzer | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard&size=0` | +analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true&size=0` | +batched_reduce_size | Integer | How many shard results to reduce on a node. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2&size=0` | +cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms&size=0` | +ccs_minimize_roundtrips | Boolean | Whether to minimize roundtrips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true&size=0` | +default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND&size=0` | +df | String | The default field in case a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title&size=0` | +docvalue_fields | String | The fields that OpenSearch should return using their docvalue forms. Example: `GET test-index/_search?docvalue_fields=ts,views&size=0` | +expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open. Example: `GET test-index-*/_search?expand_wildcards=open&size=0` | +explain | Boolean | Whether to return details about how OpenSearch computed the document’s score. Default is `false`. Requires `hits` to see details. Example: `GET test-index/_search?explain=true&size=1&q=title:test` | +from | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5` | +ignore_throttled | Boolean | Whether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true&size=0` | +ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true&size=0` | +include_named_queries_score | Boolean | Whether to return scores with named queries. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}` | +lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true&size=0` | +max_concurrent_shard_requests | Integer | How many concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2&size=0` | +phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true&size=0` | +pre_filter_shard_size | Integer | A prefilter size threshold that triggers a prefilter operation if the request exceeds the threshold. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1&size=0` | +preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local&size=0` | +q | String | Lucene query string’s query. Enables query-string helpers. Example: `GET test-index/_search?q=title:test&size=5` | +request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. Example: `GET test-index/_search?request_cache=true&size=0` | +rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true&size=0` | +routing | String | Value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42&size=0` | +scroll | Time | How long to keep the search context open. Requires `size` greater than `0` and a follow-up `_search/scroll`. Example: `GET test-index/_search?scroll=1m&size=2` | +search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch&size=0` | +seq_no_primary_term | Boolean | Whether to return sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test` | +size | Integer | How many results to include in the response. Example: `GET test-index/_search?size=3` | +sort | List | A comma-separated list of : pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3` | +_source | String | Whether to include the `_source` field in the response. Example: `GET test-index/_search?_source=false&size=1` | +_source_excludes | List | A comma-separated list of source fields to exclude from the response. Example: `GET test-index/_search?_source_excludes=title&size=1` | +_source_includes | List | A comma-separated list of source fields to include in the response. Example: `GET test-index/_search?_source_includes=title&size=1` | +stats | String | Value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc&size=0` | +stored_fields | List | Whether the get operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1` | +terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0`. Example: `GET test-index/_search?terminate_after=1&size=10` | +timeout | Time | How long the operation should wait for a response from active shards. Default is 1m. Default is `1m`. Example: `GET test-index/_search?timeout=10ms&size=0` | +track_scores | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3` | +track_total_hits | Boolean or Integer | Whether to return how many documents matched the query. Example: `GET test-index/_search?track_total_hits=2&size=0` | +typed_keys | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only visible with aggregations or suggest. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}` | +version | Boolean | Whether to include the document version as a match. Example: `GET test-index/_search?version=true&size=1&q=title:test` | ### The `preference` query parameter @@ -102,13 +98,17 @@ fields | Array | The fields to search for in the request. Specify a format to re explain | String | Whether to return details about how OpenSearch computed the document's score. Default is `false`. from | Integer | The starting index to search from. Default is 0. include_named_queries_score | Boolean | Whether to return scores for named queries. -indices_boost | Array of objects | Values used to boost the score of specified indexes. Specify in the format of <index> : <boost-multiplier> +indices_boost | Array of objects | The values used to boost the score of specified indexes. Specify in the format of <index> : <boost-multiplier> min_score | Integer | Specify a score threshold to return only documents above the threshold. query | Object | The [DSL query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index/) to use in the request. seq_no_primary_term | Boolean | Whether to return sequence number and primary term of the last operation of each document hit. size | Integer | How many results to return. Default is 10. _source | | Whether to include the `_source` field in the response. stats | String | Value to associate with the request for additional logging. +suggest_field | String | The field used for suggestions. Use with `suggest_text` and optionally `suggest_mode`, `suggest_size`. | +suggest_mode | String | The mode to use when searching. Available options are always (use suggestions based on the provided terms), popular (use suggestions that have more occurrences), and missing (use suggestions for terms not in the index). Requires `suggest_field` and `suggest_text`. | +suggest_size | Integer | The number of suggestions. Requires `suggest_field` and `suggest_text`. | +suggest_text | String | The input text for suggestions. Use with `suggest_field`. | terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is 0. timeout | Time | How long to wait for a response. Default is no timeout. version | Boolean | Whether to include the document version in the response. From da7eb5779974f05e6faffb7d230fec1e4d96b510 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Fri, 19 Sep 2025 11:20:31 +0100 Subject: [PATCH 04/11] Update search.md Signed-off-by: AntonEliatra Signed-off-by: Anton Rubin --- _api-reference/search-apis/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index 2bfb82ff525..44e8c40dbe5 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -36,7 +36,7 @@ analyzer | String | The analyzer to use in the query string. Requires `q=` or a analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true&size=0` | batched_reduce_size | Integer | How many shard results to reduce on a node. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2&size=0` | cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms&size=0` | -ccs_minimize_roundtrips | Boolean | Whether to minimize roundtrips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true&size=0` | +ccs_minimize_roundtrips | Boolean | Whether to minimize round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true&size=0` | default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND&size=0` | df | String | The default field in case a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title&size=0` | docvalue_fields | String | The fields that OpenSearch should return using their docvalue forms. Example: `GET test-index/_search?docvalue_fields=ts,views&size=0` | From 07795937d7ca3ff8d889521df772d63c42f2f560 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Fri, 19 Sep 2025 11:21:11 +0100 Subject: [PATCH 05/11] Update search.md Signed-off-by: AntonEliatra Signed-off-by: Anton Rubin --- _api-reference/search-apis/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index 44e8c40dbe5..bece46a9a63 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -39,7 +39,7 @@ cancel_after_time_interval | Time | The time after which the search request will ccs_minimize_roundtrips | Boolean | Whether to minimize round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true&size=0` | default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND&size=0` | df | String | The default field in case a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title&size=0` | -docvalue_fields | String | The fields that OpenSearch should return using their docvalue forms. Example: `GET test-index/_search?docvalue_fields=ts,views&size=0` | +docvalue_fields | String | The fields that OpenSearch should return using their `docvalue` forms. Example: `GET test-index/_search?docvalue_fields=ts,views&size=0` | expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open. Example: `GET test-index-*/_search?expand_wildcards=open&size=0` | explain | Boolean | Whether to return details about how OpenSearch computed the document’s score. Default is `false`. Requires `hits` to see details. Example: `GET test-index/_search?explain=true&size=1&q=title:test` | from | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5` | From 733c1950d34fc3d6c6c4fbc362de50812c0b764c Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Fri, 26 Sep 2025 11:17:43 +0100 Subject: [PATCH 06/11] addressing PR comments Signed-off-by: Anton Rubin --- _api-reference/search-apis/search.md | 50 ++++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index bece46a9a63..c03331f3f28 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -30,45 +30,45 @@ All parameters are optional. Parameter | Type | Description :--- | :--- | :--- -allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true&size=0` | -allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false&size=0` | -analyzer | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard&size=0` | -analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true&size=0` | -batched_reduce_size | Integer | How many shard results to reduce on a node. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2&size=0` | -cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms&size=0` | -ccs_minimize_roundtrips | Boolean | Whether to minimize round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true&size=0` | -default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND&size=0` | -df | String | The default field in case a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title&size=0` | -docvalue_fields | String | The fields that OpenSearch should return using their `docvalue` forms. Example: `GET test-index/_search?docvalue_fields=ts,views&size=0` | -expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open. Example: `GET test-index-*/_search?expand_wildcards=open&size=0` | +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true` | +allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false` | +analyzer | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard` | +analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true` | +batched_reduce_size | Integer | How many shard results to reduce on a node. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2` | +cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms` | +ccs_minimize_roundtrips | Boolean | Whether to minimize round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true` | +default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND` | +df | String | The default field in case a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title` | +docvalue_fields | String | The fields that OpenSearch should return using their `docvalue` forms. Example: `GET test-index/_search?docvalue_fields=ts,views` | +expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open. Example: `GET test-index-*/_search?expand_wildcards=open` | explain | Boolean | Whether to return details about how OpenSearch computed the document’s score. Default is `false`. Requires `hits` to see details. Example: `GET test-index/_search?explain=true&size=1&q=title:test` | from | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5` | -ignore_throttled | Boolean | Whether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true&size=0` | -ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true&size=0` | +ignore_throttled | Boolean | Whether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true` | +ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true` | include_named_queries_score | Boolean | Whether to return scores with named queries. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}` | -lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true&size=0` | -max_concurrent_shard_requests | Integer | How many concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2&size=0` | -phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true&size=0` | -pre_filter_shard_size | Integer | A prefilter size threshold that triggers a prefilter operation if the request exceeds the threshold. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1&size=0` | -preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local&size=0` | +lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true` | +max_concurrent_shard_requests | Integer | How many concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2` | +phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true` | +pre_filter_shard_size | Integer | A prefilter size threshold that triggers a prefilter operation if the request exceeds the threshold. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1` | +preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local` | q | String | Lucene query string’s query. Enables query-string helpers. Example: `GET test-index/_search?q=title:test&size=5` | -request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. Example: `GET test-index/_search?request_cache=true&size=0` | -rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true&size=0` | -routing | String | Value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42&size=0` | +request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. Example: `GET test-index/_search?request_cache=true` | +rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true` | +routing | String | Value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42` | scroll | Time | How long to keep the search context open. Requires `size` greater than `0` and a follow-up `_search/scroll`. Example: `GET test-index/_search?scroll=1m&size=2` | -search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch&size=0` | +search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch` | seq_no_primary_term | Boolean | Whether to return sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test` | size | Integer | How many results to include in the response. Example: `GET test-index/_search?size=3` | sort | List | A comma-separated list of : pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3` | _source | String | Whether to include the `_source` field in the response. Example: `GET test-index/_search?_source=false&size=1` | _source_excludes | List | A comma-separated list of source fields to exclude from the response. Example: `GET test-index/_search?_source_excludes=title&size=1` | _source_includes | List | A comma-separated list of source fields to include in the response. Example: `GET test-index/_search?_source_includes=title&size=1` | -stats | String | Value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc&size=0` | +stats | String | Value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc` | stored_fields | List | Whether the get operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1` | terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0`. Example: `GET test-index/_search?terminate_after=1&size=10` | -timeout | Time | How long the operation should wait for a response from active shards. Default is 1m. Default is `1m`. Example: `GET test-index/_search?timeout=10ms&size=0` | +timeout | Time | How long the operation should wait for a response from active shards. Default is 1m. Default is `1m`. Example: `GET test-index/_search?timeout=10ms` | track_scores | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3` | -track_total_hits | Boolean or Integer | Whether to return how many documents matched the query. Example: `GET test-index/_search?track_total_hits=2&size=0` | +track_total_hits | Boolean or Integer | Whether to return how many documents matched the query. Example: `GET test-index/_search?track_total_hits=2` | typed_keys | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only visible with aggregations or suggest. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}` | version | Boolean | Whether to include the document version as a match. Example: `GET test-index/_search?version=true&size=1&q=title:test` | From bef990c53f622dfd994dfa24ce066472b4c69bee Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 16 Oct 2025 12:05:28 +0100 Subject: [PATCH 07/11] Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: AntonEliatra --- _api-reference/search-apis/search.md | 90 ++++++++++++++-------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index c03331f3f28..867f839addf 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -30,46 +30,46 @@ All parameters are optional. Parameter | Type | Description :--- | :--- | :--- -allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true` | -allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false` | -analyzer | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard` | -analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true` | -batched_reduce_size | Integer | How many shard results to reduce on a node. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2` | -cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over cancel_after_time_interval [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms` | -ccs_minimize_roundtrips | Boolean | Whether to minimize round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true` | -default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND` | -df | String | The default field in case a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title` | -docvalue_fields | String | The fields that OpenSearch should return using their `docvalue` forms. Example: `GET test-index/_search?docvalue_fields=ts,views` | -expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open. Example: `GET test-index-*/_search?expand_wildcards=open` | -explain | Boolean | Whether to return details about how OpenSearch computed the document’s score. Default is `false`. Requires `hits` to see details. Example: `GET test-index/_search?explain=true&size=1&q=title:test` | -from | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5` | -ignore_throttled | Boolean | Whether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true` | -ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true` | -include_named_queries_score | Boolean | Whether to return scores with named queries. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}` | -lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true` | -max_concurrent_shard_requests | Integer | How many concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2` | -phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true` | -pre_filter_shard_size | Integer | A prefilter size threshold that triggers a prefilter operation if the request exceeds the threshold. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1` | -preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local` | -q | String | Lucene query string’s query. Enables query-string helpers. Example: `GET test-index/_search?q=title:test&size=5` | -request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings. Example: `GET test-index/_search?request_cache=true` | -rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true` | -routing | String | Value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42` | -scroll | Time | How long to keep the search context open. Requires `size` greater than `0` and a follow-up `_search/scroll`. Example: `GET test-index/_search?scroll=1m&size=2` | -search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch` | -seq_no_primary_term | Boolean | Whether to return sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test` | -size | Integer | How many results to include in the response. Example: `GET test-index/_search?size=3` | -sort | List | A comma-separated list of : pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3` | -_source | String | Whether to include the `_source` field in the response. Example: `GET test-index/_search?_source=false&size=1` | -_source_excludes | List | A comma-separated list of source fields to exclude from the response. Example: `GET test-index/_search?_source_excludes=title&size=1` | -_source_includes | List | A comma-separated list of source fields to include in the response. Example: `GET test-index/_search?_source_includes=title&size=1` | -stats | String | Value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc` | -stored_fields | List | Whether the get operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1` | -terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0`. Example: `GET test-index/_search?terminate_after=1&size=10` | -timeout | Time | How long the operation should wait for a response from active shards. Default is 1m. Default is `1m`. Example: `GET test-index/_search?timeout=10ms` | -track_scores | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3` | -track_total_hits | Boolean or Integer | Whether to return how many documents matched the query. Example: `GET test-index/_search?track_total_hits=2` | -typed_keys | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only visible with aggregations or suggest. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}` | +allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true`. | +allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false`. | +analyzer | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard`. | +analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true`. | +batched_reduce_size | Integer | The number of shard results to combine into one batch on the coordinating node before returning the final search results. Limits the number of shard results processed together, helping reduce memory usage when a search request spans many shards. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2`. | +cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over the `cancel_after_time_interval` [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms`. | +ccs_minimize_roundtrips | Boolean | Whether to minimize the number of round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true`. | +default_operator | String | The default operator for a string query. Valid values are `AND` and `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND`. | +df | String | The default field used if a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title`. | +docvalue_fields | String | A comma-separated list of fields whose values should be returned from their doc values representation. Doc values are an optimized, columnar format that improves performance for aggregations, sorting, and scripting. Example: `GET test-index/_search?docvalue_fields=ts,views`. | +expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with `open`, `closed`, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes.
Default is `open`. Example: `GET test-index-*/_search?expand_wildcards=open`. | +explain | Boolean | If `true`, returns details about how OpenSearch computed each document's relevance score. Default is `false`. Only applies when `hits` are included in the search response. Example: `GET test-index/_search?explain=true&size=1&q=title:test`. | +from | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5`. | +ignore_throttled | Boolean | Whether to ignore concrete indexes, expanded indexes, or indexes with aliases if they are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true`. | +ignore_unavailable | Boolean | If `true`, OpenSearch ignores missing or closed indexes and unavailable shards during the search. If `false`, the request returns an error when targeting missing or closed indexes. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true`. | +include_named_queries_score | Boolean | Whether to return score contributions from named queries (queries with `_name`) for each hit. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}`. | +lenient | Boolean | Whether OpenSearch should accept requests if queries have format errors (for example, querying a numeric field using text) instead of returning an error. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true`. | +max_concurrent_shard_requests | Integer | The maximum number of concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2`. | +phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true`. | +pre_filter_shard_size | Integer | A prefilter size threshold for triggering a prefilter operation on search shards. If the number of shards a search request expands to exceeds this value, OpenSearch performs a prefilter operation to eliminate shards that cannot match documents based on query rewriting. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1`. | +preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local`. | +q | String | A Lucene query string query. Enables query-string helpers. Takes precedence over the `query` parameter in the request body. If both are specified, only documents matching this parameter are returned; the query in the request body is ignored. Example: `GET test-index/_search?q=title:test&size=5`. | +request_cache | Boolean | Whether OpenSearch should use caching of search results for a request if `size=0` is specified. Default is the index-level `request_cache` setting. Example: `GET test-index/_search?request_cache=true`. | +rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true`. | +routing | String | The value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42`. | +scroll | Time | The amount of time to keep the search context open. Requires `size` greater than `0` and a follow-up `_search/scroll`. Example: `GET test-index/_search?scroll=1m&size=2`. | +search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid values are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It's usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It's usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch`. | +seq_no_primary_term | Boolean | Whether to return the sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test`. | +size | Integer | The number of results to include in the response. Example: `GET test-index/_search?size=3`. | +sort | List | A comma-separated list of ` : ` pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | +_source | String or Boolean | Controls the `_source` field provided in the response. Valid values are `true` (return the document source), `false` (do not return the document source) and `` (the field or fields in the source to return provided as a list or wildcard pattern). Examples: `GET test-index/_search?_source=false&size=1`, `GET test-index/_search?_source=titl*&size=1`, `GET test-index/_search?_source=title,description&size=1`. | +_source_excludes | List | A comma-separated list of source fields to exclude from the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_excludes=title&size=1`. | +_source_includes | List | A comma-separated list of source fields to include in the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_includes=title&size=1`. | +stats | String | A value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc`. | +stored_fields | List | Whether the GET operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1`. | +terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0` (no maximum). Example: `GET test-index/_search?terminate_after=1&size=10`. | +timeout | Time | How long the operation should wait for a response from active shards. Default is `1m` (1 minute). Example: `GET test-index/_search?timeout=10ms`. | +track_scores | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | +track_total_hits | Boolean or Integer | Whether to return the total number of documents that matched the query. Example: `GET test-index/_search?track_total_hits=2`. | +typed_keys | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only applicable for aggregations or suggesters. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}`. | version | Boolean | Whether to include the document version as a match. Example: `GET test-index/_search?version=true&size=1&q=title:test` | ### The `preference` query parameter @@ -98,17 +98,17 @@ fields | Array | The fields to search for in the request. Specify a format to re explain | String | Whether to return details about how OpenSearch computed the document's score. Default is `false`. from | Integer | The starting index to search from. Default is 0. include_named_queries_score | Boolean | Whether to return scores for named queries. -indices_boost | Array of objects | The values used to boost the score of specified indexes. Specify in the format of <index> : <boost-multiplier> +indices_boost | Array of objects | Boosts the`_score` of documents from specific indexes. Each entry specifies an index and a boost factor in the format `: `. A boost greater than `1.0` increases the score, while a boost between `0` and `1.0` decreases it. min_score | Integer | Specify a score threshold to return only documents above the threshold. query | Object | The [DSL query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index/) to use in the request. seq_no_primary_term | Boolean | Whether to return sequence number and primary term of the last operation of each document hit. size | Integer | How many results to return. Default is 10. _source | | Whether to include the `_source` field in the response. stats | String | Value to associate with the request for additional logging. -suggest_field | String | The field used for suggestions. Use with `suggest_text` and optionally `suggest_mode`, `suggest_size`. | -suggest_mode | String | The mode to use when searching. Available options are always (use suggestions based on the provided terms), popular (use suggestions that have more occurrences), and missing (use suggestions for terms not in the index). Requires `suggest_field` and `suggest_text`. | -suggest_size | Integer | The number of suggestions. Requires `suggest_field` and `suggest_text`. | -suggest_text | String | The input text for suggestions. Use with `suggest_field`. | +suggest_field | String | The field used for suggestions. Use with `suggest_text` and, optionally, `suggest_mode` or `suggest_size`. | +suggest_mode | String | The mode to use when searching. Valid values are `always` (provide suggestions based on the terms in `suggest_text`), `popular` (provide suggestions occurring in more documents on the shard than the search term), and `missing` (provide suggestions for terms not in the shard). Requires `suggest_field` and `suggest_text`. | +suggest_size | Integer | The number of suggestions to return. Requires `suggest_field` and `suggest_text`. | +suggest_text | String | The input text for which OpenSearch should return suggestions. Requires `suggest_field` and `suggest_text`. | terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is 0. timeout | Time | How long to wait for a response. Default is no timeout. version | Boolean | Whether to include the document version in the response. From c9f82ed090312b034160add5b0538c10cf80c73c Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Thu, 16 Oct 2025 13:54:00 +0100 Subject: [PATCH 08/11] addressing PR comments Signed-off-by: Anton Rubin --- _api-reference/search-apis/search.md | 79 +++++++++++++++------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index 867f839addf..dac03dbf5b7 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -28,49 +28,52 @@ POST /_search All parameters are optional. +Many of the parameters apply only when you use the URL `q=` parameter or a `query_string` query, see [Query string query]({{site.url}}{{site.baseurl}}/query-dsl/full-text/query-string/) for further details. +{: .note} + Parameter | Type | Description :--- | :--- | :--- -allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true`. | -allow_partial_search_results | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false`. | -analyzer | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard`. | -analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true`. | -batched_reduce_size | Integer | The number of shard results to combine into one batch on the coordinating node before returning the final search results. Limits the number of shard results processed together, helping reduce memory usage when a search request spans many shards. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2`. | -cancel_after_time_interval | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over the `cancel_after_time_interval` [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms`. | -ccs_minimize_roundtrips | Boolean | Whether to minimize the number of round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true`. | -default_operator | String | The default operator for a string query. Valid values are `AND` and `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND`. | -df | String | The default field used if a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title`. | -docvalue_fields | String | A comma-separated list of fields whose values should be returned from their doc values representation. Doc values are an optimized, columnar format that improves performance for aggregations, sorting, and scripting. Example: `GET test-index/_search?docvalue_fields=ts,views`. | -expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with `open`, `closed`, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes.
Default is `open`. Example: `GET test-index-*/_search?expand_wildcards=open`. | -explain | Boolean | If `true`, returns details about how OpenSearch computed each document's relevance score. Default is `false`. Only applies when `hits` are included in the search response. Example: `GET test-index/_search?explain=true&size=1&q=title:test`. | -from | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5`. | -ignore_throttled | Boolean | Whether to ignore concrete indexes, expanded indexes, or indexes with aliases if they are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true`. | -ignore_unavailable | Boolean | If `true`, OpenSearch ignores missing or closed indexes and unavailable shards during the search. If `false`, the request returns an error when targeting missing or closed indexes. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true`. | -include_named_queries_score | Boolean | Whether to return score contributions from named queries (queries with `_name`) for each hit. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}`. | -lenient | Boolean | Whether OpenSearch should accept requests if queries have format errors (for example, querying a numeric field using text) instead of returning an error. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true`. | +`allow_no_indices` | Boolean | Whether to ignore wildcards that don't match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true`. | +`allow_partial_search_results` | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false`. | +`analyzer` | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard`. | +`analyze_wildcard` | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true`. | +`batched_reduce_size` | Integer | The number of shard results to combine into one batch on the coordinating node before returning the final search results. Limits the number of shard results processed together, helping reduce memory usage when a search request spans many shards. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2`. | +`cancel_after_time_interval` | Time | The time after which the search request will be canceled. Request-level parameter takes precedence over the `cancel_after_time_interval` [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). Default is `-1`. Example: `GET test-index/_search?cancel_after_time_interval=10ms`. | +`ccs_minimize_roundtrips` | Boolean | Whether to minimize the number of round trips between a node and remote clusters. Default is `true`. Example: `GET test-index/_search?ccs_minimize_roundtrips=true`. | +`default_operator` | String | The default operator for a string query. Valid values are `AND` and `OR`. Default is `OR`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:test one&default_operator=AND`. | +`df` | String | The default field used if a field prefix is not provided in the query string. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=test&df=title`. | +`docvalue_fields` | String | A comma-separated list of fields whose values should be returned from their doc values representation. Doc values are an optimized, columnar format that improves performance for aggregations, sorting, and scripting. Example: `GET test-index/_search?docvalue_fields=ts,views`. | +`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values.
Valid values are:
- `all`: Match any index, including hidden ones.
- `closed`: Match closed, non-hidden indexes.
- `hidden`: Match hidden indexes. Must be combined with `open`, `closed`, or both.
- `none`: Wildcard expressions are not accepted.
- `open`: Match open, non-hidden indexes.
Default is `open`. Example: `GET test-index-*/_search?expand_wildcards=open`. | +`explain` | Boolean | If `true`, returns details about how OpenSearch computed each document's relevance score. Default is `false`. Only applies when `hits` are included in the search response. Example: `GET test-index/_search?explain=true&size=1&q=title:test`. | +`from` | Integer | The starting index to search from. Default is `0`. Example: `GET test-index/_search?from=5&size=5`. | +`ignore_throttled` | Boolean | Whether to ignore concrete indexes, expanded indexes, or indexes with aliases if they are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true`. | +`ignore_unavailable` | Boolean | If `true`, OpenSearch ignores missing or closed indexes and unavailable shards during the search. If `false`, the request returns an error when targeting missing or closed indexes. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true`. | +`include_named_queries_score` | Boolean | Whether to return score contributions from named queries (queries with `_name`) for each hit. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}`. | +`lenient` | Boolean | Whether OpenSearch should accept requests if queries have format errors (for example, querying a numeric field using text) instead of returning an error. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true`. | max_concurrent_shard_requests | Integer | The maximum number of concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2`. | -phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true`. | -pre_filter_shard_size | Integer | A prefilter size threshold for triggering a prefilter operation on search shards. If the number of shards a search request expands to exceeds this value, OpenSearch performs a prefilter operation to eliminate shards that cannot match documents based on query rewriting. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1`. | -preference | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local`. | -q | String | A Lucene query string query. Enables query-string helpers. Takes precedence over the `query` parameter in the request body. If both are specified, only documents matching this parameter are returned; the query in the request body is ignored. Example: `GET test-index/_search?q=title:test&size=5`. | -request_cache | Boolean | Whether OpenSearch should use caching of search results for a request if `size=0` is specified. Default is the index-level `request_cache` setting. Example: `GET test-index/_search?request_cache=true`. | -rest_total_hits_as_int | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true`. | -routing | String | The value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42`. | -scroll | Time | The amount of time to keep the search context open. Requires `size` greater than `0` and a follow-up `_search/scroll`. Example: `GET test-index/_search?scroll=1m&size=2`. | -search_type | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid values are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It's usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It's usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch`. | -seq_no_primary_term | Boolean | Whether to return the sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test`. | -size | Integer | The number of results to include in the response. Example: `GET test-index/_search?size=3`. | -sort | List | A comma-separated list of ` : ` pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | -_source | String or Boolean | Controls the `_source` field provided in the response. Valid values are `true` (return the document source), `false` (do not return the document source) and `` (the field or fields in the source to return provided as a list or wildcard pattern). Examples: `GET test-index/_search?_source=false&size=1`, `GET test-index/_search?_source=titl*&size=1`, `GET test-index/_search?_source=title,description&size=1`. | -_source_excludes | List | A comma-separated list of source fields to exclude from the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_excludes=title&size=1`. | -_source_includes | List | A comma-separated list of source fields to include in the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_includes=title&size=1`. | -stats | String | A value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc`. | +`phase_took` | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true`. | +`pre_filter_shard_size` | Integer | A prefilter size threshold for triggering a prefilter operation on search shards. If the number of shards a search request expands to exceeds this value, OpenSearch performs a prefilter operation to eliminate shards that cannot match documents based on query rewriting. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1`. | +`preference` | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local`. | +`q` | String | A Lucene query string query. Enables query-string helpers. Takes precedence over the `query` parameter in the request body. If both are specified, only documents matching this parameter are returned; the query in the request body is ignored. Example: `GET test-index/_search?q=title:test&size=5`. | +`request_cache` | Boolean | Whether OpenSearch should use caching of search results for a request if `size=0` is specified. Default is the index-level `request_cache` setting. Example: `GET test-index/_search?request_cache=true`. | +`rest_total_hits_as_int` | Boolean | Whether to return `hits.total` as an integer. Returns an object otherwise. Default is `false`. Use with `track_total_hits` set to `true`. Example: `GET test-index/_search?track_total_hits=true&rest_total_hits_as_int=true`. | +`routing` | String | The value used to route the update by query operation to a specific shard. Example: `GET test-index/_search?routing=user-42`. | +`scroll` | Time | The amount of time to keep the search context open. Requires `size` greater than `0` and a follow-up `_search/scroll`. Example: `GET test-index/_search?scroll=1m&size=2`. | +`search_type` | String | Whether OpenSearch should use global term and document frequencies when calculating relevance scores. Valid values are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It's usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It's usually slower but more accurate. Default is `query_then_fetch`. Example: `GET test-index/_search?search_type=dfs_query_then_fetch`. | +`seq_no_primary_term` | Boolean | Whether to return the sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test`. | +`size` | Integer | The number of results to include in the response. Example: `GET test-index/_search?size=3`. | +`sort` | List | A comma-separated list of ` : ` pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | +`_source` | String or Boolean | Controls the `_source` field provided in the response. Valid values are `true` (return the document source), `false` (do not return the document source) and `` (the field or fields in the source to return provided as a list or wildcard pattern). Examples: `GET test-index/_search?_source=false&size=1`, `GET test-index/_search?_source=titl*&size=1`, `GET test-index/_search?_source=title,description&size=1`. | +`_source_excludes` | List | A comma-separated list of source fields to exclude from the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_excludes=title&size=1`. | +`_source_includes` | List | A comma-separated list of source fields to include in the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_includes=title&size=1`. | +`stats` | String | A value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc`. | stored_fields | List | Whether the GET operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1`. | -terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0` (no maximum). Example: `GET test-index/_search?terminate_after=1&size=10`. | -timeout | Time | How long the operation should wait for a response from active shards. Default is `1m` (1 minute). Example: `GET test-index/_search?timeout=10ms`. | +`terminate_after` | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0` (no maximum). Example: `GET test-index/_search?terminate_after=1&size=10`. | +`timeout` | Time | How long the operation should wait for a response from active shards. Default is `1m` (1 minute). Example: `GET test-index/_search?timeout=10ms`. | track_scores | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | -track_total_hits | Boolean or Integer | Whether to return the total number of documents that matched the query. Example: `GET test-index/_search?track_total_hits=2`. | -typed_keys | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only applicable for aggregations or suggesters. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}`. | -version | Boolean | Whether to include the document version as a match. Example: `GET test-index/_search?version=true&size=1&q=title:test` | +`track_total_hits` | Boolean or Integer | Whether to return the total number of documents that matched the query. Example: `GET test-index/_search?track_total_hits=2`. | +`typed_keys` | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only applicable for aggregations or suggesters. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}`. | +`version` | Boolean | Whether to include the document version as a match. Example: `GET test-index/_search?version=true&size=1&q=title:test`. | ### The `preference` query parameter From 2639fda404c6e4d99e6d5f40fc0471b2bbd45c2c Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Thu, 16 Oct 2025 13:54:02 +0100 Subject: [PATCH 09/11] addressing PR comments Signed-off-by: Anton Rubin --- _api-reference/search-apis/search.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index dac03dbf5b7..35e62ddb2eb 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -50,7 +50,7 @@ Parameter | Type | Description `ignore_unavailable` | Boolean | If `true`, OpenSearch ignores missing or closed indexes and unavailable shards during the search. If `false`, the request returns an error when targeting missing or closed indexes. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true`. | `include_named_queries_score` | Boolean | Whether to return score contributions from named queries (queries with `_name`) for each hit. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}`. | `lenient` | Boolean | Whether OpenSearch should accept requests if queries have format errors (for example, querying a numeric field using text) instead of returning an error. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true`. | -max_concurrent_shard_requests | Integer | The maximum number of concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2`. | +`max_concurrent_shard_requests` | Integer | The maximum number of concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2`. | `phase_took` | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true`. | `pre_filter_shard_size` | Integer | A prefilter size threshold for triggering a prefilter operation on search shards. If the number of shards a search request expands to exceeds this value, OpenSearch performs a prefilter operation to eliminate shards that cannot match documents based on query rewriting. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1`. | `preference` | String | Specifies the shards or nodes on which OpenSearch should perform the search. For valid values, see [The preference query parameter]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search/#the-preference-query-parameter). Example: `GET test-index/_search?preference=_local`. | @@ -67,10 +67,10 @@ max_concurrent_shard_requests | Integer | The maximum number of concurrent shard `_source_excludes` | List | A comma-separated list of source fields to exclude from the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_excludes=title&size=1`. | `_source_includes` | List | A comma-separated list of source fields to include in the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_includes=title&size=1`. | `stats` | String | A value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc`. | -stored_fields | List | Whether the GET operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1`. | +`stored_fields` | List | Whether the GET operation should retrieve fields stored in the index. Default is `false`. Example: `GET test-index-stored/_search?stored_fields=note&size=1`. | `terminate_after` | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is `0` (no maximum). Example: `GET test-index/_search?terminate_after=1&size=10`. | `timeout` | Time | How long the operation should wait for a response from active shards. Default is `1m` (1 minute). Example: `GET test-index/_search?timeout=10ms`. | -track_scores | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | +`track_scores` | Boolean | Whether to return document scores. Default is `false`. Use with `sort`. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | `track_total_hits` | Boolean or Integer | Whether to return the total number of documents that matched the query. Example: `GET test-index/_search?track_total_hits=2`. | `typed_keys` | Boolean | Whether returned aggregations and suggested terms should include their types in the response. Default is `true`. Only applicable for aggregations or suggesters. Example: `POST test-index/_search?typed_keys=true {"size":0,"aggs":{"a":{"terms":{"field":"views"}}}}`. | `version` | Boolean | Whether to include the document version as a match. Example: `GET test-index/_search?version=true&size=1&q=title:test`. | From 1ae848d9781d1f6663be3545fad04e175fe42a7e Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 16 Oct 2025 16:48:30 +0100 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: AntonEliatra --- _api-reference/search-apis/search.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index 35e62ddb2eb..abfbdf8837f 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -28,13 +28,13 @@ POST /_search All parameters are optional. -Many of the parameters apply only when you use the URL `q=` parameter or a `query_string` query, see [Query string query]({{site.url}}{{site.baseurl}}/query-dsl/full-text/query-string/) for further details. +Many of the parameters apply only when you use the URL `q=` parameter or a `query_string` query. See [Query string query]({{site.url}}{{site.baseurl}}/query-dsl/full-text/query-string/) for more information. {: .note} Parameter | Type | Description :--- | :--- | :--- `allow_no_indices` | Boolean | Whether to ignore wildcards that don't match any indexes. Default is `true`. Example: `GET test-index-*/_search?allow_no_indices=true`. | -`allow_partial_search_results` | Boolean | Whether to return partial results if the request runs into an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false`. | +`allow_partial_search_results` | Boolean | Whether to return partial results if the request encounters an error or times out. Default is `true`. Example: `GET test-index/_search?allow_partial_search_results=false`. | `analyzer` | String | The analyzer to use in the query string. Requires `q=` or a `query_string` body. Example: `GET test-index/_search?q=title:test&analyzer=standard`. | `analyze_wildcard` | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=title:te*&analyze_wildcard=true`. | `batched_reduce_size` | Integer | The number of shard results to combine into one batch on the coordinating node before returning the final search results. Limits the number of shard results processed together, helping reduce memory usage when a search request spans many shards. Default is `512`. Example: `GET test-index/_search?batched_reduce_size=2`. | @@ -49,7 +49,7 @@ Parameter | Type | Description `ignore_throttled` | Boolean | Whether to ignore concrete indexes, expanded indexes, or indexes with aliases if they are frozen. Default is `true`. Example: `GET test-index/_search?ignore_throttled=true`. | `ignore_unavailable` | Boolean | If `true`, OpenSearch ignores missing or closed indexes and unavailable shards during the search. If `false`, the request returns an error when targeting missing or closed indexes. Default is `false`. Example: `GET test-index-*/_search?ignore_unavailable=true`. | `include_named_queries_score` | Boolean | Whether to return score contributions from named queries (queries with `_name`) for each hit. Default is `false`. Requires queries named with `_name`. Example: `POST test-index/_search?include_named_queries_score=true {"size":1,"query":{"match":{"title":{"query":"test","_name":"q1"}}}}`. | -`lenient` | Boolean | Whether OpenSearch should accept requests if queries have format errors (for example, querying a numeric field using text) instead of returning an error. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true`. | +`lenient` | Boolean | Whether OpenSearch should accept requests if queries have formatting errors (for example, querying a numeric field using text) instead of returning an error. Default is `false`. Requires `q=` or `query_string`. Example: `GET test-index/_search?q=views:abc&lenient=true`. | `max_concurrent_shard_requests` | Integer | The maximum number of concurrent shard requests this request should execute on each node. Default is `5`. Example: `GET test-index/_search?max_concurrent_shard_requests=2`. | `phase_took` | Boolean | Whether to return phase-level `took` time values in the response. Default is `false`. Example: `GET test-index/_search?phase_took=true`. | `pre_filter_shard_size` | Integer | A prefilter size threshold for triggering a prefilter operation on search shards. If the number of shards a search request expands to exceeds this value, OpenSearch performs a prefilter operation to eliminate shards that cannot match documents based on query rewriting. Default is `128`. Example: `GET test-index/_search?pre_filter_shard_size=1`. | @@ -63,7 +63,7 @@ Parameter | Type | Description `seq_no_primary_term` | Boolean | Whether to return the sequence number and primary term of the last operation of each document hit. Example: `GET test-index/_search?seq_no_primary_term=true&size=1&q=title:test`. | `size` | Integer | The number of results to include in the response. Example: `GET test-index/_search?size=3`. | `sort` | List | A comma-separated list of ` : ` pairs to sort by. Use `track_scores=true` if you want scores when sorting by a non-score field. Example: `GET test-index/_search?sort=views:desc&track_scores=true&size=3`. | -`_source` | String or Boolean | Controls the `_source` field provided in the response. Valid values are `true` (return the document source), `false` (do not return the document source) and `` (the field or fields in the source to return provided as a list or wildcard pattern). Examples: `GET test-index/_search?_source=false&size=1`, `GET test-index/_search?_source=titl*&size=1`, `GET test-index/_search?_source=title,description&size=1`. | +`_source` | String or Boolean | Controls the `_source` field provided in the response. Valid values are `true` (return the document source), `false` (do not return the document source) and `` (the field or fields in the source to return, provided as a list or wildcard pattern). Examples: `GET test-index/_search?_source=false&size=1`, `GET test-index/_search?_source=titl*&size=1`, `GET test-index/_search?_source=title,description&size=1`. | `_source_excludes` | List | A comma-separated list of source fields to exclude from the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_excludes=title&size=1`. | `_source_includes` | List | A comma-separated list of source fields to include in the response. If the `_source` parameter is `false`, this parameter is ignored. Example: `GET test-index/_search?_source_includes=title&size=1`. | `stats` | String | A value to associate with the request for additional logging. Example: `GET test-index/_search?stats=doc`. | From b22f37969e53aa40341e83802ae56e55add4ca81 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Thu, 16 Oct 2025 12:32:20 -0400 Subject: [PATCH 11/11] Update _api-reference/search-apis/search.md Signed-off-by: Nathan Bower --- _api-reference/search-apis/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index abfbdf8837f..cfe1409e1ab 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -109,7 +109,7 @@ size | Integer | How many results to return. Default is 10. _source | | Whether to include the `_source` field in the response. stats | String | Value to associate with the request for additional logging. suggest_field | String | The field used for suggestions. Use with `suggest_text` and, optionally, `suggest_mode` or `suggest_size`. | -suggest_mode | String | The mode to use when searching. Valid values are `always` (provide suggestions based on the terms in `suggest_text`), `popular` (provide suggestions occurring in more documents on the shard than the search term), and `missing` (provide suggestions for terms not in the shard). Requires `suggest_field` and `suggest_text`. | +suggest_mode | String | The mode to use when searching. Valid values are `always` (provide suggestions based on the terms in `suggest_text`), `popular` (provide suggestions occurring in more documents on the shard than the search term), and `missing` (provide suggestions for terms not on the shard). Requires `suggest_field` and `suggest_text`. | suggest_size | Integer | The number of suggestions to return. Requires `suggest_field` and `suggest_text`. | suggest_text | String | The input text for which OpenSearch should return suggestions. Requires `suggest_field` and `suggest_text`. | terminate_after | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. Default is 0.