The index.number_of_replicas setting controls how many replica copies Elasticsearch maintains for each primary shard of an index. It defaults to 1, meaning one replica per primary, and is a dynamic setting - you can change it on a running index without closing it. Replicas serve two purposes: they keep the index available when a node fails, and they allow search load to be spread across more shards. Unlike `number_of_shards`, which is fixed at index creation, you can dial replicas up or down on the fly through the update settings API.
Definition
index.number_of_replicas is a dynamic index-level integer setting. For every primary shard in the index, Elasticsearch maintains this many replica shards. Total shards = number_of_primaries x (1 + number_of_replicas). Replicas are placed on different nodes than their primary (by default; cluster.routing.allocation.same_shard.host can change this). With number_of_replicas: 0 the index has no redundancy and any node loss makes affected shards unavailable until recovered.
Default and Range
| Property | Value |
|---|---|
| Default | 1 |
| Type | Non-negative integer, dynamic index setting |
| Scope | Per index (or via index template for new indices) |
| Allowed minimum | 0 (no redundancy) |
| Practical maximum | Bounded by data node count - 1 (replicas cannot share a node with their primary) |
A 3-data-node cluster can support number_of_replicas: 2 (1 primary + 2 replicas across 3 nodes). With only 2 data nodes, number_of_replicas: 2 leaves one replica permanently unassigned and the cluster yellow.
How to Change It
At index creation:
PUT /my-index
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 1
}
}
On an existing index (dynamic, no close required):
PUT /my-index/_settings
{
"index.number_of_replicas": 2
}
Apply across many indices with a wildcard:
PUT /logs-*/_settings
{
"index.number_of_replicas": 1
}
Or set the default for new indices via an index template:
PUT /_index_template/logs-template
{
"index_patterns": ["logs-*"],
"template": {
"settings": { "number_of_replicas": 1 }
}
}
Verify current values:
GET /my-index/_settings?filter_path=*.settings.index.number_of_replicas
Choosing the Right Value
The right replica count is a function of cluster size, criticality of the data, and read load:
| Scenario | Recommended replicas |
|---|---|
| Single-node dev cluster | 0 (anything else leaves the cluster yellow) |
| Production, 3+ data nodes, standard data | 1 (default; survives one node loss) |
| Critical data, 4+ data nodes | 2 (survives two node losses) |
| Read-heavy workload, plenty of nodes | 2-3 to spread search load |
| Bulk-loading a new index | 0 during load, then raise after - avoids replicating every write twice |
Operational Impact
Each replica is a full copy. Doubling replicas doubles the storage used and adds proportional indexing CPU and disk I/O, because every write goes to the primary and replicates synchronously to every replica before acknowledgement. Indexing throughput drops as replica count rises. Search throughput, by contrast, scales roughly linearly with replica count up to the limit of the cluster's CPU.
The bulk-load pattern is worth knowing:
# Before bulk load: drop to 0 replicas
PUT /target-index/_settings { "index.number_of_replicas": 0, "index.refresh_interval": "-1" }
# ... run bulk load ...
# Restore after
PUT /target-index/_settings { "index.number_of_replicas": 1, "index.refresh_interval": "1s" }
POST /target-index/_forcemerge?max_num_segments=1
This can cut bulk-load time by 30-50% on large indices. It comes at the cost of zero redundancy during the load - if a node fails mid-load, you re-run the load.
Common Mistakes
- Replicas higher than data-node count - 1. Replicas need a node distinct from the primary. Setting
number_of_replicas: 2on a 2-node cluster permanently leaves one replica unassigned and the cluster yellow. - Running
number_of_replicas: 0in production. No redundancy. A single node failure stops writes to affected indices. - Forgetting to raise replicas after a bulk-load. Indices stay at 0 replicas indefinitely, leaving production exposed.
- Changing replicas during a disk-pressure event. Adding replicas doubles disk usage and can push nodes past the high watermark, making the situation worse.
- Confusing replicas with shard copies.
number_of_replicas: 1means one replica per primary, so 2 total copies of every shard - not 1 copy.
Frequently Asked Questions
Q: What is the default value of index.number_of_replicas in Elasticsearch?
A: The default is 1. Every primary shard gets one replica copy, so the index has 2 total copies of every shard. This requires at least 2 data nodes to be fully assigned.
Q: Can I change index.number_of_replicas on a running Elasticsearch index?
A: Yes. index.number_of_replicas is a dynamic setting. Use PUT /<index>/_settings and the change applies immediately. New replicas allocate and rebuild from the primaries; reducing replica count is essentially instant.
Q: How many replicas should I set in Elasticsearch?
A: For most production workloads with 3+ data nodes, 1 replica is the right default. Use 2 for critical data on 4+ nodes or to spread heavy read load. Use 0 only on single-node dev clusters or during bulk loads where you accept the loss-of-redundancy risk.
Q: What happens when number_of_replicas exceeds the available data nodes?
A: The extra replicas cannot allocate (because they would have to share a node with the primary, which the allocator forbids by default). The unassigned replicas leave the cluster in yellow state until enough nodes are added or the replica count is reduced.
Q: Does index.number_of_replicas affect indexing performance?
A: Yes. Every write goes synchronously to the primary and all replicas before being acknowledged. Doubling replicas roughly doubles the per-document write cost. For bulk-loading, temporarily set replicas to 0 and raise afterwards.
Q: How is number_of_replicas different from number_of_shards?
A: number_of_shards is the primary count; it is fixed at index creation and can only be changed via reindex, shrink, or split. number_of_replicas is the per-primary replica count; it is dynamic and can be changed at any time.
