200 lines
5.0 KiB
Plaintext
200 lines
5.0 KiB
Plaintext
[[indices-templates]]
|
|
=== Put index template API
|
|
++++
|
|
<titleabbrev>Put index template</titleabbrev>
|
|
++++
|
|
|
|
Creates or updates an index template.
|
|
|
|
[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
|
|
|
|
|
|
[[put-index-template-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_template/<index-template>`
|
|
|
|
|
|
[[put-index-template-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
Use the PUT index template API
|
|
to create or update an index template.
|
|
|
|
// 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[]
|
|
|
|
Index templates are only applied during index creation.
|
|
Changes to index templates do not affect existing indices.
|
|
Settings and mappings specified in <<indices-create-index, create index>> API requests
|
|
override any settings or mappings specified in an index template.
|
|
|
|
===== Comments in index templates
|
|
You can use C-style /* */ block comments in index templates.
|
|
You can includes comments anywhere in the request body,
|
|
except before the opening curly bracket.
|
|
|
|
[[getting]]
|
|
===== Getting templates
|
|
|
|
See <<indices-get-template>>.
|
|
|
|
|
|
[[put-index-template-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<index-template>`::
|
|
(Required, string)
|
|
Name of the index template to create.
|
|
|
|
|
|
[[put-index-template-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`create`::
|
|
(Optional, boolean)
|
|
If `true`, this request cannot replace or update existing index templates.
|
|
Defaults to `false`.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
|
|
|
|
`order`::
|
|
(Optional,integer)
|
|
Order in which {es} applies this template
|
|
if index matches multiple templates.
|
|
+
|
|
Templates with lower `order` values are merged first.
|
|
Templates with higher `order` values are merged later,
|
|
overriding templates with lower values.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
|
|
[[put-index-template-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`index_patterns`::
|
|
(Required, array of strings)
|
|
Array of wildcard expressions
|
|
used to match the names of indices during creation.
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=settings]
|
|
|
|
|
|
|
|
[[put-index-template-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
===== Index template with index aliases
|
|
|
|
You can include <<indices-aliases,index aliases>> in an index template.
|
|
|
|
[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.
|
|
|
|
|
|
[[multiple-templates]]
|
|
===== Indices matching multiple templates
|
|
|
|
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.
|