Skip to content

Commit 9ddd588

Browse files
jrodewigjrodewig
authored
[DOCS] Reformat force merge API docs (#46685)
1 parent 084d8d8 commit 9ddd588

File tree

1 file changed

+134
-50
lines changed

1 file changed

+134
-50
lines changed

‎docs/reference/indices/forcemerge.asciidoc‎

Lines changed: 134 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,30 @@
11
[[indices-forcemerge]]
2-
=== Force Merge
2+
=== Force merge API
3+
++++
4+
<titleabbrev>Force merge</titleabbrev>
5+
++++
36

4-
The force merge API allows you to force a <<index-modules-merge,merge>> on the
7+
Forces a <<index-modules-merge,merge>> on the shards of one or more indices.
8+
9+
[source,console]
10+
----
11+
POST /twitter/_forcemerge
12+
----
13+
// TEST[setup:twitter]
14+
15+
16+
[[forcemerge-api-request]]
17+
==== {api-request-title}
18+
19+
`POST /<index>/_forcemerge`
20+
21+
`POST /_forcemerge`
22+
23+
24+
[[forcemerge-api-desc]]
25+
==== {api-description-title}
26+
27+
Use the force merge API to force a <<index-modules-merge,merge>> on the
528
shards of one or more indices. Merging reduces the number of segments in each
629
shard by merging some of them together, and also frees up the space used by
730
deleted documents. Merging normally happens automatically, but sometimes it is
@@ -15,74 +38,135 @@ mostly consist of deleted documents. This can cause very large segments to
1538
remain in the index which can result in increased disk usage and worse search
1639
performance.
1740

41+
42+
[[forcemerge-blocks]]
43+
===== Blocks during a force merge
44+
1845
Calls to this API block until the merge is complete. If the client connection
1946
is lost before completion then the force merge process will continue in the
2047
background. Any new requests to force merge the same indices will also block
2148
until the ongoing force merge is complete.
2249

23-
[source,console]
24-
--------------------------------------------------
25-
POST /twitter/_forcemerge
26-
--------------------------------------------------
27-
// TEST[setup:twitter]
2850

29-
Force-merging can be useful with time-based indices and when using
30-
<<indices-rollover-index,rollover>>. In these cases each index only receives
31-
indexing traffic for a certain period of time, and once an index will receive
32-
no more writes its shards can be force-merged down to a single segment:
51+
[[forcemerge-multi-index]]
52+
===== Force merging multiple indices
3353

34-
[source,console]
35-
--------------------------------------------------
36-
POST /logs-000001/_forcemerge?max_num_segments=1
37-
--------------------------------------------------
38-
// TEST[setup:twitter]
39-
// TEST[s/logs-000001/twitter/]
54+
The force merge API can be applied to more than one index with a single call, or
55+
even on `_all` the indices. Multi index operations are executed one shard at a
56+
time per node. Force merge makes the storage for the shard being merged
57+
temporarily increase, up to double its size in case `max_num_segments` parameter
58+
is set to `1`, as all segments need to be rewritten into a new one.
4059

41-
This can be a good idea because single-segment shards can sometimes use simpler
42-
and more efficient data structures to perform searches.
4360

44-
[float]
45-
[[forcemerge-parameters]]
46-
==== Request Parameters
61+
[[forcemerge-api-path-params]]
62+
==== {api-path-parms-title}
4763

48-
The force merge API accepts the following request parameters:
64+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
65+
+
66+
To force merge all indices in the cluster,
67+
omit this parameter
68+
or use a value of `_all` or `*`.
4969

50-
[horizontal]
51-
`max_num_segments`:: The number of segments to merge to. To fully
52-
merge the index, set it to `1`. Defaults to simply checking if a
53-
merge needs to execute, and if so, executes it.
5470

55-
`only_expunge_deletes`:: Should the merge process only expunge segments with
56-
deletes in it. In Lucene, a document is not deleted from a segment, just marked
57-
as deleted. During a merge process of segments, a new segment is created that
58-
does not have those deletes. This flag allows to only merge segments that have
59-
deletes. Defaults to `false`. Note that this won't override the
60-
`index.merge.policy.expunge_deletes_allowed` threshold.
71+
[[forcemerge-api-query-params]]
72+
==== {api-query-parms-title}
6173

62-
`flush`:: Should a flush be performed after the forced merge. Defaults to
63-
`true`.
74+
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
6475

65-
[source,console]
66-
--------------------------------------------------
67-
POST /kimchy/_forcemerge?only_expunge_deletes=false&max_num_segments=100&flush=true
68-
--------------------------------------------------
69-
// TEST[s/^/PUT kimchy\n/]
76+
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
77+
+
78+
Defaults to `open`.
7079

71-
[float]
72-
[[forcemerge-multi-index]]
73-
==== Multi Index
80+
`flush`::
81+
(Optional, boolean)
82+
If `true`,
83+
{es} performs a <<indices-flush,flush>> on the indices
84+
after the force merge.
85+
Defaults to `true`.
86+
87+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
88+
89+
`max_num_segments`::
90+
+
91+
--
92+
(Optional, integer)
93+
The number of segments to merge to.
94+
To fully merge the index,
95+
set it to `1`.
96+
97+
Defaults to checking if a merge needs to execute.
98+
If so, executes it.
99+
--
100+
101+
`only_expunge_deletes`::
102+
+
103+
--
104+
(Optional, boolean)
105+
If `true`,
106+
only expunge segments containing document deletions.
107+
Defaults to `false`.
108+
109+
In Lucene,
110+
a document is not deleted from a segment;
111+
just marked as deleted.
112+
During a merge,
113+
a new segment is created
114+
that does not contain those document deletions.
115+
116+
NOTE: This parameter does *not* override the
117+
`index.merge.policy.expunge_deletes_allowed` setting.
118+
--
74119

75-
The force merge API can be applied to more than one index with a single call, or
76-
even on `_all` the indices. Multi index operations are executed one shard at a
77-
time per node. Force merge makes the storage for the shard being merged
78-
temporarily increase, up to double its size in case `max_num_segments` is set
79-
to `1`, as all segments need to be rewritten into a new one.
80120

121+
[[forcemerge-api-example]]
122+
==== {api-examples-title}
123+
124+
125+
[[forcemerge-api-specific-ex]]
126+
===== Force merge a specific index
81127

82128
[source,console]
83-
--------------------------------------------------
129+
----
130+
POST /twitter/_forcemerge
131+
----
132+
// TEST[continued]
133+
134+
135+
[[forcemerge-api-multiple-ex]]
136+
===== Force merge several indices
137+
138+
[source,console]
139+
----
84140
POST /kimchy,elasticsearch/_forcemerge
141+
----
142+
// TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
143+
144+
145+
[[forcemerge-api-all-ex]]
146+
===== Force merge all indices
85147

148+
[source,console]
149+
----
86150
POST /_forcemerge
151+
----
152+
153+
154+
[[forcemerge-api-time-based-index-ex]]
155+
===== Time-based indices
156+
157+
Force-merging is useful for time-based indices,
158+
particularly when using <<indices-rollover-index,rollover>>.
159+
In these cases,
160+
each index only receives indexing traffic for a certain period of time.
161+
Once an index receive no more writes,
162+
its shards can be force-merged to a single segment.
163+
164+
[source,console]
87165
--------------------------------------------------
88-
// TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
166+
POST /logs-000001/_forcemerge?max_num_segments=1
167+
--------------------------------------------------
168+
// TEST[setup:twitter]
169+
// TEST[s/logs-000001/twitter/]
170+
171+
This can be a good idea because single-segment shards can sometimes use simpler
172+
and more efficient data structures to perform searches.

0 commit comments

Comments
 (0)