From 5f9c0d575ac1c3095a95dac5b008788a963b5b5d Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Thu, 18 May 2023 09:50:27 -0400 Subject: [PATCH] Add the preference query parameter options (#4099) * Add the preference query parameter options Signed-off-by: Fanit Kolchina * Add more valid values Signed-off-by: Fanit Kolchina * Apply suggestions from code review Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Heather Halter Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --------- Signed-off-by: Fanit Kolchina Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com> Co-authored-by: Heather Halter Co-authored-by: Nathan Bower --- _api-reference/search.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/_api-reference/search.md b/_api-reference/search.md index a449ee42..71aa10e2 100644 --- a/_api-reference/search.md +++ b/_api-reference/search.md @@ -60,7 +60,7 @@ ignore_unavailable | Boolean | Specifies whether to include missing or closed in 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. 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 which shard or node OpenSearch should perform the count operation on. +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. @@ -86,6 +86,20 @@ track_total_hits | Boolean or Integer | Whether to return how many documents mat 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. +### The `preference` query parameter + +The `preference` query parameter specifies the shards or nodes on which OpenSearch should perform the search. The following are valid values: + +- `_primary`: Perform the search only on primary shards. +- `_replica`: Perform the search only on replica shards. +- `_primary_first`: Perform the search on primary shards but fail over to other available shards if primary shards are not available. +- `_replica_first`: Perform the search on replica shards but fail over to other available shards if replica shards are not available. +- `_local`: If possible, perform the search on the local node's shards. +- `_prefer_nodes:,`: If possible, perform the search on the specified nodes. Use a comma-separated list to specify multiple nodes. +- `_shards:,`: Perform the search only on the specified shards. Use a comma-separated list to specify multiple shards. When combined with other preferences, the `_shards` preference must be listed first. For example, `_shards:1,2|_replica`. +- `_only_nodes:,`: Perform the search only on the specified nodes. Use a comma-separated list to specify multiple nodes. +- ``: Specifies a custom string to use for the search. The string cannot start with an underscore character (`_`). Searches with the same custom string are routed to the same shards. + ## Request body All fields are optional.