Skip to content

Commit 628c068

Browse files
jrodewigjrodewig
committed
[DOCS] Reformat force merge API docs (#46685)
1 parent df7196c commit 628c068

File tree

1 file changed

+137
-52
lines changed

1 file changed

+137
-52
lines changed

‎docs/reference/indices/forcemerge.asciidoc‎

Lines changed: 137 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,31 @@
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,js]
10+
----
11+
POST /twitter/_forcemerge
12+
----
13+
// CONSOLE
14+
// TEST[setup:twitter]
15+
16+
17+
[[forcemerge-api-request]]
18+
==== {api-request-title}
19+
20+
`POST /<index>/_forcemerge`
21+
22+
`POST /_forcemerge`
23+
24+
25+
[[forcemerge-api-desc]]
26+
==== {api-description-title}
27+
28+
Use the force merge API to force a <<index-modules-merge,merge>> on the
529
shards of one or more indices. Merging reduces the number of segments in each
630
shard by merging some of them together, and also frees up the space used by
731
deleted documents. Merging normally happens automatically, but sometimes it is
@@ -15,78 +39,139 @@ mostly consist of deleted documents. This can cause very large segments to
1539
remain in the index which can result in increased disk usage and worse search
1640
performance.
1741

42+
43+
[[forcemerge-blocks]]
44+
===== Blocks during a force merge
45+
1846
Calls to this API block until the merge is complete. If the client connection
1947
is lost before completion then the force merge process will continue in the
2048
background. Any new requests to force merge the same indices will also block
2149
until the ongoing force merge is complete.
2250

23-
[source,js]
24-
--------------------------------------------------
25-
POST /twitter/_forcemerge
26-
--------------------------------------------------
27-
// CONSOLE
28-
// TEST[setup:twitter]
2951

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

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

43-
This can be a good idea because single-segment shards can sometimes use simpler
44-
and more efficient data structures to perform searches.
4561

46-
[float]
47-
[[forcemerge-parameters]]
48-
==== Request Parameters
62+
[[forcemerge-api-path-params]]
63+
==== {api-path-parms-title}
64+
65+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
66+
+
67+
To force merge all indices in the cluster,
68+
omit this parameter
69+
or use a value of `_all` or `*`.
70+
71+
72+
[[forcemerge-api-query-params]]
73+
==== {api-query-parms-title}
74+
75+
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
4976

50-
The force merge API accepts the following request parameters:
77+
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
78+
+
79+
Defaults to `open`.
5180

52-
[horizontal]
53-
`max_num_segments`:: The number of segments to merge to. To fully
54-
merge the index, set it to `1`. Defaults to simply checking if a
55-
merge needs to execute, and if so, executes it.
81+
`flush`::
82+
(Optional, boolean)
83+
If `true`,
84+
{es} performs a <<indices-flush,flush>> on the indices
85+
after the force merge.
86+
Defaults to `true`.
5687

57-
`only_expunge_deletes`:: Should the merge process only expunge segments with
58-
deletes in it. In Lucene, a document is not deleted from a segment, just marked
59-
as deleted. During a merge process of segments, a new segment is created that
60-
does not have those deletes. This flag allows to only merge segments that have
61-
deletes. Defaults to `false`. Note that this won't override the
62-
`index.merge.policy.expunge_deletes_allowed` threshold.
88+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
6389

64-
`flush`:: Should a flush be performed after the forced merge. Defaults to
65-
`true`.
90+
`max_num_segments`::
91+
+
92+
--
93+
(Optional, integer)
94+
The number of segments to merge to.
95+
To fully merge the index,
96+
set it to `1`.
97+
98+
Defaults to checking if a merge needs to execute.
99+
If so, executes it.
100+
--
101+
102+
`only_expunge_deletes`::
103+
+
104+
--
105+
(Optional, boolean)
106+
If `true`,
107+
only expunge segments containing document deletions.
108+
Defaults to `false`.
109+
110+
In Lucene,
111+
a document is not deleted from a segment;
112+
just marked as deleted.
113+
During a merge,
114+
a new segment is created
115+
that does not contain those document deletions.
116+
117+
NOTE: This parameter does *not* override the
118+
`index.merge.policy.expunge_deletes_allowed` setting.
119+
--
120+
121+
122+
[[forcemerge-api-example]]
123+
==== {api-examples-title}
124+
125+
126+
[[forcemerge-api-specific-ex]]
127+
===== Force merge a specific index
66128

67129
[source,js]
68-
--------------------------------------------------
69-
POST /kimchy/_forcemerge?only_expunge_deletes=false&max_num_segments=100&flush=true
70-
--------------------------------------------------
130+
----
131+
POST /twitter/_forcemerge
132+
----
71133
// CONSOLE
72-
// TEST[s/^/PUT kimchy\n/]
134+
// TEST[continued]
73135

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

137+
[[forcemerge-api-multiple-ex]]
138+
===== Force merge several indices
84139

85140
[source,js]
86-
--------------------------------------------------
141+
----
87142
POST /kimchy,elasticsearch/_forcemerge
143+
----
144+
// CONSOLE
145+
// TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
146+
147+
148+
[[forcemerge-api-all-ex]]
149+
===== Force merge all indices
88150

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

0 commit comments

Comments
 (0)