diff --git a/docs/reference/glossary.asciidoc b/docs/reference/glossary.asciidoc index d4c3c9d90282d..74c3ad59f8f6c 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 0b64c86c83151..f301cd090bce8 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::search/index.asciidoc[] include::query-dsl.asciidoc[] diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index c792a9f5da350..786da3cb8ba42 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -48,14 +48,20 @@ 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. +For more information, see <>. + * <> * <> * <> * <> * <> +* <> * <> [discrete] @@ -97,6 +103,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[] @@ -105,6 +113,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[] @@ -115,6 +125,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[] @@ -133,11 +145,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 0000000000000..85f89160ec65f --- /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 5c2da11978049..75e9c1c5fed5b 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 0000000000000..52eca0b0ab820 --- /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 0000000000000..c7c389f49c4a3 --- /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 c113e3b8a6372..f38d237c38e43 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 +GET /_index_template -------------------------------------------------- diff --git a/docs/reference/indices/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc index 00ff3ba4986ef..625144a9c5089 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. Templates are @@ -25,11 +16,6 @@ aliases. You use component templates to construct index templates, they aren't d 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 _component_template/component_template1 @@ -93,7 +79,7 @@ PUT _index_template/template_1 -------------------------------------------------- // TESTSETUP -////////////////////////// +//// [source,console] -------------------------------------------------- @@ -102,345 +88,16 @@ DELETE _component_template/* -------------------------------------------------- // TEARDOWN -////////////////////////// - -[[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. {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 <> 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 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 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 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}. +== Index template and settings priority -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. - -[[multiple-component-templates]] -===== 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, the order they are specified 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. - -[[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* --------------------------------------------------- +If a new 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. -[[get-template-api-all-ex]] -===== Get all index templates +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] --------------------------------------------------- -GET /_index_template --------------------------------------------------- \ No newline at end of file diff --git a/docs/reference/indices/put-component-template.asciidoc b/docs/reference/indices/put-component-template.asciidoc new file mode 100644 index 0000000000000..7391f5f066cc0 --- /dev/null +++ b/docs/reference/indices/put-component-template.asciidoc @@ -0,0 +1,209 @@ +[[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 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. +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] + +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 an 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 48c28d1154320..45d9b44e2634c 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 0000000000000..d441a786989ef --- /dev/null +++ b/docs/reference/indices/put-index-template.asciidoc @@ -0,0 +1,307 @@ +[[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 index creation. + +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. + +===== 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 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 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 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, +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. + +[[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/template-exists.asciidoc b/docs/reference/indices/template-exists.asciidoc index 5c9f13dae4872..7c12586380057 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 996367980c5ab..79cb84d8ae8f4 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -917,6 +917,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 977fe7eeb9727..a7be361fac649 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -530,6 +530,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