From cc9e00dfade67849b256880771eaa16b2b41c139 Mon Sep 17 00:00:00 2001 From: debadair Date: Wed, 10 Jun 2020 16:15:04 -0700 Subject: [PATCH] [DOCS] Fix chunking in template API docs (#57632) (#57956) * [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 * Fixed bad merge * Fix merge issue & test. --- docs/reference/indices.asciidoc | 5 +- .../indices/component-templates.asciidoc | 122 ++++---- .../indices/index-templates.asciidoc | 276 ++++++++++-------- 3 files changed, 220 insertions(+), 183 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..00ff3ba4986ef 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,13 +97,35 @@ PUT _index_template/template_1 [source,console] -------------------------------------------------- -DELETE _index_template/template_* +DELETE _index_template/* 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} @@ -86,8 +135,6 @@ DELETE _component_template/* [[put-index-template-api-desc]] ==== {api-description-title} -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 @@ -102,68 +149,6 @@ requests override any settings or mappings specified in an index template. You can use C-style /* */ block comments in index templates. You can include comments anywhere in the request body, except before the opening curly bracket. -[[getting]] -===== Getting templates - -[[indices-get-template]] -=== Get index template API -++++ -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::{es-repo-dir}/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::{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-api-example]] -==== {api-examples-title} - - -[[get-template-api-wildcard-ex]] -===== Get index templates using a wildcard expression - -[source,console] --------------------------------------------------- -GET /_index_template/temp* --------------------------------------------------- - - -[[get-template-api-all-ex]] -===== Get all index templates - -[source,console] --------------------------------------------------- -GET /_index_template --------------------------------------------------- - [[put-index-template-api-path-params]] ==== {api-path-parms-title} @@ -179,7 +164,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 +175,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 +188,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 +212,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 +347,100 @@ PUT /_index_template/template_1 -------------------------------------------------- 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* +-------------------------------------------------- + + +[[get-template-api-all-ex]] +===== Get all index templates + +[source,console] +-------------------------------------------------- +GET /_index_template +-------------------------------------------------- \ No newline at end of file