mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-07 05:28:34 +00:00
1337b35572
This commit removes the `prefer_v2_templates` flag and setting. This was a brief setting that allowed specifying whether V1 or V2 template should be used when an index is created. It has been removed in favor of V2 templates always having priority. Relates to #53101 Resolves #56528 This is not a breaking change because this flag was never in a released version.
264 lines
6.8 KiB
Plaintext
264 lines
6.8 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 V2 templates were introduced. When a V2 index template matches a given index it always
|
|
takes precedence over a V1 template. If no V2 index template matches, a V1 template may still match
|
|
and be applied.
|
|
====
|
|
|
|
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
|
|
}
|
|
}
|
|
--------------------------------------------------
|