elasticsearch/docs/reference/indices/templates.asciidoc

[[indices-templates]]
=== Index Templates

// tag::index-template-def[]
Index templates define <<index-modules-settings,settings>> and <<mapping,mappings>>
that you can automatically apply when creating new indices.
{es} applies templates to new indices
based on an index pattern that matches the index name.
// end::index-template-def[]

NOTE: Templates are only applied at index creation time. Changing a template
will have no impact on existing indices. When using the create index API, the
settings/mappings defined as part of the create index call will take precedence
over any matching settings/mappings defined in the template.

For example:

[source,js]
--------------------------------------------------
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",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TESTSETUP

NOTE: Index templates provide C-style /* */ block comments. Comments are allowed
everywhere in the JSON document except before the initial opening curly bracket. 

Defines a template named `template_1`, with a template pattern of `te*` or `bar*`.
The settings and mappings will be applied to any index name that matches
the `te*` or `bar*` pattern.

It is also possible to include aliases in an index template as follows:

[source,js]
--------------------------------------------------
PUT _template/template_1
{
    "index_patterns" : ["te*"],
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user" : "kimchy" }
            },
            "routing" : "kimchy"
        },
        "{index}-alias" : {} <1>
    }
}
--------------------------------------------------
// CONSOLE
// TEST[s/^/DELETE _template\/template_1\n/]

<1> the `{index}` placeholder in the alias name will be replaced with the
actual index name that the template gets applied to, during index creation.

[float]
[[delete]]
==== Deleting a Template

Index templates are identified by a name (in the above case
`template_1`) and can be deleted as well:

[source,js]
--------------------------------------------------
DELETE /_template/template_1
--------------------------------------------------
// CONSOLE

[float]	
[[getting]]	
==== Getting templates

See <<indices-get-template>>.

[float]
[[multiple-templates]]
==== Multiple Templates Matching

Multiple 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:

[source,js]
--------------------------------------------------
PUT /_template/template_1
{
    "index_patterns" : ["*"],
    "order" : 0,
    "settings" : {
        "number_of_shards" : 1
    },
    "mappings" : {
        "_source" : { "enabled" : false }
    }
}

PUT /_template/template_2
{
    "index_patterns" : ["te*"],
    "order" : 1,
    "settings" : {
        "number_of_shards" : 1
    },
    "mappings" : {
        "_source" : { "enabled" : true }
    }
}
--------------------------------------------------
// CONSOLE
// TEST[s/^/DELETE _template\/template_1\n/]

The above will disable storing the `_source`, but
for indices that start with `te*`, `_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.

NOTE: Multiple matching templates with the same order value will 
result in a non-deterministic merging order.

[float]
[[versioning-templates]]
==== Template Versioning

Templates can optionally add a `version` number, which can be any integer value,
in order to simplify template management by external systems. The `version`
field is completely optional and it is meant solely for external management of
templates. To unset a `version`, simply replace the template without specifying
one.

[source,js]
--------------------------------------------------
PUT /_template/template_1
{
    "index_patterns" : ["*"],
    "order" : 0,
    "settings" : {
        "number_of_shards" : 1
    },
    "version": 123
}
--------------------------------------------------
// CONSOLE

To check the `version`, you can
<<common-options-response-filtering, filter responses>>
using `filter_path` to limit the response to just the `version`:

[source,js]
--------------------------------------------------
GET /_template/template_1?filter_path=*.version
--------------------------------------------------
// CONSOLE
// TEST[continued]

This should give a small response that makes it both easy and inexpensive to parse:

[source,js]
--------------------------------------------------
{
  "template_1" : {
    "version" : 123
  }
}
--------------------------------------------------
// TESTRESPONSE