Create or update an index template

POST also PUT /_index_template/{name}

Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. Index templates are applied during data stream or index creation. For data streams, these settings and mappings are applied when the stream's backing indices are created. Settings and mappings specified in a create index API request override any settings or mappings specified in an index template. Changes to index templates do not affect existing indices, including the existing backing indices of a data stream.

You can use C-style /* *\/ block comments in index templates. You can include comments anywhere in the request body, except before the opening curly bracket.

Multiple matching templates

If multiple index templates match the name of a new index or data stream, the template with the highest priority is used.

Multiple templates with overlapping index patterns at the same priority are not allowed and an error will be thrown when attempting to create a template matching an existing index template at identical priorities.

Composing aliases, mappings, and settings

When multiple component templates are specified in the composed_of field for an index template, they are merged in the order specified, meaning that later component templates override earlier component templates. Any mappings, settings, or aliases from the parent index template are merged in next. Finally, any configuration on the index request itself is merged. Mapping definitions are merged recursively, which means that later mapping components can introduce new field mappings and update the mapping configuration. If a field mapping is already contained in an earlier component, its definition will be completely overwritten by the later one. This recursive merging strategy applies not only to field mappings, but also root options like dynamic_templates and meta. If an earlier component contains a dynamic_templates block, then by default new dynamic_templates entries are appended onto the end. If an entry already exists with the same key, then it is overwritten by the new definition.

Required authorization

Cluster privileges: manage_index_templates

Path Parameters

name string Name required: Index or template name

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /_index_template/template_1
{
  "index_patterns" : ["template*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.indices.putIndexTemplate({
  name: "template_1",
  index_patterns: ["template*"],
  priority: 1,
  template: {
    settings: {
      number_of_shards: 2,
    },
  },
});

Python Elasticsearch Python Client

resp = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "template*"
    ],
    priority=1,
    template={
        "settings": {
            "number_of_shards": 2
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_index_template/template_1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index_patterns": [
      "template*"
    ],
    "priority": 1,
    "template": {
      "settings": {
        "number_of_shards": 2
      }
    }
  }'

Java Elasticsearch Java Client

client.indices().putIndexTemplate(p -> p
    .indexPatterns("template*")
    .name("template_1")
    .priority(1L)
    .template(t -> t
        .settings(s -> s
            .otherSettings(Map.of())
            .numberOfShards("2")
        )
    )
);

C# Elasticsearch .NET Client

var response = await client.Indices
    .PutIndexTemplateAsync(name: "template_1", d1 => d1
        .IndexPatterns(new[] { "template*" })
        .Priority(1L)
        .Template(d2 => d2
            .Settings(d3 => d3
                .NumberOfShards(2)
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->indices()->putIndexTemplate([
    "name" => "template_1",
    "body" => [
        "index_patterns" => array(
            "template*",
        ),
        "priority" => 1,
        "template" => [
            "settings" => [
                "number_of_shards" => 2,
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.indices.put_index_template(
  name: "template_1",
  body: {
    "index_patterns": [
      "template*"
    ],
    "priority": 1,
    "template": {
      "settings": {
        "number_of_shards": 2
      }
    }
  }
)

Response

No example

You can include index aliases in an index template. During index creation, the {index} placeholder in the alias name will be replaced with the actual index name that the template gets applied to.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /_index_template/{name}
{
  "index_patterns": [
    "template*"
  ],
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "aliases": {
      "alias1": {},
      "alias2": {
        "filter": {
          "term": {
            "user.id": "kimchy"
          }
        },
        "routing": "shard-1"
      },
      "{index}-alias": {}
    }
  }
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_index_template/{name}" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "index_patterns": [
    "template*"
  ],
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "aliases": {
      "alias1": {},
      "alias2": {
        "filter": {
          "term": {
            "user.id": "kimchy"
          }
        },
        "routing": "shard-1"
      },
      "{index}-alias": {}
    }
  }
}'

Response

No example

Required authorization

Path Parameters

Query Parameters { create , master_timeout , cause , }

Request { index_patterns , composed_of , template , data_stream , priority , version , _meta , allow_auto_create , ignore_missing_component_templates , deprecated , }

Response

Query Parameters

Request