186 lines
4.9 KiB
Plaintext
186 lines
4.9 KiB
Plaintext
[[indices-forcemerge]]
|
|
=== Force merge API
|
|
++++
|
|
<titleabbrev>Force merge</titleabbrev>
|
|
++++
|
|
|
|
Forces a <<index-modules-merge,merge>> on the shards of one or more indices.
|
|
For data streams, the API forces a merge on the shards of the stream's backing
|
|
indices.
|
|
|
|
[source,console]
|
|
----
|
|
POST /my-index-000001/_forcemerge
|
|
----
|
|
// TEST[setup:my_index]
|
|
|
|
|
|
[[forcemerge-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /<target>/_forcemerge`
|
|
|
|
`POST /_forcemerge`
|
|
|
|
|
|
[[forcemerge-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
Use the force merge API to force a <<index-modules-merge,merge>> on the
|
|
shards of one or more indices. Merging reduces the number of segments in each
|
|
shard by merging some of them together, and also frees up the space used by
|
|
deleted documents. Merging normally happens automatically, but sometimes it is
|
|
useful to trigger a merge manually.
|
|
|
|
WARNING: **Force merge should only be called against an index after you have
|
|
finished writing to it.** Force merge can cause very large (>5GB) segments to
|
|
be produced, and if you continue to write to such an index then the automatic
|
|
merge policy will never consider these segments for future merges until they
|
|
mostly consist of deleted documents. This can cause very large segments to
|
|
remain in the index which can result in increased disk usage and worse search
|
|
performance.
|
|
|
|
|
|
[[forcemerge-blocks]]
|
|
===== Blocks during a force merge
|
|
|
|
Calls to this API block until the merge is complete. If the client connection
|
|
is lost before completion then the force merge process will continue in the
|
|
background. Any new requests to force merge the same indices will also block
|
|
until the ongoing force merge is complete.
|
|
|
|
|
|
[[forcemerge-multi-index]]
|
|
===== Force merging multiple indices
|
|
|
|
You can force merge multiple indices with a single request by targeting:
|
|
|
|
* One or more data streams that contain multiple backing indices
|
|
* Multiple indices
|
|
* One or more index aliases that point to multiple indices
|
|
* All data streams and indices in a cluster
|
|
|
|
Multi-index operations are executed one shard at a
|
|
time per node. Force merge makes the storage for the shard being merged
|
|
temporarily increase, up to double its size in case `max_num_segments` parameter
|
|
is set to `1`, as all segments need to be rewritten into a new one.
|
|
|
|
|
|
[[forcemerge-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Optional, string)
|
|
Comma-separated list of data streams, indices, and index aliases used to limit
|
|
the request. Wildcard expressions (`*`) are supported.
|
|
+
|
|
To target all data streams and indices in a cluster, omit this parameter or use
|
|
`_all` or `*`.
|
|
|
|
|
|
[[forcemerge-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
|
+
|
|
Defaults to `true`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
|
+
|
|
Defaults to `open`.
|
|
|
|
`flush`::
|
|
(Optional, boolean)
|
|
If `true`,
|
|
{es} performs a <<indices-flush,flush>> on the indices
|
|
after the force merge.
|
|
Defaults to `true`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
|
|
|
`max_num_segments`::
|
|
+
|
|
--
|
|
(Optional, integer)
|
|
The number of segments to merge to.
|
|
To fully merge indices,
|
|
set it to `1`.
|
|
|
|
Defaults to checking if a merge needs to execute.
|
|
If so, executes it.
|
|
--
|
|
|
|
`only_expunge_deletes`::
|
|
+
|
|
--
|
|
(Optional, boolean)
|
|
If `true`,
|
|
only expunge segments containing document deletions.
|
|
Defaults to `false`.
|
|
|
|
In Lucene,
|
|
a document is not deleted from a segment;
|
|
just marked as deleted.
|
|
During a merge,
|
|
a new segment is created
|
|
that does not contain those document deletions.
|
|
|
|
NOTE: This parameter does *not* override the
|
|
`index.merge.policy.expunge_deletes_allowed` setting.
|
|
--
|
|
|
|
|
|
[[forcemerge-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
|
|
[[forcemerge-api-specific-ex]]
|
|
===== Force merge a specific data stream or index
|
|
|
|
[source,console]
|
|
----
|
|
POST /my-index-000001/_forcemerge
|
|
----
|
|
// TEST[continued]
|
|
|
|
|
|
[[forcemerge-api-multiple-ex]]
|
|
===== Force merge several data streams or indices
|
|
|
|
[source,console]
|
|
----
|
|
POST /my-index-000001,my-index-000002/_forcemerge
|
|
----
|
|
// TEST[s/^/PUT my-index-000001\nPUT my-index-000002\n/]
|
|
|
|
|
|
[[forcemerge-api-all-ex]]
|
|
===== Force merge all indices
|
|
|
|
[source,console]
|
|
----
|
|
POST /_forcemerge
|
|
----
|
|
|
|
|
|
[[forcemerge-api-time-based-index-ex]]
|
|
===== Data streams and time-based indices
|
|
|
|
Force-merging is useful for managing a data stream's older backing indices and
|
|
other time-based indices, particularly after a
|
|
<<indices-rollover-index,rollover>>.
|
|
In these cases,
|
|
each index only receives indexing traffic for a certain period of time.
|
|
Once an index receive no more writes,
|
|
its shards can be force-merged to a single segment.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /.ds-logs-000001/_forcemerge?max_num_segments=1
|
|
--------------------------------------------------
|
|
// TEST[setup:my_index]
|
|
// TEST[s/.ds-logs-000001/my-index-000001/]
|
|
|
|
This can be a good idea because single-segment shards can sometimes use simpler
|
|
and more efficient data structures to perform searches.
|