Skip to content

Expanding on search api query parameters #10979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Expanding on search api query parameters #10979

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
183d75d
adding info api docs
AntonEliatra Sep 15, 2025
424ddb0
Revert "adding info api docs"
AntonEliatra Sep 15, 2025
c3dbb1e
expanding examples on search API
AntonEliatra Sep 18, 2025
da7eb57
Update search.md
AntonEliatra Sep 19, 2025
0779593
Update search.md
AntonEliatra Sep 19, 2025
733c195
addressing PR comments
AntonEliatra Sep 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ _site
.jekyll-metadata
.DS_Store
Gemfile.lock
.bundle
.idea
*.iml
.jekyll-cache
Expand Down
92 changes: 46 additions & 46 deletions _api-reference/search-apis/search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,51 +30,47 @@

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` |
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` |

Check failure on line 41 in _api-reference/search-apis/search.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: df. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: df. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/search-apis/search.md", "range": {"start": {"line": 41, "column": 1}}}, "severity": "ERROR"}
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 <field> : <direction> 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` |

Check failure on line 63 in _api-reference/search-apis/search.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: _source. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: _source. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/search-apis/search.md", "range": {"start": {"line": 63, "column": 2}}}, "severity": "ERROR"}
_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` |

Check failure on line 64 in _api-reference/search-apis/search.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: _source. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: _source. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/search-apis/search.md", "range": {"start": {"line": 64, "column": 2}}}, "severity": "ERROR"}
_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"}}}}` |
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

Expand Down Expand Up @@ -102,13 +98,17 @@
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 &lt;index&gt; : &lt;boost-multiplier&gt;
indices_boost | Array of objects | The values used to boost the score of specified indexes. Specify in the format of &lt;index&gt; : &lt;boost-multiplier&gt;
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.
Expand Down
Loading