How to update index settings in Elasticsearch

Updating index settings in Elasticsearch changes how an existing index refreshes, allocates replicas, or stores new segments without rebuilding that index from scratch. That is useful when indexing throughput needs to improve during a bulk load, replica counts need to match current cluster capacity, or a storage-oriented setting must change after the index is already in use.

The /_settings API manages per-index values such as index.number_of_replicas, index.refresh_interval, and index.codec. Dynamic settings apply immediately to open indices, while current releases can temporarily close and reopen targeted indices with reopen=true to apply many non-dynamic settings. Assigning null removes an explicit override and returns that setting to the default behavior.

Secured clusters need HTTPS, authentication, and a role with index manage privilege for update calls. Increasing replicas can leave shards UNASSIGNED until enough data nodes exist, settings such as index.number_of_shards remain creation-time only, and data stream write indices cannot be closed, so some changes still require template updates, rollover, or reindex workflow.

Steps to update index settings in Elasticsearch:

List the target index to confirm the exact name and current health.

$ curl -sS --fail "http://localhost:9200/_cat/indices/app-events-2026.04?v"
health status index              uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
green  open   app-events-2026.04 3WkHUrIgS_GZcNdCISr52A   1   0          0            0       227b           227b         227b

The _cat APIs are intended for human-readable checks. Replace http://localhost:9200 with the real endpoint and add authentication or TLS options when security is enabled.

Review the current explicit setting values on the index.

$ curl -sS --fail "http://localhost:9200/app-events-2026.04/_settings?pretty&filter_path=*.settings.index.number_of_replicas,*.settings.index.refresh_interval"
{
  "app-events-2026.04" : {
    "settings" : {
      "index" : {
        "refresh_interval" : "1s",
        "number_of_replicas" : "0"
      }
    }
  }
}

If a setting is missing from this filtered response, the index is using the cluster or built-in default rather than an explicit override.

Update dynamic settings such as index.number_of_replicas and index.refresh_interval on the open index.
```
$ curl -sS --fail -H "Content-Type: application/json" -X PUT "http://localhost:9200/app-events-2026.04/_settings?pretty" -d '{
  "index": {
    "number_of_replicas": 1,
    "refresh_interval": "30s"
  }
}'
{
  "acknowledged" : true
}
```
Raising the replica count on a one-node cluster leaves the new replica shard UNASSIGNED and the index health yellow until another data node can host the replica.

Set refresh_interval to -1 during sustained bulk indexing to disable background refreshes temporarily, and set a positive value again before regular search traffic resumes.

Read the settings again to confirm the new explicit values are stored.

$ curl -sS --fail "http://localhost:9200/app-events-2026.04/_settings?pretty&filter_path=*.settings.index.number_of_replicas,*.settings.index.refresh_interval"
{
  "app-events-2026.04" : {
    "settings" : {
      "index" : {
        "refresh_interval" : "30s",
        "number_of_replicas" : "1"
      }
    }
  }
}

Check cluster health and shard allocation after the replica change.

$ curl -sS --fail "http://localhost:9200/_cluster/health/app-events-2026.04?pretty&filter_path=status,number_of_nodes,number_of_data_nodes,active_primary_shards,active_shards,unassigned_shards,active_shards_percent_as_number"
{
  "status" : "yellow",
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "unassigned_shards" : 1,
  "active_shards_percent_as_number" : 50.0
}

$ curl -sS --fail "http://localhost:9200/_cat/shards/app-events-2026.04?v"
index              shard prirep state      docs store dataset ip         node
app-events-2026.04 0     p      STARTED       0  227b    227b 192.0.2.40 node-01
app-events-2026.04 0     r      UNASSIGNED

Replica rows show r in the prirep column. On a multi-node cluster, a matching replica row should move to STARTED after allocation completes.

Apply a non-dynamic setting by letting Elasticsearch reopen the index automatically.
```
$ curl -sS --fail -H "Content-Type: application/json" -X PUT "http://localhost:9200/app-events-2026.04/_settings?pretty&reopen=true" -d '{
  "index": {
    "codec": "best_compression"
  }
}'
{
  "acknowledged" : true
}
```
reopen=true temporarily closes and reopens the targeted index so the change can be applied without a separate close and open sequence. Use a maintenance window when a reopen could interrupt writers or searches.

New analyzers still require a closed-index workflow, and a data stream write index cannot be closed directly.

Related: How to create and manage index templates in Elasticsearch
Related: How to reindex data in Elasticsearch

Verify the non-dynamic setting value now stored on the index.

$ curl -sS --fail "http://localhost:9200/app-events-2026.04/_settings?pretty&filter_path=*.settings.index.codec"
{
  "app-events-2026.04" : {
    "settings" : {
      "index" : {
        "codec" : "best_compression"
      }
    }
  }
}

Changing index.codec affects newly written or merged segments. Existing segments are rewritten only as merges occur.

Reset a dynamic setting to the default behavior by assigning null.
```
$ curl -sS --fail -H "Content-Type: application/json" -X PUT "http://localhost:9200/app-events-2026.04/_settings?pretty" -d '{
  "index": {
    "refresh_interval": null
  }
}'
{
  "acknowledged" : true
}
```
Use the query parameter preserve_existing=true when a wildcard or alias targets multiple indices and only missing settings should be filled in without overwriting existing explicit values.

Read the settings again to confirm the explicit index.refresh_interval override is gone.

$ curl -sS --fail "http://localhost:9200/app-events-2026.04/_settings?pretty&filter_path=*.settings.index.refresh_interval,*.settings.index.number_of_replicas,*.settings.index.codec"
{
  "app-events-2026.04" : {
    "settings" : {
      "index" : {
        "codec" : "best_compression",
        "number_of_replicas" : "1"
      }
    }
  }
}

When index.refresh_interval is no longer stored explicitly, current Elastic Stack falls back to the default refresh behavior, which is 1s on Elastic Stack and can defer background refreshes on search-idle shards until the next search request.

Author: Mohd Shakir Zakaria
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.