How to Configure Index Settings in Elasticsearch

To configure index settings in Elasticsearch, use the PUT API with the index name and specify settings in the settings JSON object. You can set options like number_of_shards and number_of_replicas during index creation or update some settings on an existing index.

Syntax

The basic syntax to configure index settings uses the PUT HTTP method targeting the index name, with a JSON body containing a settings object. This object holds key-value pairs for settings like shard count or refresh interval.

• PUT /index_name/_settings: Update settings on an existing index.
• PUT /index_name: Create a new index with settings.
• settings: JSON object with configuration options.

json

PUT /my_index
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}

Example

This example creates a new index named products with 5 shards and 1 replica. It shows how to send the request to Elasticsearch to set these index settings at creation time.

json

PUT /products
{
  "settings": {
    "number_of_shards": 5,
    "number_of_replicas": 1
  }
}

Output

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "products"
}

Common Pitfalls

Common mistakes include trying to change number_of_shards on an existing index, which is not allowed, and forgetting to refresh the index after updating settings that affect search behavior. Also, some settings require the index to be closed before updating.

Always check which settings are dynamic (can be updated live) and which require index recreation.

json

### Wrong: Trying to update shards on existing index
PUT /products/_settings
{
  "index": {
    "number_of_shards": 10
  }
}

### Right: Create new index with desired shards
PUT /products_v2
{
  "settings": {
    "number_of_shards": 10
  }
}

Quick Reference

Setting	Description	Can Update After Creation
number_of_shards	Number of primary shards for the index	No
number_of_replicas	Number of replica shards	Yes
refresh_interval	How often the index refreshes to make changes searchable	Yes
analysis	Settings for text analysis and tokenization	No
max_result_window	Maximum number of search results returned	Yes

Key Takeaways

Configure index settings using the PUT API with a settings JSON object.

Set shard count only when creating the index; it cannot be changed later.

Some settings can be updated live, others require closing or recreating the index.

Always verify which settings are dynamic before attempting updates.

Use the quick reference table to know which settings can be changed after creation.