[DOC] Document force_merge API (and new only_expunge_deletes behavior in 2.12)

[msfroh]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request.
Relates to opensearch-project/OpenSearch#10603, which doesn't change any APIs but does change existing behavior.

I don't believe we currently have any documentation around the force_merge API. We do have https://opensearch.org/docs/latest/dashboards/im-dashboards/forcemerge/, but that's just a UI component to simplify access to the force_merge API. I think we should have a section for force_merge under https://opensearch.org/docs/latest/api-reference/index-apis/index/.

Anyway, this Stackoverflow question (https://stackoverflow.com/questions/55903641/is-it-ok-to-forcemerge-with-only-expunge-deletes-on-a-read-write-index) from 2019 essentially covers the problem solved by opensearch-project/OpenSearch#10603.

Essentially, under normal circumstances, OpenSearch will do background segment merges that produce segments with size at most index.merge.policy.max_merged_segment (default 5GB). When you force merge, that max segment size is ignored -- every shard could potentially get merged down to a single segment, regardless of size. The problem is that you now have segments bigger than 5GB that may accumulate deleted documents. Those segments cannot possibly participate in any future merges unless the total deletion count would bring them back under 5GB.

Given that there's a parameter called only_expunge_deletes, it's not unreasonable that some people (including me -- I've been burned by this) would think that it's safe to use that parameter to force a merge that only expunges deletes (without producing giant zombie segments that never participate in future merges). Unfortunately, until now, those people would have been wrong.

This change makes it so that only_expunge_deletes will still honor the value of index.merge.policy.max_merged_segment.

What other resources are available?
N/A

[hdhalter]

@msfroh - This doesn't look like it's tied to 2.12. Can we take care of this now since it is already merged? Otherwise, please point us to the 2.12 dev PR that fixes the problem.

[msfroh]

@msfroh - This doesn't look like it's tied to 2.12. Can we take care of this now since it is already merged? Otherwise, please point us to the 2.12 dev PR that fixes the problem.

Sorry -- I forgot to label the PR with 2.12. It didn't make it into 2.11 since I forgot to backport it before the 2.11 cutoff, but it's now in 2.x and should go out in 2.12.

To clarify:

• The force_merge API has been around forever, long before the fork -- going back to at least Elasticsearch 2.1. That can be documented whenever we want.
• The change to the only_expunge_deletes behavior will go into 2.12.