diff --git a/docs/reference/glossary.asciidoc b/docs/reference/glossary.asciidoc index 7ff9c4acc53..ad603fa813b 100644 --- a/docs/reference/glossary.asciidoc +++ b/docs/reference/glossary.asciidoc @@ -27,6 +27,12 @@ same cluster name. Each cluster has a single master node which is chosen automatically by the cluster and which can be replaced if the current master node fails. +[[glossary-component-template]] component template :: +// tag::component-template-def[] +A building block for constructing <> that specifies index +<>, <>, and <>. +// end::component-template-def[] + [[glossary-ccr]] {ccr} (CCR):: The {ccr} feature enables you to replicate indices in remote clusters to your diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index c6a4d4ee4fb..12d612393bc 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -20,6 +20,8 @@ include::setup.asciidoc[] include::upgrade.asciidoc[] +include::indices/index-templates.asciidoc[] + include::data-streams/data-streams.asciidoc[] include::search/index.asciidoc[] diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index dc3793530f4..1ba42569e79 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -49,14 +49,21 @@ index settings, aliases, mappings, and index templates. * <> [discrete] -[[index-templates]] +[[index-templates-apis]] === Index templates: -* <> + +Index templates automatically apply settings, mappings, and aliases to new indices. +They are most often used to configure rolling indices for time series data to +ensure that each new index has the same configuration as the previous one. +The index template associated with a data stream configures its backing indices. +For more information, see <>. + * <> * <> * <> * <> * <> +* <> * <> * <> * <> @@ -103,6 +110,8 @@ include::indices/delete-index.asciidoc[] include::indices/delete-alias.asciidoc[] +include::indices/delete-component-template.asciidoc[] + include::indices/delete-index-template.asciidoc[] include::indices/flush.asciidoc[] @@ -111,6 +120,8 @@ include::indices/forcemerge.asciidoc[] include::indices/apis/freeze.asciidoc[] +include::indices/get-component-template.asciidoc[] + include::indices/get-field-mapping.asciidoc[] include::indices/get-index.asciidoc[] @@ -121,6 +132,8 @@ include::indices/get-settings.asciidoc[] include::indices/get-index-template.asciidoc[] +include::indices/get-index-template-v1.asciidoc[] + include::indices/get-mapping.asciidoc[] include::indices/alias-exists.asciidoc[] @@ -139,11 +152,11 @@ include::indices/template-exists.asciidoc[] include::indices/open-close.asciidoc[] -include::indices/index-templates.asciidoc[] +include::indices/put-index-template.asciidoc[] -include::indices/component-templates.asciidoc[] +include::indices/put-index-template-v1.asciidoc[] -include::indices/templates.asciidoc[] +include::indices/put-component-template.asciidoc[] include::indices/put-mapping.asciidoc[] diff --git a/docs/reference/indices/delete-component-template.asciidoc b/docs/reference/indices/delete-component-template.asciidoc new file mode 100644 index 00000000000..85f89160ec6 --- /dev/null +++ b/docs/reference/indices/delete-component-template.asciidoc @@ -0,0 +1,52 @@ +[[indices-delete-component-template]] +=== Delete component template API +++++ +Delete component template +++++ + +Deletes an existing component template. + +//// +[source,console] +-------------------------------------------------- +PUT _component_template/template_1 +{ + "template": { + "settings": { + "index.number_of_replicas": 0 + } + } +} +-------------------------------------------------- +// TESTSETUP +//// + +[source,console] +-------------------------------------------------- +DELETE _component_template/template_1 +-------------------------------------------------- + + +[[delete-component-template-api-request]] +==== {api-request-title} + +`DELETE /_template/` + + +[[delete-component-template-api-desc]] +==== {api-description-title} + +Use the delete component template API to delete one or more component templates +Component templates are building blocks for constructing <> +that specify index mappings, settings, and aliases. + +[[delete-component-template-api-path-params]] +==== {api-path-parms-title} + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=component-template] + + +[[delete-component-template-api-query-params]] +==== {api-query-parms-title} + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] diff --git a/docs/reference/indices/delete-index-template.asciidoc b/docs/reference/indices/delete-index-template.asciidoc index 5c2da119780..75e9c1c5fed 100644 --- a/docs/reference/indices/delete-index-template.asciidoc +++ b/docs/reference/indices/delete-index-template.asciidoc @@ -4,7 +4,7 @@ Delete index template ++++ -Deletes an existing index. +Deletes an index template. //// [source,console] @@ -35,9 +35,9 @@ DELETE /_template/template_1 [[delete-template-api-desc]] ==== {api-description-title} -Use the delete index template API to delete one or more index templates - -include::templates.asciidoc[tag=index-template-def] +Use the delete index template API to delete one or more index templates. +Index templates define <>, <>, +and <> that can be applied automatically to new indices. [[delete-template-api-path-params]] diff --git a/docs/reference/indices/get-component-template.asciidoc b/docs/reference/indices/get-component-template.asciidoc new file mode 100644 index 00000000000..52eca0b0ab8 --- /dev/null +++ b/docs/reference/indices/get-component-template.asciidoc @@ -0,0 +1,88 @@ +[[getting-component-templates]] +=== Get component template API +++++ +Get component template +++++ + +Retrieves information about one or more component templates. + +////////////////////////// + +[source,console] +-------------------------------------------------- +PUT /_component_template/template_1 +{ + "template": { + "settings": { + "index.number_of_replicas": 0 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + } + } + } + } +} +-------------------------------------------------- +// TESTSETUP + +[source,console] +-------------------------------------------------- +DELETE /_component_template/template_* +-------------------------------------------------- +// TEARDOWN + +////////////////////////// + +[source,console] +-------------------------------------------------- +GET /_component_template/template_1 +-------------------------------------------------- + +[[get-component-template-api-request]] +==== {api-request-title} + +`GET /_component-template/` + + +[[get-component-template-api-path-params]] +==== {api-path-parms-title} + +`` +(Optional, string) +Comma-separated list of component template names used to limit the request. +Wildcard (`*`) expressions are supported. + + +[[get-component-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-component-template-api-example]] +==== {api-examples-title} + + +[[get-component-template-api-wildcard-ex]] +===== Get component templates using a wildcard expression + +[source,console] +-------------------------------------------------- +GET /_component_template/temp* +-------------------------------------------------- + + +[[get-component-template-api-all-ex]] +===== Get all component templates + +[source,console] +-------------------------------------------------- +GET /_component_template +-------------------------------------------------- diff --git a/docs/reference/indices/get-index-template-v1.asciidoc b/docs/reference/indices/get-index-template-v1.asciidoc new file mode 100644 index 00000000000..c7c389f49c4 --- /dev/null +++ b/docs/reference/indices/get-index-template-v1.asciidoc @@ -0,0 +1,93 @@ +[[indices-get-template-v1]] +=== Get index template API +++++ +Get index template (legacy) +++++ + +IMPORTANT: This documentation is about legacy index templates, +which are deprecated and will be replaced by the composable templates introduced in {es} 7.8. +For information about composable templates, <>. + +Retrieves information about one or more index templates. + +//// +[source,console] +-------------------------------------------------- +PUT _template/template_1 +{ + "index_patterns" : ["te*"], + "settings": { + "number_of_shards": 1 + } +} +-------------------------------------------------- +// TESTSETUP + +[source,console] +-------------------------------------------------- +DELETE _template/template_1 +-------------------------------------------------- +// TEARDOWN + +//// + +[source,console] +-------------------------------------------------- +GET /_template/template_1 +-------------------------------------------------- + + +[[get-template-v1-api-request]] +==== {api-request-title} + +`GET /_template/` + + +[[get-template-v1-api-path-params]] +==== {api-path-parms-title} + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-template] ++ +To return all index templates, omit this parameter +or use a value of `_all` or `*`. + + +[[get-template-v1-api-query-params]] +==== {api-query-parms-title} + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings] + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local] + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] + + +[[get-template-v1-api-example]] +==== {api-examples-title} + + +[[get-template-v1-api-multiple-ex]] +===== Get multiple index templates + +[source,console] +-------------------------------------------------- +GET /_template/template_1,template_2 +-------------------------------------------------- + + +[[get-template-v1-api-wildcard-ex]] +===== Get index templates using a wildcard expression + +[source,console] +-------------------------------------------------- +GET /_template/temp* +-------------------------------------------------- + + +[[get-template-v1-api-all-ex]] +===== Get all index templates + +[source,console] +-------------------------------------------------- +GET /_template +-------------------------------------------------- diff --git a/docs/reference/indices/get-index-template.asciidoc b/docs/reference/indices/get-index-template.asciidoc index c2a47505159..f38d237c38e 100644 --- a/docs/reference/indices/get-index-template.asciidoc +++ b/docs/reference/indices/get-index-template.asciidoc @@ -1,5 +1,5 @@ -[[indices-get-template-v1]] -=== Get index template API +[[indices-get-template]] +=== Get index template API [[getting-templates]] ++++ Get index template ++++ @@ -7,13 +7,17 @@ Returns information about one or more index templates. //// + [source,console] -------------------------------------------------- -PUT _template/template_1 +PUT /_index_template/template_1 { - "index_patterns" : ["te*"], - "settings": { - "number_of_shards": 1 + "index_patterns" : ["te*"], + "priority" : 1, + "template": { + "settings" : { + "number_of_shards" : 2 + } } } -------------------------------------------------- @@ -21,7 +25,7 @@ PUT _template/template_1 [source,console] -------------------------------------------------- -DELETE _template/template_1 +DELETE _index_template/template_* -------------------------------------------------- // TEARDOWN @@ -29,63 +33,52 @@ DELETE _template/template_1 [source,console] -------------------------------------------------- -GET /_template/template_1 +GET /_index_template/template_1 -------------------------------------------------- - -[[get-template-v1-api-request]] +[[get-template-api-request]] ==== {api-request-title} -`GET /_template/` +`GET /_index_template/` -[[get-template-v1-api-path-params]] +[[get-template-api-path-params]] ==== {api-path-parms-title} -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-template] +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-template] + -To return all index templates, omit this parameter -or use a value of `_all` or `*`. +To retrieve all index templates, omit this parameter or use a value of `*`. -[[get-template-v1-api-query-params]] +[[get-template-api-query-params]] ==== {api-query-parms-title} -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings] +include::{docdir}/rest-api/common-parms.asciidoc[tag=flat-settings] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=include-type-name] include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local] -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] -[[get-template-v1-api-example]] +[[get-template-api-example]] ==== {api-examples-title} -[[get-template-v1-api-multiple-ex]] -===== Get multiple index templates - -[source,console] --------------------------------------------------- -GET /_template/template_1,template_2 --------------------------------------------------- - - -[[get-template-v1-api-wildcard-ex]] +[[get-template-api-wildcard-ex]] ===== Get index templates using a wildcard expression [source,console] -------------------------------------------------- -GET /_template/temp* +GET /_index_template/temp* -------------------------------------------------- -[[get-template-v1-api-all-ex]] +[[get-template-api-all-ex]] ===== Get all index templates [source,console] -------------------------------------------------- -GET /_template --------------------------------------------------- \ No newline at end of file +GET /_index_template +-------------------------------------------------- diff --git a/docs/reference/indices/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc index 8335a7d059f..5a47f3cd9a0 100644 --- a/docs/reference/indices/index-templates.asciidoc +++ b/docs/reference/indices/index-templates.asciidoc @@ -1,18 +1,9 @@ -[[indices-templates]] -=== Index templates -++++ -Index template -++++ +[[index-templates]] += Index templates -This documentation is about composable templates. For legacy templates please see the -<>. - -[NOTE] -==== -In {es} 7.8 composable templates were introduced. When a composable template matches a given index -it always takes precedence over a legacy template. If no composable template matches, a legacy -template may still match and be applied. -==== +NOTE: This topic describes the composable index templates introduced in {es} 7.8. +For information about how index templates worked previously, +see the <>. [[getting]] An index template is a way to tell {es} how to configure an index when it is created. @@ -29,6 +20,10 @@ specify settings, mappings, and aliases. If a new data stream or index matches more than one index template, the index template with the highest priority is used. +When a composable template matches a given index +it always takes precedence over a legacy template. If no composable template matches, a legacy +template may still match and be applied. + 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. @@ -92,7 +87,7 @@ PUT _index_template/template_1 -------------------------------------------------- // TESTSETUP -////////////////////////// +//// [source,console] -------------------------------------------------- @@ -101,516 +96,6 @@ DELETE _component_template/* -------------------------------------------------- // TEARDOWN -////////////////////////// +//// -[[simulating-templates]] -==== Simulating template composition - -Since templates can be composed not only of multiple component templates, but also the index -template itself, there are two simulation APIs to determine what the resulting index settings will -be. - -To simulate the settings that would be applied to a matching index name: - -[source,console] --------------------------------------------------- -POST /_index_template/_simulate_index/myindex --------------------------------------------------- - -To simulate the settings that would be applied from a particular template: - -[source,console] --------------------------------------------------- -POST /_index_template/_simulate/template_1 - -POST /_index_template/_simulate -{ - "index_patterns": ["foo"], - "template": { - "settings": { - "number_of_replicas": 0 - } - } -} --------------------------------------------------- - - -Here's an example demonstrating simulating both an index name and template name: - -[source,console] --------------------------------------------------- -PUT /_component_template/ct1 <1> -{ - "template": { - "settings": { - "index.number_of_shards": 2 - } - } -} - -PUT /_component_template/ct2 <2> -{ - "template": { - "settings": { - "index.number_of_replicas": 0 - }, - "mappings": { - "properties": { - "@timestamp": { - "type": "date" - } - } - } - } -} - -PUT /_index_template/final-template <3> -{ - "index_patterns": ["logdata-*"], - "composed_of": ["ct1", "ct2"], - "priority": 5 -} - -POST /_index_template/_simulate_index/logdata-2019-02-01 <4> - -POST /_index_template/_simulate/final-template <5> - -POST /_index_template/_simulate <6> -{ - "index_patterns": ["logdata-*"], - "composed_of": ["ct2"], - "priority": 10, - "template": { - "settings": { - "index.number_of_replicas": 1 - } - } -} --------------------------------------------------- -<1> Creating a component template (ct1) setting the number of shards to two -<2> Creating another component template (ct2) setting the number of replicas to zero with mappings -<3> Creating an index template called "final" template using ct1 and ct2 -<4> Simulate the settings that would be applied for a new index "logdata-2019-02-01" -<5> Simulate the settings composed using the "final-template" index template -<6> Simulate the settings composed using a custom specified template - -The output of the simulate API from the last example call looks like: - -[source,console-result] ---------------------------------------------------------- -{ - "template" : { - "settings" : { - "index" : { - "number_of_replicas" : "1" <1> - } - }, - "mappings" : { - "properties" : { - "@timestamp" : { <2> - "type" : "date" - } - } - }, - "aliases" : { } - }, - "overlapping" : [ <3> - { - "name" : "final-template", - "index_patterns" : [ - "logdata-*" - ] - } - ] -} ---------------------------------------------------------- -<1> The number of replicas from the simulated template body -<2> The `@timestamp` field inherited from the "ct2" component template -<3> Any overlapping templates that would have matched, but have lower priority - -When simulating a template and specifying a template in the body of the request, the simulated -template is not added to the existing templates, it is only used for the simulation. - -[[indices-put-template]] -=== Put index template API -++++ -Put index template -++++ - -Creates or updates an index template. - -[source,console] --------------------------------------------------- -PUT /_index_template/template_1 -{ - "index_patterns" : ["te*"], - "priority" : 1, - "template": { - "settings" : { - "number_of_shards" : 2 - } - } -} --------------------------------------------------- - -[[put-index-template-api-request]] -==== {api-request-title} - -`PUT /_index_template/` - - -[[put-index-template-api-desc]] -==== {api-description-title} - -// tag::index-template-def[] -Index templates define <> and <> that you can -automatically apply when creating new indices. - -For data streams, these settings and mappings are applied to the stream's backing indices when created. - -{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 data stream or index creation. Changes to index templates do not affect -existing indices, including the existing backing indices of a data stream. -Settings and mappings specified in <> 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. - -[[put-index-template-api-path-params]] -==== {api-path-parms-title} - -``:: -(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 data streams and indices during creation. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases] -+ -NOTE: You cannot add data streams to an index alias. - -[xpack]#`data_stream`#:: -(Optional, object) -Indicates whether the template is used to create data streams and their backing -indices. If so, use an empty object as the argument: + -`data_stream: { }`. -+ -Data streams require a matching index template with a `data_stream` object. -See <>. - -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 are merged in the order -specified, meaning that the last component template specified has the highest precedence. See -<> for an example. - -`priority`:: -(Optional, integer) -Priority to determine index template precedence when a new data stream or 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} - -===== Index template with index aliases - -You can include <> 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 <> 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 <> API. - -[[data-stream-definition]] -===== Data stream definition - -If an index template should create data streams, the template must include an -empty `data_stream` object. See <>. - -[source,console] --------------------------------------------------- -PUT /_index_template/template_1 -{ - "index_patterns": ["logs-*"], - "data_stream": { } -} --------------------------------------------------- - -[[multiple-component-templates]] -===== Composing aliases, mappings, and settings - -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. Any mappings, settings, or aliases from the parent index template are merged -in next. Finally, any configuration on the index request itself is merged. - -In this example, the order of the two component templates changes the number of shards for an -index: - -[source,console] --------------------------------------------------- -PUT /_component_template/template_with_2_shards -{ - "template": { - "settings": { - "index.number_of_shards": 2 - } - } -} - -PUT /_component_template/template_with_3_shards -{ - "template": { - "settings": { - "index.number_of_shards": 3 - } - } -} - -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. - -Mapping definitions are merged recursively, which means that later mapping components can -introduce new field mappings and update the mapping configuration. If a field mapping is -already contained in an earlier component, its definition will be completely overwritten -by the later one. - -This recursive merging strategy applies not only to field mappings, but also root options like -`dynamic_templates` and `meta`. If an earlier component contains a `dynamic_templates` block, -then by default new `dynamic_templates` entries are appended onto the end. If an entry already -exists with the same key, then it is overwritten by the new definition. - -[[indices-get-template]] -=== Get index template API [[getting-templates]] -++++ -Get index template -++++ - -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/` - - -[[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 --------------------------------------------------- +include::simulate-multi-component-templates.asciidoc[] diff --git a/docs/reference/indices/put-component-template.asciidoc b/docs/reference/indices/put-component-template.asciidoc new file mode 100644 index 00000000000..024d22a8649 --- /dev/null +++ b/docs/reference/indices/put-component-template.asciidoc @@ -0,0 +1,212 @@ +[[indices-component-template]] +=== Put component template API +++++ +Put component template +++++ + +Creates or updates a component template. +Component templates are building blocks for constructing <>. +that specify index <>, <>, +and <>. + +[source,console] +-------------------------------------------------- +PUT _component_template/template_1 +{ + "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" + } + } + } + } +} +-------------------------------------------------- +// TESTSETUP + +////////////////////////// + +[source,console] +-------------------------------------------------- +DELETE _component_template/template_* +-------------------------------------------------- +// TEARDOWN + +////////////////////////// + +[[put-component-template-api-request]] +==== {api-request-title} + +`PUT /_component_template/` + + +[[put-component-template-api-desc]] +==== {api-description-title} + +An index template can be composed of multiple component templates. +To use a component template, specify it in an index template's `composed_of` list. +Component templates are only applied to new data streams and indices +as part of a matching index template. + +Settings and mappings specified directly in the index template or the <> +request override any settings or mappings specified in a component template. + +Component templates are only used during index creation. For data streams, this +includes data stream creation and the creation of a stream's backing indices. +Changes to component templates do not +affect existing indices, including a stream's backing indices. + +===== Comments in component templates +You can use C-style /* */ block comments in component templates. +You can include comments anywhere in the request body, +except before the opening curly bracket. + +[[put-component-template-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Name of the component template to create. + + +[[put-component-template-api-query-params]] +==== {api-query-parms-title} + +`create`:: +(Optional, boolean) +If `true`, this request cannot replace or update existing component templates. +Defaults to `false`. + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] + +[[put-component-template-api-request-body]] +==== {api-request-body-title} + +`template`:: +(Required, object) +This is the template to be applied, may optionally include a `mappings`, +`settings`, or `aliases` configuration. + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=aliases] ++ +NOTE: You cannot add data streams to an index alias. + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings] + +include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=settings] + +`version`:: +(Optional, integer) +Version number used to manage component templates externally. +This number is not automatically generated or incremented by {es}. + +`_meta`:: +(Optional, object) +Optional user metadata about the component template. May have any contents. +This map is not automatically generated by {es}. + +[[put-component-template-api-example]] +==== {api-examples-title} + +===== Component template with index aliases + +You can include <> in a component template. + +[source,console] +-------------------------------------------------- +PUT _component_template/template_1 +{ + "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. + +[[applying-component-templates]] +===== Applying component templates + +You cannot directly apply a component template to a data stream or index. +To be applied, a component template must be included in an index template's `composed_of` list. See <>. + +[[component-templates-version]] +===== Component template versioning + +You can use the `version` parameter to add a version number to a component template. +External systems can use these version numbers to simplify template management. + +The `version` parameter is optional and not automatically generated or used by {es}. + +To unset a `version`, replace the template without specifying one. + +[source,console] +-------------------------------------------------- +PUT /_component_template/template_1 +{ + "template": { + "settings" : { + "number_of_shards" : 1 + } + }, + "version": 123 +} +-------------------------------------------------- + +To check the `version`, you can use the <>. + +[[component-templates-metadata]] +===== Component template metadata + +You can use the `_meta` parameter to add arbitrary metadata to a component template. +This user-defined object is stored in the cluster state, +so keeping it short is preferrable. + +The `_meta` parameter is optional and not automatically generated or used by {es}. + +To unset `_meta`, replace the template without specifying one. + +[source,console] +-------------------------------------------------- +PUT /_component_template/template_1 +{ + "template": { + "settings" : { + "number_of_shards" : 1 + } + }, + "_meta": { + "description": "set number of shards to one", + "serialization": { + "class": "MyComponentTemplate", + "id": 10 + } + } +} +-------------------------------------------------- + +To check the `_meta`, you can use the <> API. diff --git a/docs/reference/indices/templates.asciidoc b/docs/reference/indices/put-index-template-v1.asciidoc similarity index 92% rename from docs/reference/indices/templates.asciidoc rename to docs/reference/indices/put-index-template-v1.asciidoc index 1a4183435dc..7ce153f3000 100644 --- a/docs/reference/indices/templates.asciidoc +++ b/docs/reference/indices/put-index-template-v1.asciidoc @@ -1,18 +1,12 @@ [[indices-templates-v1]] === Put index template API ++++ -Put index template +Put index template (legacy) ++++ -This documentation is about legacy index templates, which are deprecated and will be replaced by -composable templates. For information about composable templates, see <>. - -[NOTE] -==== -In {es} 7.8 composable templates were introduced. When a composable template matches a given index -it always takes precedence over a legacy template. If no composable template matches, a legacy -template may still match and be applied. -==== +IMPORTANT: This documentation is about legacy index templates, +which are deprecated and will be replaced by the composable templates introduced in {es} 7.8. +For information about composable templates, <>. Creates or updates an index template. @@ -64,12 +58,14 @@ DELETE _template/template_* Use the PUT index template API to create or update an index template. -// tag::index-template-def[] Index templates define <> and <> 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: Composable templates always take precedence over legacy templates. +If no composable template matches a new index, +matching legacy templates are applied according to their order. Index templates are only applied during index creation. Changes to index templates do not affect existing indices. diff --git a/docs/reference/indices/put-index-template.asciidoc b/docs/reference/indices/put-index-template.asciidoc new file mode 100644 index 00000000000..97331e5370c --- /dev/null +++ b/docs/reference/indices/put-index-template.asciidoc @@ -0,0 +1,337 @@ +[[indices-put-template]] +=== Put index template API +++++ +Put index template +++++ + +Creates or updates an index template. +Index templates define <>, <>, +and <> that can be applied automatically to new indices. + +[source,console] +-------------------------------------------------- +PUT /_index_template/template_1 +{ + "index_patterns" : ["te*"], + "priority" : 1, + "template": { + "settings" : { + "number_of_shards" : 2 + } + } +} +-------------------------------------------------- +// TESTSETUP + +////////////////////////// + +[source,console] +-------------------------------------------------- +DELETE _index_template/template_* +-------------------------------------------------- +// TEARDOWN + +////////////////////////// + +[[put-index-template-api-request]] +==== {api-request-title} + +`PUT /_index_template/` + + +[[put-index-template-api-desc]] +==== {api-description-title} + +{es} applies templates to new indices based on an +wildcard pattern that matches the index name. + +Index templates are applied during data stream or index creation. +For data streams, these settings and mappings are applied when the stream's backing indices are created. + +Settings and mappings specified in a <> +request override any settings or mappings specified in an index template. + +Changes to index templates do not affect +existing indices, including the existing backing indices of a data stream. + +===== 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. + +[[put-index-template-api-path-params]] +==== {api-path-parms-title} + +``:: +(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 data streams and indices during creation. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases] ++ +NOTE: You cannot add data streams to an index alias. + +[xpack]#`data_stream`#:: +(Optional, object) +Indicates whether the template is used to create data streams and their backing +indices. If so, use an empty object as the argument: + +`data_stream: { }`. ++ +Data streams require a matching index template with a `data_stream` object. +See <>. + +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 are merged in the order +specified, meaning that the last component template specified has the highest precedence. See +<> for an example. + +`priority`:: +(Optional, integer) +Priority to determine index template precedence when a new data stream or 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} + +===== Index template with index aliases + +You can include <> 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]] +===== Multiple matching templates + +If multiple index templates match the name of a new index or data stream, +the template with the highest priority is used. 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 a version number to an index template. +External systems can use these version numbers to simplify template management. + +The `version` parameter is optional and not automatically generated or used 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 <> API. + +[[template-metadata]] +===== Template metadata + +You can use the `_meta` parameter to add arbitrary metadata to an index template. +This user-defined object is stored in the cluster state, +so keeping it short is preferrable. + +The `_meta` parameter is optional and not automatically generated or used 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 <> API. + +[[data-stream-definition]] +===== Data stream definition + +To use an index template for a data stream, the template must include an empty `data_stream` object. +Data stream templates are only used for a stream's backing indices, +they are not applied to regular indices. +See <>. + +[source,console] +-------------------------------------------------- +PUT /_index_template/template_1 +{ + "index_patterns": ["logs-*"], + "data_stream": { } +} +-------------------------------------------------- + +[[multiple-component-templates]] +===== Composing aliases, mappings, and settings + +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. Any mappings, settings, or aliases from the parent index template are merged +in next. Finally, any configuration on the index request itself is merged. + +In this example, the order of the two component templates changes the number of shards for an +index: + +[source,console] +-------------------------------------------------- +PUT /_component_template/template_with_2_shards +{ + "template": { + "settings": { + "index.number_of_shards": 2 + } + } +} + +PUT /_component_template/template_with_3_shards +{ + "template": { + "settings": { + "index.number_of_shards": 3 + } + } +} + +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. + +Mapping definitions are merged recursively, which means that later mapping components can +introduce new field mappings and update the mapping configuration. If a field mapping is +already contained in an earlier component, its definition will be completely overwritten +by the later one. + +This recursive merging strategy applies not only to field mappings, but also root options like +`dynamic_templates` and `meta`. If an earlier component contains a `dynamic_templates` block, +then by default new `dynamic_templates` entries are appended onto the end. If an entry already +exists with the same key, then it is overwritten by the new definition. diff --git a/docs/reference/indices/simulate-multi-component-templates.asciidoc b/docs/reference/indices/simulate-multi-component-templates.asciidoc new file mode 100644 index 00000000000..861330d272e --- /dev/null +++ b/docs/reference/indices/simulate-multi-component-templates.asciidoc @@ -0,0 +1,124 @@ +[[simulate-multi-component-templates]] +== Simulate multi-component templates + +Since templates can be composed not only of multiple component templates, but also the index +template itself, there are two simulation APIs to determine what the resulting index settings will +be. + +To simulate the settings that would be applied to a particular index name: + +//// +[source,console] +-------------------------------------------------- +PUT /_index_template/template_1 +{ + "index_patterns" : ["my*"], + "priority" : 1, + "template": { + "settings" : { + "number_of_shards" : 2 + } + } +} +-------------------------------------------------- +// TESTSETUP + +[source,console] +-------------------------------------------------- +DELETE /_index_template/template_1 +-------------------------------------------------- +// TEARDOWN + +//// + +[source,console] +-------------------------------------------------- +POST /_index_template/_simulate_index/myindex +-------------------------------------------------- + +To simulate the settings that would be applied from an existing template: + +[source,console] +-------------------------------------------------- +POST /_index_template/_simulate/template_1 +-------------------------------------------------- + +You can also specify a template definition in the simulate request. +This enables you to verify that settings will be applied as expected before you add a new template. + +[source,console] +-------------------------------------------------- +PUT /_component_template/ct1 +{ + "template": { + "settings": { + "index.number_of_shards": 2 + } + } +} + +PUT /_component_template/ct2 +{ + "template": { + "settings": { + "index.number_of_replicas": 0 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + } + } + } + } +} + +POST /_index_template/_simulate +{ + "index_patterns": ["my*"], + "template": { + "settings" : { + "index.number_of_shards" : 3 + } + }, + "composed_of": ["ct1", "ct2"] +} +-------------------------------------------------- + + +The response shows the settings, mappings, and aliases that would be applied to matching indices, +and any overlapping templates whose configuration would be superseded by the simulated template body +or higher-priority templates. + +[source,console-result] +--------------------------------------------------------- +{ + "template" : { + "settings" : { + "index" : { + "number_of_shards" : "3", <1> + "number_of_replicas" : "0" + } + }, + "mappings" : { + "properties" : { + "@timestamp" : { + "type" : "date" <2> + } + } + }, + "aliases" : { } + }, + "overlapping" : [ + { + "name" : "template_1", <3> + "index_patterns" : [ + "my*" + ] + } + ] +} +--------------------------------------------------------- +<1> The number of shards from the simulated template body +<2> The `@timestamp` field inherited from the `ct2` component template +<3> Any overlapping templates that would have matched, but have lower priority diff --git a/docs/reference/indices/template-exists.asciidoc b/docs/reference/indices/template-exists.asciidoc index 5c9f13dae48..7c125863800 100644 --- a/docs/reference/indices/template-exists.asciidoc +++ b/docs/reference/indices/template-exists.asciidoc @@ -4,7 +4,7 @@ Index template exists ++++ -Checks if an index template exists. +Checks if an <> exists. @@ -26,8 +26,8 @@ HEAD /_template/template_1 Use the index template exists API to determine whether one or more index templates exist. -include::templates.asciidoc[tag=index-template-def] - +Index templates define <>, <>, +and <> that can be applied automatically to new indices. [[template-exists-api-path-params]] ==== {api-path-parms-title} diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index f5d442dbc74..9255de3dffb 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -907,6 +907,11 @@ See <>. The `xpack.sql.enabled` setting has been deprecated. SQL access is always enabled. +[role="exclude",id="indices-templates"] +=== Index templates [[getting]] + +See <>. + //// [role="exclude",id="search-request-body"] === Request body search diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index d68424059a7..3c2339f0d27 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -535,6 +535,13 @@ Comma-separated list or wildcard expression of index template names used to limit the request. end::index-template[] +tag::component-template[] +``:: +(Required, string) +Comma-separated list or wildcard expression of component template names +used to limit the request. +end::component-template[] + tag::lenient[] `lenient`:: (Optional, boolean) If `true`, format-based query failures (such as