How to Update Elasticsearch Index Settings (Dynamic and Static)

The Elasticsearch Update Index Settings API (PUT /<index>/_settings) changes index-level settings on an existing index. Dynamic settings (replicas, refresh interval, allocation rules) update live on an open index. Static settings (sort order, codec choice) require the index to be closed before the change takes effect. The number_of_shards setting is fixed at creation and cannot be changed at all - it requires a reindex, clone, shrink, or split.

When to Use Update Settings (vs Alternatives)

Prerequisites

• The user or API key has manage privilege on the target index pattern.
• The target index is open (for dynamic updates) or you can briefly close it (for static updates).
• The cluster is in green or yellow health for the affected index. Don't change settings on a red index.

Dynamic Settings: Update on a Live Index

Dynamic settings can be changed while the index is open and serving traffic. The most common ones:

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 2,
    "refresh_interval": "30s"
  }
}

Response: { "acknowledged": true }. Changes apply immediately to all shards.

You can update multiple settings in one call; they apply atomically.

Static Settings: Close, Update, Reopen

Static settings cannot change on an open index. The standard pattern is close, update, reopen:

POST /my-index/_close
PUT  /my-index/_settings
{
  "index": {
    "codec": "best_compression"
  }
}
POST /my-index/_open

A few static settings worth knowing:

The index is offline for the duration. On a large index, reopen and shard recovery can take several minutes. Schedule static-setting updates for low-traffic windows.

number_of_shards is a special case: it cannot be changed at all, not even on a closed index. Use the shrink API (decrease), the split API (increase), or reindex into a new index with the desired shard count.

Step-by-Step: Update Index Settings Safely

1. Identify whether the setting is dynamic or static. The Elasticsearch reference documentation marks each setting; if the docs do not say "dynamic", assume static. Reasonable defaults: number_of_replicas, refresh_interval, routing.allocation.* are dynamic; codec, sort.* are static.

2. For dynamic settings, send PUT directly.

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

3. For static settings, close the index first.

   POST /my-index/_close
   

4. Apply the settings change.

   PUT /my-index/_settings
   {
     "index": { "codec": "best_compression" }
   }
   

5. Reopen the index and wait for green health.

   POST /my-index/_open
   GET  /_cluster/health/my-index?wait_for_status=green&timeout=120s
   

6. Verify with the Get Settings API.

   GET /my-index/_settings
   

Pattern: Update Settings via Index Templates

If the same setting tweak applies to every new index of a given pattern, do it once in an index template rather than running PUT /_settings repeatedly:

PUT /_index_template/logs-template
{
  "index_patterns": ["logs-*"],
  "template": {
    "settings": {
      "number_of_shards": 2,
      "number_of_replicas": 1,
      "refresh_interval": "30s"
    }
  }
}

The template applies to indices created after the template is registered; it does not retroactively change existing indices.

Operating Settings Changes in Production

The trap with index-settings changes is silent regressions. Lowering number_of_replicas to save disk works fine on a green cluster - until a node fails and there is no second copy. Raising refresh_interval from 1s to 30s to boost throughput silently breaks any application that depended on near-real-time search. Always check the downstream callers before changing a setting that touches durability or visibility.

Pulse tracks index-settings changes over time and correlates them with cluster behavior - search latency, indexing throughput, segment counts, and merge IO. When a settings change causes a regression, Pulse's auto-RCA points at the change rather than leaving you to bisect node logs. For repetitive tuning (refresh interval per-index, replica counts per tier), Pulse recommends per-index values based on the actual workload pattern.

Common Mistakes

1. Trying to change number_of_shards. It cannot be updated. Use shrink, split, or reindex.
2. Updating a static setting on an open index. The request returns an error. Close the index first.
3. Forgetting to reopen after updating a static setting. The application sees index_closed_exception until the index is reopened.
4. Changing settings without a snapshot or rollback plan. Lowering replicas or codec changes is irreversible without a reindex.
5. Setting refresh_interval: -1 for a "permanent" bulk load and never restoring. New documents accumulate indefinitely and are not searchable.
6. Updating settings on a red index. Wait until the index recovers; setting changes can interfere with recovery.

Frequently Asked Questions

Q: What is the difference between dynamic and static index settings in Elasticsearch?
A: Dynamic settings can be changed while the index is open and serving traffic (replicas, refresh interval, allocation rules). Static settings require the index to be closed before the change takes effect (codec, sort order). The official setting reference marks each one.

Q: Can I change number_of_shards after an index is created?
A: No. number_of_shards is fixed at creation. To change shard count, reindex into a new index with the desired count, use the shrink API to decrease, or use the split API to increase (requires number_of_routing_shards set at creation).

Q: How do I change the refresh interval on a live Elasticsearch index?
A: Send PUT /<index>/_settings with { "index": { "refresh_interval": "30s" } }. The setting is dynamic, so no close is required and the change takes effect on the next refresh cycle. See the refresh interval guide for tuning advice.

Q: Why is my Elasticsearch settings update returning a "static setting" error?
A: The setting you are trying to change is static, which means the index has to be closed first. Run POST /<index>/_close, then PUT the settings, then POST /<index>/_open to bring it back online.

Q: Can I update settings on multiple indices at once?
A: Yes. Use a comma list (PUT /index-a,index-b/_settings) or a wildcard (PUT /logs-*/_settings). The same body applies to every matched index. Be careful with wildcards if action.destructive_requires_name is loose.

Q: How do I roll back an index settings change?
A: Send the same PUT /<index>/_settings call with the previous value. For settings whose previous value was the system default, set the value to null to reset (e.g. "refresh_interval": null).

Q: Are index settings the same as mapping changes?
A: No. Settings control runtime behavior (shards, refresh, allocation). Mappings define field types and analyzers. Use put mapping for mapping changes, and a reindex when an existing field's type needs to change.

Related Reading

• Create an Index with Mapping: set the right settings at creation time.
• Index Refresh Interval: the most commonly updated dynamic setting.
• Index Templates: apply settings to every new index of a pattern.
• Changing a Field Type: when the change is to mappings, not settings.
• Clone Index Guide: uses index.blocks.write settings updates as part of its flow.
• Reindex Data Guide: the answer when a settings update is not enough.
• Cluster Health Check: the call to make before and after settings changes.