mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-08 14:05:27 +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.
411 lines
12 KiB
Plaintext
411 lines
12 KiB
Plaintext
[[indices-templates]]
|
|
=== Index template API
|
|
++++
|
|
<titleabbrev>Index template</titleabbrev>
|
|
++++
|
|
|
|
This documentation is about V2 (version 2) index templates. For V1 templates please see the
|
|
<<indices-templates-v1,V1 template documentation>>.
|
|
|
|
[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.
|
|
====
|
|
|
|
An index template is a way to tell {es} how to configure an index when it is created. Templates are
|
|
configured prior to index creation and then when an index is created either manually or through
|
|
indexing a document, the template settings are used as a basis for creating the index.
|
|
|
|
There are two types of templates, index templates and <<indices-component-template,component
|
|
templates>>. Component templates are reusable building blocks that configure mappings, settings, and
|
|
aliases. You use component templates to construct index templates, they aren't directly applied to a
|
|
set of indices. Index templates can contain a collection of component templates, as well as directly
|
|
specify settings, mappings, and aliases.
|
|
|
|
If a new index matches more than one index template, the index template with the highest priority is used.
|
|
|
|
If an index is created with explicit settings and also matches an index template,
|
|
the settings from the create index request take precedence over settings specified in the index template and its component templates.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _index_template/template_1
|
|
{
|
|
"index_patterns": ["te*", "bar*"],
|
|
"template": {
|
|
"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"
|
|
}
|
|
}
|
|
},
|
|
"aliases": {
|
|
"mydata": { }
|
|
}
|
|
},
|
|
"priority": 10,
|
|
"composed_of": ["component_template1", "other_component_template"],
|
|
"version": 3,
|
|
"_meta": {
|
|
"description": "my custom"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE _index_template/template_*
|
|
DELETE _component_template/*
|
|
--------------------------------------------------
|
|
// TEARDOWN
|
|
|
|
//////////////////////////
|
|
|
|
[[put-index-template-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_index_template/<index-template>`
|
|
|
|
|
|
[[put-index-template-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
Creates or updates 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]]
|
|
===== Getting templates
|
|
|
|
[[indices-get-template]]
|
|
=== Get index template API
|
|
++++
|
|
<titleabbrev>Get index template</titleabbrev>
|
|
++++
|
|
|
|
Returns information about one or more index templates.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_index_template/template_1
|
|
--------------------------------------------------
|
|
|
|
|
|
[[get-template-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_index_template/<index-template>`
|
|
|
|
|
|
[[get-template-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-template]
|
|
+
|
|
To return all index templates, omit this parameter or use a value of `*`.
|
|
|
|
|
|
[[get-template-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
|
|
[[get-template-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
|
|
[[get-template-api-wildcard-ex]]
|
|
===== Get index templates using a wildcard expression
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_index_template/temp*
|
|
--------------------------------------------------
|
|
|
|
|
|
[[get-template-api-all-ex]]
|
|
===== Get all index templates
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_index_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=master-timeout]
|
|
|
|
|
|
[[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]
|
|
|
|
`template`::
|
|
(Optional, object)
|
|
This is the template to be applied, may optionally include a `mappings`,
|
|
`settings`, or `aliases` configuration.
|
|
|
|
`composed_of`::
|
|
(Optional, array of strings)
|
|
An ordered list of component template names. Component templates will be merged in the order
|
|
specified, meaning that the last component template specified has the highest precedence. See the
|
|
<<indices-component-template,component template>> reference for information.
|
|
|
|
`priority`::
|
|
(Optional, integer)
|
|
Priority to determine index template precedence when a new index is created. The index template with
|
|
the highest priority is chosen. If no priority is specified the template is treated as though it is
|
|
of priority 0 (lowest priority).
|
|
This number is not automatically generated by {es}.
|
|
|
|
`version`::
|
|
(Optional, integer)
|
|
Version number used to manage index templates externally.
|
|
This number is not automatically generated by {es}.
|
|
|
|
`_meta`::
|
|
(Optional, object)
|
|
Optional user metadata about the index template. May have any contents.
|
|
This map is not automatically generated by {es}.
|
|
|
|
[[put-index-template-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
==== Composing multiple component templates
|
|
|
|
When multiple component templates are specified in the `composed_of` field for an index template,
|
|
they are merged in the order specified, meaning that later component templates override earlier
|
|
component templates.
|
|
|
|
For two component templates:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_component_template/template_with_2_shards
|
|
{
|
|
"template": {
|
|
"settings": {
|
|
"index.number_of_shards": 2
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_component_template/template_with_3_shards
|
|
{
|
|
"template": {
|
|
"settings": {
|
|
"index.number_of_shards": 3
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The order they are specified changes the number of shards for an index:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_index_template/template_1
|
|
{
|
|
"index_patterns": ["t*"],
|
|
"composed_of": ["template_with_2_shards", "template_with_3_shards"]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
In this case, an index matching `t*` will have three primary shards. If the order of composed
|
|
templates were reversed, the index would have two primary shards.
|
|
|
|
===== Index template with index aliases
|
|
|
|
You can include <<indices-aliases,index aliases>> in an index template.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT _index_template/template_1
|
|
{
|
|
"index_patterns" : ["te*"],
|
|
"template": {
|
|
"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]]
|
|
===== Indices matching multiple templates
|
|
|
|
When an index is created that matches multiple index templates, only the index template with the
|
|
highest priority is applied. For example:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_index_template/template_1
|
|
{
|
|
"index_patterns" : ["t*"],
|
|
"priority" : 0,
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 1,
|
|
"number_of_replicas": 0
|
|
},
|
|
"mappings" : {
|
|
"_source" : { "enabled" : false }
|
|
}
|
|
}
|
|
}
|
|
|
|
PUT /_index_template/template_2
|
|
{
|
|
"index_patterns" : ["te*"],
|
|
"priority" : 1,
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 2
|
|
},
|
|
"mappings" : {
|
|
"_source" : { "enabled" : true }
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
For indices that start with `te*`, `_source` will enabled, and the index will have two primary
|
|
shards and one replica, because only `template_2` will be applied.
|
|
|
|
NOTE: Multiple templates with overlapping index patterns at the same priority are not allowed, and
|
|
an error will be thrown when attempting to create a template matching an existing index template at
|
|
identical priorities.
|
|
|
|
|
|
[[versioning-templates]]
|
|
===== 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 /_index_template/template_1
|
|
{
|
|
"index_patterns" : ["foo", "bar"],
|
|
"priority" : 0,
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 1
|
|
}
|
|
},
|
|
"version": 123
|
|
}
|
|
--------------------------------------------------
|
|
|
|
To check the `version`, you can use the <<indices-get-template, get index template>> API.
|
|
|
|
[[template-metadata]]
|
|
===== Template metadata
|
|
|
|
You can use the `_meta` parameter to add optional metadata to an index template. This is a
|
|
user-defined map that can contain any data. This data will be stored in the cluster state however,
|
|
so keeping it short is preferrable.
|
|
|
|
The `_meta` parameter is completely optional and not automatically generated by {es}.
|
|
|
|
To unset `_meta`, replace the template without specifying one.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_index_template/template_1
|
|
{
|
|
"index_patterns": ["foo", "bar"],
|
|
"template": {
|
|
"settings" : {
|
|
"number_of_shards" : 3
|
|
}
|
|
},
|
|
"_meta": {
|
|
"description": "set number of shards to three",
|
|
"serialization": {
|
|
"class": "MyIndexTemplate",
|
|
"id": 17
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
To check the `_meta`, you can use the <<indices-get-template, get index template>> API.
|