Put index template API
editPut index template API
editCreates or updates an index template. Index templates define settings, mappings, and aliases that can be applied automatically to new indices.
PUT /_index_template/template_1 { "index_patterns" : ["te*"], "priority" : 1, "template": { "settings" : { "number_of_shards" : 2 } } }
Request
editPUT /_index_template/<index-template>
Description
editElasticsearch applies templates to new indices based on an wildcard pattern that matches the index name.
Index templates are applied during index creation.
Settings and mappings specified in a create index request override any settings or mappings specified in an index template.
Changes to index templates do not affect existing indices.
Comments in index templates
editYou can use C-style /* */ block comments in index templates. You can include comments anywhere in the request body, except before the opening curly bracket.
Path parameters
edit-
<index-template>
- (Required, string) Name of the index template to create.
Query parameters
edit-
create
-
(Optional, boolean)
If
true
, this request cannot replace or update existing index templates. Defaults tofalse
. -
master_timeout
-
(Optional, time units) Specifies the period of time 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. Defaults to
30s
.
Request body
edit-
index_patterns
-
(Required, array of strings)
Array of wildcard (
*
) expressions used to match the names of indices during creation. -
template
-
(Optional, object) Template to be applied. It may optionally include an
aliases
,mappings
, orsettings
configuration.Properties of
template
-
aliases
- (Optional, alias object) Index aliases which include the index. See Update index alias.
-
mappings
-
(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:
- Field names
- Field data types
- Mapping parameters
See Mapping.
-
settings
- (Optional, index setting object) Configuration options for the index. See Index Settings.
-
-
composed_of
- (Optional, array of strings) An ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence. See Composing multiple component templates for an example.
-
priority
- (Optional, integer) Priority to determine index template precedence when a new index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though it is of priority 0 (lowest priority). This number is not automatically generated by Elasticsearch.
-
version
- (Optional, integer) Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch.
-
_meta
- (Optional, object) Optional user metadata about the index template. May have any contents. This map is not automatically generated by Elasticsearch.
Examples
editIndex template with index aliases
editYou can include index aliases in an index template.
Multiple matching templates
editIf multiple index templates match the name of a new index, the template with the highest priority is used. For example:
PUT /_index_template/template_1 { "index_patterns" : ["t*"], "priority" : 0, "template": { "settings" : { "number_of_shards" : 1, "number_of_replicas": 0 }, "mappings" : { "_source" : { "enabled" : false } } } } PUT /_index_template/template_2 { "index_patterns" : ["te*"], "priority" : 1, "template": { "settings" : { "number_of_shards" : 2 }, "mappings" : { "_source" : { "enabled" : true } } } }
For indices that start with te*
, _source
will enabled, and the index will have two primary
shards and one replica, because only template_2
will be applied.
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.
Template versioning
editYou can use the version
parameter to add a version number to an index template.
External systems can use these version numbers to simplify template management.
The version
parameter is optional and not automatically generated or used by Elasticsearch.
To unset a version
, replace the template without specifying one.
PUT /_index_template/template_1 { "index_patterns" : ["foo", "bar"], "priority" : 0, "template": { "settings" : { "number_of_shards" : 1 } }, "version": 123 }
To check the version
, you can use the get index template API.
Template metadata
editYou can use the _meta
parameter to add arbitrary metadata to an index template.
This user-defined object is stored in the cluster state,
so keeping it short is preferrable.
The _meta
parameter is optional and not automatically generated or used by Elasticsearch.
To unset _meta
, replace the template without specifying one.
PUT /_index_template/template_1 { "index_patterns": ["foo", "bar"], "template": { "settings" : { "number_of_shards" : 3 } }, "_meta": { "description": "set number of shards to three", "serialization": { "class": "MyIndexTemplate", "id": 17 } } }
To check the _meta
, you can use the get index template API.
Composing aliases, mappings, and settings
editWhen 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.
In this example, the order of the two component templates changes the number of shards for an index:
PUT /_component_template/template_with_2_shards { "template": { "settings": { "index.number_of_shards": 2 } } } PUT /_component_template/template_with_3_shards { "template": { "settings": { "index.number_of_shards": 3 } } } PUT /_index_template/template_1 { "index_patterns": ["t*"], "composed_of": ["template_with_2_shards", "template_with_3_shards"] }
In this case, an index matching t*
will have three primary shards. If the order of composed
templates were reversed, the index would have two primary shards.
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.