Update data stream settings

PUT /_data_stream/{name}/_settings

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

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Path parameters

Query parameters

Request body

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