Add concurrent segment search documentation #4990

kolchfa-aws · 2023-09-07T23:35:22Z

Fixes #4989

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

kolchfa-aws · 2023-09-08T17:05:04Z

@sohami Could you review this PR for technical accuracy?

jed326 · 2023-09-08T17:22:30Z

_api-reference/index-apis/stats.md

+## Concurrent segment search
+
+Starting with OpenSearch 2.10, you can perform [concurrent segment search](search-plugins/concurrent-segment-search/), in which each shard-level request will search the segments in parallel during query phase. If you enable concurrent segment search, the Index Stats API response will contain several additional fields with statistics about slices (units of work executed by a thread). For more information about slices, see [Concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search#searching-segments-concurrently).


Small nit: These stats will show up if the feature flag is enabled for concurrent search, regardless of if the cluster/index settings for concurrent search are enabled.

jed326 · 2023-09-08T17:24:50Z

_api-reference/index-apis/stats.md

+{% include copy-curl.html %}
+
+## Concurrent segment search


These stats will also show up in nodes-stats as well as _cat/nodes, _cat/shards, _cat/indices but for the _cat APIs users can find it in the help section of the API.

@kolchfa-aws since all of these stats are gated by the concurrent search feature flag, I was thinking this information should be kept all within the concurrent-segment-search.md page too? I don't think we need to add these to the API pages until the feature is GA and the feature flag is removed, but it would be good to have the table below somewhere.

Yes, the two options are:

keep the APIs with the concurrent segment page

put the APIs in their respective pages.
It's a matter of opinion, but I think it makes it easier if the API changes are kept in the API pages. Users won't see concurrent-segment-related fields if they don't enable the feature, so I don't think there's any harm in keeping them in the API pages, especially because they are in a separate table. The danger with keeping them in the main page is that someone can just remove the experimental header and not add the API changes in the GA release.

The danger with keeping them in the main page is that someone can just remove the experimental header and not add the API changes in the GA release.

Maybe we can track this is an issue somewhere - perhaps #3662

Added a comment so we can track

ticheng-aws · 2023-09-08T17:24:24Z

_api-reference/profile.md

+|`time_in_nanos`	|For concurrent segment search, `time_in_nanos` is the cumulative amount of time to execute all methods across all slices, in nanoseconds. This is not equivalent to the actual amount of time the query took to execute because it does not take into account that multiple slices can execute the methods in parallel.	|
+|`breakdown.<method>`	|For concurrent segment search, this field contains the total amount of time taken by all segments to execute a method.	|
+|`<method>_count`	|For concurrent segment search, this field contains the total number of invocations of a `<method>` obtained by adding the number of method invocations for all segments.	|


nit: breakdown.<method>_count

ticheng-aws · 2023-09-08T17:27:32Z

_api-reference/profile.md

+The following sections contain definitions of all modified or added response fields for concurrent segment search.
+
+#### The `query` object


The query array

ticheng-aws · 2023-09-08T17:29:32Z

_api-reference/profile.md

+#### Example response
+
+The following is an example response for a concurrent search with three segment slices:


Should we mention this response has profile enabled?

This file is the Profile API documentation and it states in the very beginning that you have to set profile to true in order to get these responses.

@ticheng-aws are any of these response fields gated by the concurrent search feature flag? If so I think we should call those out.

The new fields are not gated by the concurrent search feature flag.

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

kolchfa-aws · 2023-09-08T17:57:02Z

Thanks, @jed326 and @ticheng-aws! I implemented your comments.

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

jed326 · 2023-09-08T23:02:06Z

_api-reference/index-apis/stats.md

+{% include copy-curl.html %}
+
+## Concurrent segment search


@kolchfa-aws since all of these stats are gated by the concurrent search feature flag, I was thinking this information should be kept all within the concurrent-segment-search.md page too? I don't think we need to add these to the API pages until the feature is GA and the feature flag is removed, but it would be good to have the table below somewhere.

jed326 · 2023-09-08T23:07:12Z

_api-reference/profile.md

+#### Example response
+
+The following is an example response for a concurrent search with three segment slices:


@ticheng-aws are any of these response fields gated by the concurrent search feature flag? If so I think we should call those out.

jed326 · 2023-09-08T23:19:37Z

_search-plugins/concurrent-segment-search.md

+## Concurrent segment search mechanisms
+
+You can choose one of the two available concurrent segment mechanisms: the default [Lucene mechanism](#the-lucene-mechanism) or the [max slice count mechanism](#the-max-slice-count-mechanism).


These mechanisms are about controlling the amount of concurrency, so maybe the section should be titled "Mechanisms to control search concurrency" or something along those lines.

How about Concurrent Segment Search Slice Calculation ?

You can choose one of the two available concurrent segment search slice calculation mechanisms:

How about "Slicing mechanisms"?

jed326 · 2023-09-08T23:20:49Z

_search-plugins/concurrent-segment-search.md

+
+### The Lucene mechanism
+
+By default, Lucene assigns a maximum of 250 K documents or 5 segments (whichever is met first) to each slice in a shard. For example, consider a shard with 11 segments. The first 5 segments have 250 K documents each and the next 6 segments have 20 K documents each. The first 5 segments will be assigned to one slice each because they each contain the maximum allowed document count for a slice. Then the next 5 segments will all be assigned to another slice because of the maximum allowed segment count for a slice. The 11th slice will be assigned to a separate slice. 


"Then the next 5 segments will all be assigned to another single slice"

sohami · 2023-09-08T22:52:08Z

_api-reference/cat/cat-indices.md

+
+## Concurrent segment search
+
+Starting with OpenSearch 2.10, you can perform [concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search/), in which each shard-level request will search the segments in parallel during query phase. If you [enable the concurrent segment search feature flag]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search#enabling-the-feature-flag), the CAT Indices API response will contain several additional fields with statistics about slices (units of work executed by a thread). For the descriptions of those fields, see [Index Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/stats#concurrent-segment-search).


@kolchfa-aws Lets not add these in the _cat/indices or /nodes and /shards API doc section. We only add the default stats displayed by these API. Users don't generally use these APIs for other stats

sohami · 2023-09-08T23:44:07Z

_search-plugins/concurrent-segment-search.md

+
+## The `terminate_after` search parameter
+
+The [`terminate_after` search parameter]({{site.url}}{{site.baseurl}}/api-reference/search/#url-parameters) is used to terminate a search request once a specified number of docs has been collected. In the non-concurrent search workflow, this count is evaluated at each shard, however for the concurrent search workflow this will be evaluated at each leaf slice instead to avoid synchronizing document counts between threads. Functionally there should be no difference, however in the concurrent search case the request may perform slightly more work than expected because of each segment slice on the shard collecting up to the specified number of docs.


The terminate_after search parameter is used to terminate a search request once a specified number of docs has been collected. In the non-concurrent search workflow, this count is evaluated at each shard, however for the concurrent search workflow this will be evaluated at each leaf slice instead to avoid synchronizing document counts between threads. In the concurrent search case, the request will perform more work than expected because of each segment slice on the shard collecting up to the specified number of docs. The intent to terminate collection after the threshold is reached is still kept at slice level. So you will see overall more hits count in result than terminate_after threshold but up to a max of slice_count * terminate_after. The number of returned hits will be controlled by size parameter.

sohami · 2023-09-08T23:55:27Z

_search-plugins/concurrent-segment-search.md

+
+## Searching segments concurrently
+
+Without concurrent segment search, Lucene executes a request sequentially across all segments on each shard during query phase. The query phase then collects the top hits for the search request. With concurrent segment search, each shard-level request will search the segments in parallel during query phase. For each shard, the segments are divided into multiple work units called _slices_. Each _slice_ is the unit of work which can be executed in parallel on a separate thread, thus the slice count determines the maximum degree of parallelism for a shard-level request. Once all the slices complete their work, Lucene performs a reduce operation on the slices, merging them and creating the final result for this shard-level request. Slices are executed using a new `index_searcher` thread pool, which is different from the `search` thread pool that handles shard-level requests.


Each _slice_ is the unit of work which can be executed in parallel on a separate thread ---> Each _slice_ can be executed in parallel on a separate thread

sohami · 2023-09-09T00:02:10Z

_search-plugins/concurrent-segment-search.md

+## Concurrent segment search mechanisms
+
+You can choose one of the two available concurrent segment mechanisms: the default [Lucene mechanism](#the-lucene-mechanism) or the [max slice count mechanism](#the-max-slice-count-mechanism).


How about Concurrent Segment Search Slice Calculation ?

You can choose one of the two available concurrent segment search slice calculation mechanisms:

sohami · 2023-09-09T00:04:38Z

_search-plugins/concurrent-segment-search.md

+- [CAT Indices]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-indices/)
+- [CAT Nodes]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-nodes/)
+- [CAT Shards]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-shards/)


I don't think we need to mention the _cat/indices or _cat/nodes or _cat/shards API here. Usually users don't see any index or node level stats using these APIs. And we don't add any other stats related info in the doc of these APIs anyways.

sohami · 2023-09-09T00:08:20Z

_api-reference/profile.md

+    },
+    "max_score": 1,
+    "hits": [


hits array and aggregation section we can remove with ... as that is not relevant here. We can just keep the profile portion

sohami · 2023-09-09T23:14:06Z

_search-plugins/concurrent-segment-search.md

+```
+{% include copy.html %}
+
+## Disabling concurrent search for an index or all indexes


Disabling concurrent search at index or cluster level

sohami · 2023-09-09T23:18:47Z

_search-plugins/concurrent-segment-search.md

+Use concurrent segment search to search the segments in parallel during query phase. Some cases in which concurrent segment search improves search latency include the following:
+
+- When sending long-running requests, for example, requests that contain aggregations or large ranges.
+- As an alternative to force-merging segments into a single segment in order to improve performance.
+- Running a search on an index with multiple segments in searchable snapshots.


I think we can remove the last point since second is generic enough and covers all types of indices.

sohami · 2023-09-09T23:21:17Z

_search-plugins/concurrent-segment-search.md

+- `0`: Use the default Lucene mechanism.
+- Positive integer: Use the max target slice count mechanism. Usually, a value 2--8 should be sufficient.
+
+## The `terminate_after` search parameter


May be lets call this section as "Things to Know". We may add more info in this section going forward.

I can generalize later when we add more info. For now, I think it's better to leave this heading because it's more descriptive.

sohami · 2023-09-10T02:14:42Z

_api-reference/nodes-apis/nodes-stats.md

@@ -1072,6 +1072,10 @@ total_rejections_breakup_shadow_mode.throughput_degradation_limits | Integer | T
 enabled | Boolean | Specifies whether the shard indexing pressure feature is turned on for the node.
 enforced | Boolean | If true, the shard indexing pressure runs in enforced mode (there are rejections). If false, the shard indexing pressure runs in shadow mode (there are no rejections, but statistics are recorded and can be retrieved in the `total_rejections_breakup_shadow_mode` object). Only applicable if shard indexing pressure is enabled. 

+## Concurrent segment search
+
+Starting with OpenSearch 2.10, you can perform [concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search/), in which each shard-level request will search the segments in parallel during query phase. If you [enable the concurrent segment search feature flag]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search#enabling-the-feature-flag), the Nodes Stats API response will contain several additional fields with statistics about slices (units of work executed by a thread). For the descriptions of those fields, see [Index Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/stats#concurrent-segment-search).


Can be add experimental somewhere for the feature like If you enable the experimental feature concurrent segment search

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

kolchfa-aws · 2023-09-11T15:14:46Z

@jed326 @ticheng-aws @sohami I've implemented your comments. Could you please review again?

vagimeli

A few comments. Looks good.

_api-reference/index-apis/stats.md

vagimeli · 2023-09-11T16:31:28Z

_api-reference/profile.md

 `profile.shards.searches.rewrite_time` | Integer | All Lucene queries are rewritten. A query and its children may be rewritten more than once, until the query stops changing. The rewriting process involves performing optimizations, such as removing redundant clauses or replacing a query path with a more efficient one. After the rewriting process, the original query may change significantly. The `rewrite_time` field contains the cumulative total rewrite time for the query and all its children, in nanoseconds.
 [`profile.shards.searches.collector`](#the-collector-array) | Array of objects | Profiling information about the Lucene collectors that ran the search.
 [`profile.shards.aggregations`](#aggregations) | Array of objects | Profiling information about the aggregation execution.

-### The `query` object
+### The `query` array

 The `query` object contains the following fields.


Should "object" be changed to "array?"

Yes, thanks!

_api-reference/profile.md

_search-plugins/concurrent-segment-search.md

vagimeli · 2023-09-11T16:46:08Z

_search-plugins/concurrent-segment-search.md

+As an alternative to directly modifying `config/jvm.options`, you can define the properties by using an environment variable. This can be done in a single command when you start OpenSearch or by defining the variable with `export`.
+
+To add these flags in-line when starting OpenSearch, run the following command:
+


Delete extra line?

vagimeli · 2023-09-11T16:46:51Z

_search-plugins/concurrent-segment-search.md

+## Disabling concurrent search at index or cluster level
+
+After you enable the experimental feature flag, all search requests will use concurrent segment search during query phase. To disable concurrent segment search for all indexes, set following dynamic cluster setting:
+


Delete extra line?

vagimeli · 2023-09-11T16:52:41Z

_search-plugins/concurrent-segment-search.md

+
+### The Lucene mechanism
+
+By default, Lucene assigns a maximum of 250 K documents or 5 segments (whichever is met first) to each slice in a shard. For example, consider a shard with 11 segments. The first 5 segments have 250 K documents each and the next 6 segments have 20 K documents each. The first 5 segments will be assigned to one slice each because they each contain the maximum allowed document count for a slice. Then the next 5 segments will all be assigned to another single slice because of the maximum allowed segment count for a slice. The 11th slice will be assigned to a separate slice. 


Does "250 K" mean 250,000? If so, then either write out the number 250,000 or close up the space between numeral and unit of measure (250K). Or are we referring to 250 k documents?

250,000. I'll close the space.

_search-plugins/concurrent-segment-search.md

Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

natebower

@kolchfa-aws Please see my comments and changes and let me know if you have any questions. Thanks!

_api-reference/index-apis/stats.md

natebower · 2023-09-11T17:19:31Z

_api-reference/nodes-apis/nodes-stats.md

@@ -1072,6 +1072,10 @@ total_rejections_breakup_shadow_mode.throughput_degradation_limits | Integer | T
 enabled | Boolean | Specifies whether the shard indexing pressure feature is turned on for the node.
 enforced | Boolean | If true, the shard indexing pressure runs in enforced mode (there are rejections). If false, the shard indexing pressure runs in shadow mode (there are no rejections, but statistics are recorded and can be retrieved in the `total_rejections_breakup_shadow_mode` object). Only applicable if shard indexing pressure is enabled. 

+## Concurrent segment search
+
+Starting with OpenSearch 2.10, you can perform [concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search/), in which each shard-level request will search the segments in parallel during query phase. If you [enable the experimental concurrent segment search feature flag]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search#enabling-the-feature-flag), the Nodes Stats API response will contain several additional fields with statistics about slices (units of work executed by a thread). For the descriptions of those fields, see [Index Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/stats#concurrent-segment-search).


Please apply edits from previous text to this para.

natebower · 2023-09-11T17:20:14Z

_api-reference/profile.md

+## Concurrent segment search
+
+Starting with OpenSearch 2.10, you can perform [concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search/), in which each shard-level request will search the segments in parallel during query phase. If you enable the experimental concurrent segment search feature flag, the Profile API response will contain several additional fields with statistics about _slices_.


Apply previous edits.

_api-reference/profile.md

natebower · 2023-09-11T17:48:49Z

_search-plugins/concurrent-segment-search.md

+
+## API changes
+
+If you enable the concurrent segment search feature flag, the following stats API responses will contain several additional fields with statistics about slices:


Should "Stats" be capitalized?

_search-plugins/concurrent-segment-search.md

natebower · 2023-09-11T17:51:25Z

_search-plugins/concurrent-segment-search.md

+
+For the descriptions of the added fields, see [Index Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/stats#concurrent-segment-search).
+
+Additionally, for the [Profile API], some response fields will be modified and others added. For more information, see the [concurrent segment search section of the Profile API]({{site.url}}{{site.baseurl}}/api-reference/profile/).


"of the Profile API documentation"? Missing link.

_search-plugins/concurrent-segment-search.md

Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add concurrent segment search documentation Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add API information Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Small rewording Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add tech review feedback Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fix link Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add API section Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Small rewriting Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Rewriting Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Tech review feedback Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Apply suggestions from code review Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update profile.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _api-reference/profile.md Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update concurrent-segment-search.md Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Implemented editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> --------- Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Co-authored-by: Nathan Bower <nbower@amazon.com>

Add concurrent segment search documentation

464e722

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

kolchfa-aws self-assigned this Sep 7, 2023

kolchfa-aws requested review from cwillum, hdhalter, Naarcha-AWS, vagimeli, ananzh, seanneumann, AMoo-Miki and natebower as code owners September 7, 2023 23:35

kolchfa-aws added v2.10.0 release-notes PR: Include this PR in the automated release notes labels Sep 7, 2023

kolchfa-aws added 2 commits September 8, 2023 12:58

Add API information

35d0ad7

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

Small rewording

82c9117

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

jed326 reviewed Sep 8, 2023

View reviewed changes

ticheng-aws reviewed Sep 8, 2023

View reviewed changes

Add tech review feedback

ccf3450

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

kolchfa-aws added 4 commits September 8, 2023 14:45

Fix link

a88cb42

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

Add API section

0c07fd0

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

Small rewriting

32d2671

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

Rewriting

a491397

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

hdhalter added the 3 - Tech review PR: Tech review in progress label Sep 8, 2023

jed326 reviewed Sep 8, 2023

View reviewed changes

sohami reviewed Sep 10, 2023

View reviewed changes

Tech review feedback

0318ab3

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

ticheng-aws approved these changes Sep 11, 2023

View reviewed changes

kolchfa-aws removed the 3 - Tech review PR: Tech review in progress label Sep 11, 2023

kolchfa-aws added the 4 - Doc review PR: Doc review in progress label Sep 11, 2023

vagimeli approved these changes Sep 11, 2023

View reviewed changes

jed326 approved these changes Sep 11, 2023

View reviewed changes

kolchfa-aws and others added 4 commits September 11, 2023 13:09

Apply suggestions from code review

5f7add8

Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Update profile.md

b6e7b0a

Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Update _api-reference/profile.md

034377f

Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Update concurrent-segment-search.md

de5a5a9

Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

kolchfa-aws mentioned this pull request Sep 11, 2023

[DOC] Concurrent Segment Search support in OpenSearch #3662

Closed

4 tasks

natebower reviewed Sep 11, 2023

View reviewed changes

kolchfa-aws and others added 2 commits September 11, 2023 14:04

Apply suggestions from code review

4d3f5ec

Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Implemented editorial comments

e0672d6

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

kolchfa-aws added 6 - Done but waiting to merge PR: The work is done and ready to merge and removed 4 - Doc review PR: Doc review in progress labels Sep 11, 2023

sohami approved these changes Sep 14, 2023

View reviewed changes

kolchfa-aws merged commit cab5e40 into main Sep 22, 2023
5 checks passed

kolchfa-aws added the experimental label Sep 25, 2023

Naarcha-AWS deleted the concurrent-segment branch March 28, 2024 23:22

		## Concurrent segment search

		Starting with OpenSearch 2.10, you can perform [concurrent segment search](search-plugins/concurrent-segment-search/), in which each shard-level request will search the segments in parallel during query phase. If you enable concurrent segment search, the Index Stats API response will contain several additional fields with statistics about slices (units of work executed by a thread). For more information about slices, see [Concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search#searching-segments-concurrently).

		The following sections contain definitions of all modified or added response fields for concurrent segment search.

		#### The `query` object

		#### Example response

		The following is an example response for a concurrent search with three segment slices:

		## Concurrent segment search mechanisms

		You can choose one of the two available concurrent segment mechanisms: the default [Lucene mechanism](#the-lucene-mechanism) or the [max slice count mechanism](#the-max-slice-count-mechanism).


		### The Lucene mechanism

		By default, Lucene assigns a maximum of 250 K documents or 5 segments (whichever is met first) to each slice in a shard. For example, consider a shard with 11 segments. The first 5 segments have 250 K documents each and the next 6 segments have 20 K documents each. The first 5 segments will be assigned to one slice each because they each contain the maximum allowed document count for a slice. Then the next 5 segments will all be assigned to another slice because of the maximum allowed segment count for a slice. The 11th slice will be assigned to a separate slice.


		## The `terminate_after` search parameter

		The [`terminate_after` search parameter]({{site.url}}{{site.baseurl}}/api-reference/search/#url-parameters) is used to terminate a search request once a specified number of docs has been collected. In the non-concurrent search workflow, this count is evaluated at each shard, however for the concurrent search workflow this will be evaluated at each leaf slice instead to avoid synchronizing document counts between threads. Functionally there should be no difference, however in the concurrent search case the request may perform slightly more work than expected because of each segment slice on the shard collecting up to the specified number of docs.


		## Searching segments concurrently

		Without concurrent segment search, Lucene executes a request sequentially across all segments on each shard during query phase. The query phase then collects the top hits for the search request. With concurrent segment search, each shard-level request will search the segments in parallel during query phase. For each shard, the segments are divided into multiple work units called _slices_. Each _slice_ is the unit of work which can be executed in parallel on a separate thread, thus the slice count determines the maximum degree of parallelism for a shard-level request. Once all the slices complete their work, Lucene performs a reduce operation on the slices, merging them and creating the final result for this shard-level request. Slices are executed using a new `index_searcher` thread pool, which is different from the `search` thread pool that handles shard-level requests.

		As an alternative to directly modifying `config/jvm.options`, you can define the properties by using an environment variable. This can be done in a single command when you start OpenSearch or by defining the variable with `export`.

		To add these flags in-line when starting OpenSearch, run the following command:

		## Disabling concurrent search at index or cluster level

		After you enable the experimental feature flag, all search requests will use concurrent segment search during query phase. To disable concurrent segment search for all indexes, set following dynamic cluster setting:


		## API changes

		If you enable the concurrent segment search feature flag, the following stats API responses will contain several additional fields with statistics about slices:


		For the descriptions of the added fields, see [Index Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/stats#concurrent-segment-search).

		Additionally, for the [Profile API], some response fields will be modified and others added. For more information, see the [concurrent segment search section of the Profile API]({{site.url}}{{site.baseurl}}/api-reference/profile/).

Add concurrent segment search documentation #4990

Add concurrent segment search documentation #4990

Conversation

kolchfa-aws commented Sep 7, 2023

Checklist

kolchfa-aws commented Sep 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kolchfa-aws commented Sep 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kolchfa-aws commented Sep 11, 2023

vagimeli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

natebower left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment