Update Index Settings API

Introduced 1.0

The Update Index Settings API changes index-level settings in real time. You can update dynamic index settings at any time. You can update static index settings only on a closed index, and you cannot update final static settings, such as index.number_of_shards, after index creation. For more information about static and dynamic index settings, see Index settings.

In addition to the built-in index settings, you can also update settings for individual plugins. To retrieve a complete list of all available settings, including default values, run GET <target-index>/_settings?include_defaults=true.

The API updates settings only on existing indexes and does not create an index. Each setting in the request body is applied whether or not it was previously set on the index. To leave settings that already have a value unchanged and apply only the settings that are not yet set, specify preserve_existing=true. To reset a setting to its default value, set it to null. For more information, see Resetting a setting to its default value.

If the request contains any setting that cannot be updated, the entire request is rejected and no settings are changed.

Endpoints

PUT /{index}/_settings

Path parameters

The following table lists the available path parameters. All path parameters are optional.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Request body

The request body contains the index settings you want to update. You can specify settings in either flat or nested format.

Example request: Updating settings for a single index

The following example updates settings for the books index:

PUT /books/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

response = client.indices.put_settings(
  index = "books",
  body = {
    "index": {
      "number_of_replicas": 2
    }
  }
)

Example request: Resetting a setting to its default value

To revert a setting to its default value, specify null as the value:

PUT /books/_settings
{
  "index": {
    "refresh_interval": null
  }
}

Example request: Updating settings for multiple indexes

The following example updates settings for multiple indexes:

PUT /books,products/_settings
{
  "index": {
    "number_of_replicas": 0
  }
}

Example request: Optimizing for bulk indexing

To optimize an index for bulk indexing operations, disable the refresh interval by setting it to -1. After bulk indexing is complete, reenable it by setting it back to a positive value:

PUT /books/_settings
{
  "index": {
    "refresh_interval": "-1"
  }
}

After completing bulk indexing, restore the refresh interval:

PUT /books/_settings
{
  "index": {
    "refresh_interval": "1s"
  }
}

Example response

{
  "acknowledged": true
}

Response body fields

The following table lists all response body fields.

Status codes

The following table lists the HTTP status codes that the API returns.

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: indices:admin/settings/update.