Update data stream settings

PUT /_data_stream/{name}/_settings

Auth

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

Path parameters

name union string | string[] required: A comma-separated list of data streams or data stream patterns.

Query 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 · 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 · 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

Type: object

Response

application/json

data_streams object[] required

Examples

Request Console 1 / 8 languages

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

Console Kibana Dev Tools

PUT /_data_stream/my-data-stream/_settings
{
  "index.lifecycle.name" : "new-test-policy",
  "index.number_of_shards": 11
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.putDataStreamSettings({
  name: "my-data-stream",
  settings: {
    "index.lifecycle.name": "new-test-policy",
    "index.number_of_shards": 11,
  },
});

Python Elasticsearch Python Client

resp = client.indices.put_data_stream_settings(
    name="my-data-stream",
    settings={
        "index.lifecycle.name": "new-test-policy",
        "index.number_of_shards": 11
    },
)

curl Shell

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 Elasticsearch Java Client

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# Elasticsearch .NET Client

var response = await client.Indices
    .PutDataStreamSettingsAsync(name: new[] { "my-data-stream" }, d1 => d1
        .Settings(d2 => d2
            .OtherSettings(new Dictionary<string, object>()
            {
                { "index.lifecycle.name", "new-test-policy" },
                { "index.number_of_shards", 11 }
            })
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->putDataStreamSettings([
    "name" => "my-data-stream",
    "body" => [
        "index.lifecycle.name" => "new-test-policy",
        "index.number_of_shards" => 11,
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.put_data_stream_settings(
  name: "my-data-stream",
  body: {
    "index.lifecycle.name": "new-test-policy",
    "index.number_of_shards": 11
  }
)

Response

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"
        ]
      }
    }
  ]
}