Update data stream settings | Elasticsearch API documentation

Update data stream settings Generally available

PUT /_data_stream/{name}/_settings

This API can be used to override settings on specific data streams. These overrides will take precedence over what is specified in the template that the data stream matches. To prevent your data stream from getting into an invalid state, only certain settings are allowed. If possible, the setting change is applied to all backing indices. Otherwise, it will be applied when the data stream is next rolled over.

Required authorization

Index privileges: manage

Path parameters

name string | array[string] Required

A comma-separated list of data streams or data stream patterns.

Query parameters

dry_run boolean

If true, the request does not actually change the settings on any data streams or indices. Instead, it simulates changing the settings and reports back to the user what would have happened had these settings actually been applied.
master_timeout string

The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

application/json

Body Required

object

Index settings

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  applied_to_data_stream boolean Required
  
  If the settings were successfully applied to the data stream (or would have been, if running in dry_run mode), it is true. If an error occurred, it is false.
  
  error string
  
  A message explaining why the settings could not be applied to the data stream.
  
  settings object Required
  Index settings
  
  effective_settings object Required
  Index settings
  
  index_settings_results object Required
  
  Hide index_settings_results attributes Show index_settings_results attributes object
  
  applied_to_data_stream_only array[string] Required
  
  The list of settings that were applied to the data stream but not to backing indices. These will be applied to the write index the next time the data stream is rolled over.
  
  applied_to_data_stream_and_backing_indices array[string] Required
  
  The list of settings that were applied to the data stream and to all of its backing indices. These settings will also be applied to the write index the next time the data stream is rolled over.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  index string Required
  
  error string Required
  
  A message explaining why the settings could not be applied to specific indices.

PUT /_data_stream/{name}/_settings

curl \
 --request PUT 'http://api.example.com/_data_stream/{name}/_settings' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"index.lifecycle.name\" : \"new-test-policy\",\n  \"index.number_of_shards\": 11\n}"'

Request example

This is a request to change two settings on a data stream.

{
  "index.lifecycle.name" : "new-test-policy",
  "index.number_of_shards": 11
}

Response examples (200)

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when two settings are successfully updated on the data stream. In this case, `index.number_of_shards` is only applied to the data stream -- it will be applied to the write index on rollover. The setting `index.lifecycle.name` is applied to the data stream and all backing indices.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      },
      "index_settings_results": {
        "applied_to_data_stream_only": [
          "index.number_of_shards"
        ],
        "applied_to_data_stream_and_backing_indices": [
          "index.lifecycle.name"
        ]
      }
    }
  ]
}

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a setting is successfully applied to the data stream, but one of the backing indices, `.ds-my-data-stream-2025.05.28-000001`, has a write block. The response reports that the setting was not successfully applied to that index.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      },
      "index_settings_results": {
        "applied_to_data_stream_only": [
          "index.number_of_shards"
        ],
        "applied_to_data_stream_and_backing_indices": [
          "index.lifecycle.name"
        ],
        "errors": [
          {
            "index": ".ds-my-data-stream-2025.05.28-000001",
            "error": "index [.ds-my-data-stream-2025.05.28-000001] blocked by: [FORBIDDEN/9/index metadata (api)];"
          }
        ]
      }
    }
  ]
}

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a user attempts to set a setting that is not allowed on a data stream. As a result, no change was applied to the data stream.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": false,
      "error": "Cannot set the following settings on a data stream: [index.number_of_replicas]",
      "settings": {},
      "effective_settings": {},
      "index_settings_results": {
        "applied_to_data_stream_only": [],
        "applied_to_data_stream_and_backing_indices": []
      }
    }
  ]
}