From b033791ef59dd0fd03b575abd31c9f69e9edfaa6 Mon Sep 17 00:00:00 2001 From: debadair Date: Wed, 3 Jun 2020 17:14:20 -0700 Subject: [PATCH 1/3] [DOCS] Fix chunking in template API docs (#57632) * [DOCS] Fix chunking in template API docs * Fixed typo in xref * Added anchor for beats xref * Fixed example --- docs/reference/indices.asciidoc | 5 +- .../indices/component-templates.asciidoc | 122 +++-- .../indices/index-templates.asciidoc | 423 +++++++++++++----- 3 files changed, 374 insertions(+), 176 deletions(-) diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index 6c54cd5392a06..fe89de0e43d7c 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -51,8 +51,11 @@ index settings, aliases, mappings, and index templates. [[index-templates]] === Index templates: * <> -* <> +* <> * <> +* <> +* <> +* <> * <> [float] diff --git a/docs/reference/indices/component-templates.asciidoc b/docs/reference/indices/component-templates.asciidoc index b12a4daf98c9b..936d34147ea1b 100644 --- a/docs/reference/indices/component-templates.asciidoc +++ b/docs/reference/indices/component-templates.asciidoc @@ -1,7 +1,7 @@ [[indices-component-template]] -=== Component template API +=== Put component template API ++++ -Component template +Put component template ++++ Component templates are building blocks that specify mappings, settings, or alias configuration, but @@ -74,66 +74,6 @@ 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. -[[getting-component-templates]] -===== Getting component templates - -=== Get component template API -++++ -Get component template -++++ - -Returns information about one or more component templates. - -[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} - -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-template] -+ -To return all component templates, omit this parameter or use a value of `*`. - - -[[get-component-template-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-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 --------------------------------------------------- - [[put-component-template-api-path-params]] ==== {api-path-parms-title} @@ -270,3 +210,61 @@ PUT /_component_template/template_1 -------------------------------------------------- To check the `_meta`, you can use the <> API. + +[[getting-component-templates]] +=== Get component template API +++++ +Get component template +++++ + +Returns information about one or more component templates. + +[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} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-template] ++ +To return all component templates, omit this parameter or use a value of `*`. + + +[[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/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc index 49ddd83d3fe71..1d92583d89dff 100644 --- a/docs/reference/indices/index-templates.asciidoc +++ b/docs/reference/indices/index-templates.asciidoc @@ -1,5 +1,5 @@ [[indices-templates]] -=== Index template API +=== Index templates ++++ Index template ++++ @@ -14,6 +14,7 @@ it always takes precedence over a legacy template. If no composable template mat template may still match and be applied. ==== +[[getting]] An index template is a way to tell {es} how to configure an index when it is created. Templates are configured prior to index creation and then when an index is created either manually or through indexing a document, the template settings are used as a basis for creating the index. @@ -26,11 +27,37 @@ 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, +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 +{ + "template": { + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + } + } + } + } +} + +PUT _component_template/other_component_template +{ + "template": { + "mappings": { + "properties": { + "ip_address": { + "type": "ip" + } + } + } + } +} + PUT _index_template/template_1 { "index_patterns": ["te*", "bar*"], @@ -70,99 +97,185 @@ PUT _index_template/template_1 [source,console] -------------------------------------------------- -DELETE _index_template/template_* +DELETE _index_template/* DELETE _component_template/* -------------------------------------------------- // TEARDOWN ////////////////////////// -[[put-index-template-api-request]] -==== {api-request-title} - -`PUT /_index_template/` +[[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. -[[put-index-template-api-desc]] -==== {api-description-title} +To simulate the settings that would be applied to a matching index name: -Creates or updates 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[] +[source,console] +-------------------------------------------------- +POST /_index_template/_simulate_index/myindex +-------------------------------------------------- -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. +To simulate the settings that would be applied from a particular 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. +[source,console] +-------------------------------------------------- +POST /_index_template/_simulate/template_1 -[[getting]] -===== Getting templates +POST /_index_template/_simulate +{ + "index_patterns": ["foo"], + "template": { + "settings": { + "number_of_replicas": 0 + } + } +} +-------------------------------------------------- -[[indices-get-template]] -=== Get index template API -++++ -Get index template -++++ -Returns information about one or more index templates. +Here's an example demonstrating simulating both an index name and template name: [source,console] -------------------------------------------------- -GET /_index_template/template_1 --------------------------------------------------- - +PUT /_component_template/ct1 <1> +{ + "template": { + "settings": { + "index.number_of_shards": 2 + } + } +} -[[get-template-api-request]] -==== {api-request-title} +PUT /_component_template/ct2 <2> +{ + "template": { + "settings": { + "index.number_of_replicas": 0 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + } + } + } + } +} -`GET /_index_template/` +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> -[[get-template-api-path-params]] -==== {api-path-parms-title} +POST /_index_template/_simulate/final-template <5> -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 `*`. +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: -[[get-template-api-query-params]] -==== {api-query-parms-title} +[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 -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings] +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. -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local] +[[indices-put-template]] +=== Put index template API +++++ +Put index template +++++ -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] +Creates or updates an index template. +[source,console] +-------------------------------------------------- +PUT /_index_template/template_1 +{ + "index_patterns" : ["te*"], + "priority" : 1, + "template": { + "settings" : { + "number_of_shards" : 2 + } + } +} +-------------------------------------------------- -[[get-template-api-example]] -==== {api-examples-title} +[[put-index-template-api-request]] +==== {api-request-title} +`PUT /_index_template/` -[[get-template-api-wildcard-ex]] -===== Get index templates using a wildcard expression -[source,console] --------------------------------------------------- -GET /_index_template/temp* --------------------------------------------------- +[[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[] -[[get-template-api-all-ex]] -===== Get all index templates +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. -[source,console] --------------------------------------------------- -GET /_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} @@ -179,7 +292,7 @@ Name of the index template to create. (Optional, boolean) If `true`, this request cannot replace or update existing index templates. Defaults to `false`. -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] [[put-index-template-api-request-body]] @@ -190,11 +303,11 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] Array of wildcard expressions used to match the names of indices during creation. -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=aliases] +include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases] -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings] +include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings] -include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=settings] +include::{docdir}/rest-api/common-parms.asciidoc[tag=settings] `template`:: (Optional, object) @@ -203,9 +316,9 @@ This is the template to be applied, may optionally include a `mappings`, `composed_of`:: (Optional, array of strings) -An ordered list of component template names. Component templates will be merged in the order -specified, meaning that the last component template specified has the highest precedence. See the -<> reference for information. +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) @@ -227,52 +340,6 @@ This map is not automatically generated by {es}. [[put-index-template-api-example]] ==== {api-examples-title} -==== Composing multiple component templates - -When multiple component templates are specified in the `composed_of` field for an index template, -they are merged in the order specified, meaning that later component templates override earlier -component templates. - -For two component templates: - -[source,console] --------------------------------------------------- -PUT /_component_template/template_with_2_shards -{ - "template": { - "settings": { - "index.number_of_shards": 2 - } - } -} --------------------------------------------------- - -[source,console] --------------------------------------------------- -PUT /_component_template/template_with_3_shards -{ - "template": { - "settings": { - "index.number_of_shards": 3 - } - } -} --------------------------------------------------- - -The order they are specified changes the number of shards for an index: - -[source,console] --------------------------------------------------- -PUT /_index_template/template_1 -{ - "index_patterns": ["t*"], - "composed_of": ["template_with_2_shards", "template_with_3_shards"] -} --------------------------------------------------- - -In this case, an index matching `t*` will have three primary shards. If the order of composed -templates were reversed, the index would have two primary shards. - ===== Index template with index aliases You can include <> in an index template. @@ -408,3 +475,133 @@ PUT /_index_template/template_1 -------------------------------------------------- To check the `_meta`, you can use the <> API. + +[[data-stream-definition]] +===== Data stream definition + +If a composable template should auto create a data stream instead of an index then +a `data_stream` definition can be added to a composable template. + +[source,console] +-------------------------------------------------- +PUT /_index_template/template_1 +{ + "index_patterns": ["logs-*"], + "template": { + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + } + } + } + }, + "data_stream": { + "timestamp_field": "@timestamp" + } +} +-------------------------------------------------- + +Required properties of a data stream definition: + +`timestamp_field`:: +(Required, string) The name of the timestamp field. This field must be present +in all documents indexed into the data stream and must be of type +<> or <>. + +[[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* +-------------------------------------------------- + + +[[get-template-api-all-ex]] +===== Get all index templates + +[source,console] +-------------------------------------------------- +GET /_index_template +-------------------------------------------------- \ No newline at end of file From b2ba38b5a482a2020b3820081239239668630c71 Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Wed, 10 Jun 2020 15:39:54 -0700 Subject: [PATCH 2/3] Fixed bad merge --- .../indices/index-templates.asciidoc | 33 ------------------- 1 file changed, 33 deletions(-) diff --git a/docs/reference/indices/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc index 1d92583d89dff..dc73b3d011634 100644 --- a/docs/reference/indices/index-templates.asciidoc +++ b/docs/reference/indices/index-templates.asciidoc @@ -476,39 +476,6 @@ PUT /_index_template/template_1 To check the `_meta`, you can use the <> API. -[[data-stream-definition]] -===== Data stream definition - -If a composable template should auto create a data stream instead of an index then -a `data_stream` definition can be added to a composable template. - -[source,console] --------------------------------------------------- -PUT /_index_template/template_1 -{ - "index_patterns": ["logs-*"], - "template": { - "mappings": { - "properties": { - "@timestamp": { - "type": "date" - } - } - } - }, - "data_stream": { - "timestamp_field": "@timestamp" - } -} --------------------------------------------------- - -Required properties of a data stream definition: - -`timestamp_field`:: -(Required, string) The name of the timestamp field. This field must be present -in all documents indexed into the data stream and must be of type -<> or <>. - [[multiple-component-templates]] ===== Composing multiple component templates From 5b057928c53e6d65585f3680940288688e2616dd Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Wed, 10 Jun 2020 15:58:36 -0700 Subject: [PATCH 3/3] Fix merge issue & test. --- .../indices/index-templates.asciidoc | 128 ------------------ 1 file changed, 128 deletions(-) diff --git a/docs/reference/indices/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc index dc73b3d011634..00ff3ba4986ef 100644 --- a/docs/reference/indices/index-templates.asciidoc +++ b/docs/reference/indices/index-templates.asciidoc @@ -104,134 +104,6 @@ DELETE _component_template/* ////////////////////////// -[[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 ++++