How to Change Number of Replicas in Elasticsearch

To change the number of replicas in Elasticsearch, use the _settings API with the number_of_replicas parameter. For example, send a PUT request to /{index}/_settings with the new replica count in the JSON body.

Syntax

Use the PUT /{index}/_settings API to update the number of replicas. Replace {index} with your index name. In the request body, set number_of_replicas to the desired number.

• PUT: HTTP method to update settings
• /{index}/_settings: URL path targeting the index settings
• number_of_replicas: The new replica count (integer)

json

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

Example

This example changes the number of replicas for an index named my-index to 2. It uses a PUT request with JSON body specifying the new replica count.

json

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

Output

{
  "acknowledged": true
}

Common Pitfalls

Common mistakes when changing replicas include:

• Trying to change replicas on a closed index (index must be open).
• Using incorrect JSON structure or missing the index key in the body.
• Not waiting for cluster health to be green after changing replicas.

Always check cluster health and index status before and after the change.

json

### Wrong way (missing 'index' key):
PUT /my-index/_settings
{
  "number_of_replicas": 2
}

### Right way:
PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

Quick Reference

Action	API Endpoint	Description
Check current replicas	GET /my-index/_settings	View current number_of_replicas setting
Change replicas	PUT /my-index/_settings	Update number_of_replicas in request body
Check cluster health	GET /_cluster/health	Ensure cluster is green after change

Key Takeaways

Use the PUT /{index}/_settings API with the number_of_replicas parameter to change replicas.

Always include the 'index' key in the JSON body when updating settings.

Ensure the index is open before changing replicas.

Check cluster health after updating replicas to confirm changes applied successfully.