266 lines
7.1 KiB
Plaintext
266 lines
7.1 KiB
Plaintext
[[indices-templates-v1]]
|
|
=== Put index template API
|
|
++++
|
|
<titleabbrev>Put index template</titleabbrev>
|
|
++++
|
|
|
|
This documentation is about V1 (version 1) index templates, which are deprecated and will be
|
|
replaced by V2 templates. For information about V2 templates, see <<indices-templates>>.
|
|
|
|
[NOTE]
|
|
====
|
|
In {es} 7.8 the `prefer_v2_templates` querystring parameter was introduced to the index, update,
|
|
bulk, and create index APIs to allow configuring whether to favor V2 or V1 index templates. In 7.x
|
|
the default value for this parameter is `false` meaning that the V1 index templates take precedence.
|
|
In 8.x the default value for the parameter is `true` meaning that <<indices-templates,V2 index
|
|
templates>> take precedence (V1 templates may still match if no V2 template matches).
|
|
====
|
|
|
|
Creates or updates an index template.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE _template/template_*
|
|
--------------------------------------------------
|
|
// TEARDOWN
|
|
|
|
//////////////////////////
|
|
|
|
[[put-index-template-v1-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_template/<index-template>`
|
|
|
|
|
|
[[put-index-template-v1-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 include comments anywhere in the request body,
|
|
except before the opening curly bracket.
|
|
|
|
[[getting-v1]]
|
|
===== Getting templates
|
|
|
|
See <<indices-get-template-v1>>.
|
|
|
|
|
|
[[put-index-template-v1-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<index-template>`::
|
|
(Required, string)
|
|
Name of the index template to create.
|
|
|
|
|
|
[[put-index-template-v1-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`create`::
|
|
(Optional, boolean)
|
|
If `true`, this request cannot replace or update existing index templates.
|
|
Defaults to `false`.
|
|
|
|
`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=master-timeout]
|
|
|
|
|
|
[[put-index-template-v1-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]
|
|
|
|
`version`::
|
|
(Optional, integer)
|
|
Version number used to manage index templates externally.
|
|
This number is not automatically generated by {es}.
|
|
|
|
|
|
[[put-index-template-v1-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
===== Index template with index aliases
|
|
|
|
You can include <<indices-aliases,index aliases>> in an index template.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _template/template_1
|
|
{
|
|
"index_patterns" : ["te*"],
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
},
|
|
"aliases" : {
|
|
"alias1" : {},
|
|
"alias2" : {
|
|
"filter" : {
|
|
"term" : {"user" : "kimchy" }
|
|
},
|
|
"routing" : "kimchy"
|
|
},
|
|
"{index}-alias" : {} <1>
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<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-v1]]
|
|
===== 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,console]
|
|
--------------------------------------------------
|
|
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 }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
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.
|
|
|
|
|
|
[[versioning-templates-v1]]
|
|
===== Template versioning
|
|
|
|
You 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 {es}.
|
|
|
|
To unset a `version`,
|
|
replace the template without specifying one.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_template/template_1
|
|
{
|
|
"index_patterns" : ["*"],
|
|
"order" : 0,
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
},
|
|
"version": 123
|
|
}
|
|
--------------------------------------------------
|
|
|
|
To check the `version`,
|
|
you can use the <<indices-get-template, get index template>> API
|
|
with the <<common-options-response-filtering, `filter_path`>> query parameter
|
|
to return only the version number:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_template/template_1?filter_path=*.version
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"template_1" : {
|
|
"version" : 123
|
|
}
|
|
}
|
|
--------------------------------------------------
|