--- type: api title: Update data stream settings description: NOTE: Available in 8.19. Not available in earlier versions. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-indices-put-data-stream-settings resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-indices-put-data-stream-settings products: - Elasticsearch --- # Update data stream settings Availability: 9.1+ ## Paths - `PUT` `/_data_stream/{name}/_settings` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth) #### Path Parameters - `name` (union IndexName | [] IndexName) A comma-separated list of data streams or data stream patterns. ## Description NOTE: Available in 8.19. Not available in earlier versions. 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` ## Query String Parameters - `dry_run` (boolean · default: false) 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 Duration · default: 30s) 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. - `timeout` (string Duration · default: 30s) The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. ## Request Body `application/json` Type: `IndexSettings` ## Response `application/json` - `data_streams` ([] UpdatedDataStreamSettings) - `name` (string IndexName) The data stream name. - `applied_to_data_stream` (boolean) 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` (IndexSettings) The settings that are specfic to this data stream that will override any settings from the matching index template. - `effective_settings` (IndexSettings) The settings that are effective on this data stream, taking into account the settings from the matching index template and the settings specific to this data stream. - `index_settings_results` ({} IndexSettingResults) Information about whether and where each setting was applied. - `applied_to_data_stream_only` ([] string) 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` ([] string) 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` ([] DataStreamSettingsError) - `index` (string IndexName) - `error` (string) A message explaining why the settings could not be applied to specific indices. ## Code Examples #### Console ```console PUT /_data_stream/my-data-stream/_settings { "index.lifecycle.name" : "new-test-policy", "index.number_of_shards": 11 } ``` #### JavaScript ```javascript const response = await client.indices.putDataStreamSettings({ name: "my-data-stream", settings: { "index.lifecycle.name": "new-test-policy", "index.number_of_shards": 11, }, }); ``` #### Python ```python resp = client.indices.put_data_stream_settings( name="my-data-stream", settings={ "index.lifecycle.name": "new-test-policy", "index.number_of_shards": 11 }, ) ``` #### curl ```curl curl -X PUT "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_settings" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "index.lifecycle.name": "new-test-policy", "index.number_of_shards": 11 }' ``` #### Java ```java client.indices().putDataStreamSettings(p -> p .name("my-data-stream") .settings(s -> s .otherSettings(Map.of("index.lifecycle.name", JsonData.fromJson("\"new-test-policy\""),"index.number_of_shards", JsonData.fromJson("11"))) ) ); ``` #### C# ```c# var response = await client.Indices .PutDataStreamSettingsAsync(name: new[] { "my-data-stream" }, d1 => d1 .Settings(d2 => d2 .OtherSettings(new Dictionary() { { "index.lifecycle.name", "new-test-policy" }, { "index.number_of_shards", 11 } }) ) ); ``` #### PHP ```php $resp = $client->indices()->putDataStreamSettings([ "name" => "my-data-stream", "body" => [ "index.lifecycle.name" => "new-test-policy", "index.number_of_shards" => 11, ], ]); ``` #### Ruby ```ruby response = client.indices.put_data_stream_settings( name: "my-data-stream", body: { "index.lifecycle.name": "new-test-policy", "index.number_of_shards": 11 } ) ``` ## Response Examples #### Change data stream settings on a data stream 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. ```json { "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" ] } } ] } ``` #### Change data stream settings on a data stream that has an index with a metadata block 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. ```json { "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)];" } ] } } ] } ``` #### Attempt to change a data stream setting that is not allowed 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. ```json { "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": [] } } ] } ```