› › ›

Force merge

Phases allowed: hot, warm.

Force merges the index into the specified maximum number of segments.

Shards that are relocating during a forcemerge will not be merged.

To use the forcemerge action in the hot phase, the rollover action must be present. If no rollover action is configured, ILM will reject the policy.

Performance considerations

Force merge is a resource-intensive operation. If too many force merges are triggered at once, it can negatively impact your cluster. This can happen when you apply an ILM policy that includes a force merge action to existing indices. If they meet the min_age criteria, they can immediately proceed through multiple phases. You can prevent this by increasing the min_age or setting index.lifecycle.origination_date to change how the index age is calculated.

If you experience a force merge task queue backlog, you might need to increase the size of the force merge threadpool so indices can be force merged in parallel. To do this, configure the thread_pool.force_merge.size cluster setting.

This can have cascading performance impacts. Monitor cluster performance and increment the size of the thread pool slowly to reduce the backlog.

Force merging will be performed by the nodes within the current phase of the index. A forcemerge in the hot phase will use hot nodes with potentially faster nodes, while impacting ingestion more. A forcemerge in the warm phase will use warm nodes and potentially take longer to perform, but without impacting ingestion in the hot tier.

Options

max_num_segments: (Required, integer) Number of segments to merge to. To fully merge the index, set to 1.
index_codec: (Optional, string) Codec used to compress the document store. The only accepted value is best_compression, which uses ZSTD for a higher compression ratio but slower stored fields performance. To use the default LZ4 codec, omit this argument.

If using best_compression, ILM will close and then re-open the index prior to the force merge. While closed, the index will be unavailable for read or write operations.

Example

resp = client.ilm.put_lifecycle(
    name="my_policy",
    policy={
        "phases": {
            "warm": {
                "actions": {
                    "forcemerge": {
                        "max_num_segments": 1
                    }
                }
            }
        }
    },
)
print(resp)

response = client.ilm.put_lifecycle(
  policy: 'my_policy',
  body: {
    policy: {
      phases: {
        warm: {
          actions: {
            forcemerge: {
              max_num_segments: 1
            }
          }
        }
      }
    }
  }
)
puts response

const response = await client.ilm.putLifecycle({
  name: "my_policy",
  policy: {
    phases: {
      warm: {
        actions: {
          forcemerge: {
            max_num_segments: 1,
          },
        },
      },
    },
  },
});
console.log(response);

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "forcemerge" : {
            "max_num_segments": 1
          }
        }
      }
    }
  }
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/ilm-forcemerge.html