Create or update index template API
editCreate or update index template API
editThis documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8. For information about composable templates, see Index templates.
Creates or updates an index template.
PUT _template/template_1 { "index_patterns": ["te*", "bar*"], "settings": { "number_of_shards": 1 }, "mappings": { "_source": { "enabled": false }, "properties": { "host_name": { "type": "keyword" }, "created_at": { "type": "date" } } } }
Request
editPUT /_template/<index-template>
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
manage_index_templates
ormanage
cluster privilege to use this API.
Description
editIndex templates define settings and mappings that you can automatically apply when creating new indices. Elasticsearch applies templates to new indices based on an index pattern that matches the index name.
Composable templates always take precedence over legacy templates. If no composable template matches a new index, matching legacy templates are applied according to their order.
Index templates are only applied during index creation. Changes to index templates do not affect existing indices. Settings and mappings specified in create index API requests override any settings or mappings specified in an index template.
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.
Getting templates
editPath 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
. -
order
-
(Optional,integer) Order in which Elasticsearch applies this template if index matches multiple templates.
Templates with lower
order
values are merged first. Templates with higherorder
values are merged later, overriding templates with lower values. -
master_timeout
-
(Optional, time units)
Period to wait for the master node. If the master node is not available before
the timeout expires, the request fails and returns an error. Defaults to
30s
. Can also be set to-1
to indicate that the request should never timeout.
Request body
edit-
index_patterns
- (Required, array of strings) Array of wildcard expressions used to match the names of indices during creation.
-
aliases
-
(Optional, object of objects) Aliases for the index.
Properties of
aliases
objects-
<alias>
-
(Required, object) The key is the alias name. Index alias names support date math.
The object body contains options for the alias. Supports an empty object.
Properties of
<alias>
-
filter
- (Optional, Query DSL object) Query used to limit documents the alias can access.
-
index_routing
-
(Optional, string) Value used to route indexing operations to a specific shard.
If specified, this overwrites the
routing
value for indexing operations. -
is_hidden
-
(Optional, Boolean) If
true
, the alias is hidden. Defaults tofalse
. All indices for the alias must have the sameis_hidden
value. -
is_write_index
-
(Optional, Boolean) If
true
, the index is the write index for the alias. Defaults tofalse
. -
routing
- (Optional, string) Value used to route indexing and search operations to a specific shard.
-
search_routing
-
(Optional, string) Value used to route search operations to a specific shard. If
specified, this overwrites the
routing
value for search operations.
-
-
-
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.
-
version
- (Optional, integer) Version number used to manage index templates externally. This number is not automatically generated by Elasticsearch.
Examples
editIndex template with index aliases
editYou can include index aliases in an index template.
resp = client.indices.put_template( name="template_1", index_patterns=[ "te*" ], settings={ "number_of_shards": 1 }, aliases={ "alias1": {}, "alias2": { "filter": { "term": { "user.id": "kimchy" } }, "routing": "shard-1" }, "{index}-alias": {} }, ) print(resp)
const response = await client.indices.putTemplate({ name: "template_1", index_patterns: ["te*"], settings: { number_of_shards: 1, }, aliases: { alias1: {}, alias2: { filter: { term: { "user.id": "kimchy", }, }, routing: "shard-1", }, "{index}-alias": {}, }, }); console.log(response);
Indices matching multiple templates
editMultiple index templates can potentially match an index, in this case,
both the settings and mappings are merged into the final configuration
of the index. The order of the merging can be controlled using the
order
parameter, with lower order being applied first, and higher
orders overriding them. For example:
resp = client.indices.put_template( name="template_1", index_patterns=[ "te*" ], order=0, settings={ "number_of_shards": 1 }, mappings={ "_source": { "enabled": False } }, ) print(resp) resp1 = client.indices.put_template( name="template_2", index_patterns=[ "tes*" ], order=1, settings={ "number_of_shards": 1 }, mappings={ "_source": { "enabled": True } }, ) print(resp1)
const response = await client.indices.putTemplate({ name: "template_1", index_patterns: ["te*"], order: 0, settings: { number_of_shards: 1, }, mappings: { _source: { enabled: false, }, }, }); console.log(response); const response1 = await client.indices.putTemplate({ name: "template_2", index_patterns: ["tes*"], order: 1, settings: { number_of_shards: 1, }, mappings: { _source: { enabled: true, }, }, }); console.log(response1);
PUT /_template/template_1 { "index_patterns" : ["te*"], "order" : 0, "settings" : { "number_of_shards" : 1 }, "mappings" : { "_source" : { "enabled" : false } } } PUT /_template/template_2 { "index_patterns" : ["tes*"], "order" : 1, "settings" : { "number_of_shards" : 1 }, "mappings" : { "_source" : { "enabled" : true } } }
The above will disable storing the _source
, but
for indices that start with tes*
, _source
will still be enabled.
Note, for mappings, the merging is "deep", meaning that specific
object/property based mappings can easily be added/overridden on higher
order templates, with lower order templates providing the basis.
Multiple matching templates with the same order value will result in a non-deterministic merging order.
Template versioning
editYou can use the version
parameter
to add an optional version number to an index template.
External systems can use these version numbers
to simplify template management.
The version
parameter is completely optional
and not automatically generated by Elasticsearch.
To unset a version
,
replace the template without specifying one.
resp = client.indices.put_template( name="template_1", index_patterns=[ "my-index-*" ], order=0, settings={ "number_of_shards": 1 }, version=123, ) print(resp)
response = client.indices.put_template( name: 'template_1', body: { index_patterns: [ 'my-index-*' ], order: 0, settings: { number_of_shards: 1 }, version: 123 } ) puts response
const response = await client.indices.putTemplate({ name: "template_1", index_patterns: ["my-index-*"], order: 0, settings: { number_of_shards: 1, }, version: 123, }); console.log(response);
PUT /_template/template_1 { "index_patterns" : ["my-index-*"], "order" : 0, "settings" : { "number_of_shards" : 1 }, "version": 123 }
To check the version
,
you can use the get index template API
with the filter_path
query parameter
to return only the version number:
$params = [ 'name' => 'template_1', ]; $response = $client->indices()->getTemplate($params);
resp = client.indices.get_template( name="template_1", filter_path="*.version", ) print(resp)
response = client.indices.get_template( name: 'template_1', filter_path: '*.version' ) puts response
const response = await client.indices.getTemplate({ name: "template_1", filter_path: "*.version", }); console.log(response);
GET /_template/template_1?filter_path=*.version
The API returns the following response:
{ "template_1" : { "version" : 123 } }