[DOCS] [7.x] Add runtime fields to index templates (#70172) (#70403)

* [DOCS] Add runtime fields to index templates * Apply suggestions from code review Co-authored-by: debadair <[email protected]> * Deemphasize runtime fields and Kibana. * Remove duplicate timestamp from component template. Co-authored-by: debadair <[email protected]> Co-authored-by: debadair <[email protected]>
elastic · Mar 15, 2021 · 930f937 · 930f937
1 parent b2b0101
commit 930f937
Showing 1 changed file with 63 additions and 32 deletions.
diff --git a/docs/reference/indices/index-templates.asciidoc b/docs/reference/indices/index-templates.asciidoc
@@ -1,25 +1,38 @@
 [[index-templates]]
 = Index templates
 
-NOTE: This topic describes the composable index templates introduced in {es} 7.8. 
-For information about how index templates worked previously, 
+NOTE: This topic describes the composable index templates introduced in {es} 7.8.
+For information about how index templates worked previously,
 see the <<indices-templates-v1,legacy template documentation>>.
 
 [[getting]]
-An index template is a way to tell {es} how to configure an index when it is created.
-For data streams, the index template configures the stream's backing indices as they
-are created. Templates are configured prior to index creation and then when an
-index is created either manually or through indexing a document, the template
-settings are used as a basis for creating the index.
-
-There are two types of templates, index templates and <<indices-component-template,component
-templates>>. Component templates are reusable building blocks that configure mappings, settings, and
-aliases. You use component templates to construct index templates, they aren't directly applied to a
-set of indices. Index templates can contain a collection of component templates, as well as directly
-specify settings, mappings, and aliases.
-
-If a new data stream or index matches more than one index template, the index template with the highest priority is used.
-
+An index template is a way to tell {es} how to configure an index when it is
+created. For data streams, the index template configures the stream's backing
+indices as they are created. Templates are configured
+*prior to index creation*. When an index is created - either manually or
+through indexing a document - the template settings are used as a basis for
+creating the index.
+
+There are two types of templates: index templates and <<indices-component-template,component templates>>. Component templates are reusable building
+blocks that configure mappings, settings, and aliases. While you can use
+component templates to construct index templates, they aren't directly applied
+to a set of indices. Index templates can contain a collection of component
+templates, as well as directly specify settings, mappings, and aliases.
+
+The following conditions apply to index templates:
+
+* Composable templates take precedence over legacy templates. If no composable
+template matches a given index, 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 <<indices-create-index,create index>> request
+take precedence over settings specified in the index template and its component
+templates.
+* If a new data stream or index matches more than one index template, the index
+template with the highest priority is used.
+
+.Using index templates with {fleet} or {agent}
+****
 // tag::built-in-index-templates[]
 [IMPORTANT]
 ====
@@ -53,16 +66,20 @@ template for the `logs-*` index pattern, assign your template a priority of
 for `logs-*-*`.
 ====
 // end::built-in-index-templates[]
+****
+
+[discrete]
+[[create-index-templates]]
+== Create index template
 
-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.
+Use the <<indices-put-template,index template>> and <<indices-component-template,put component template>> APIs to create and update index templates.
+You can also <<index-mgmt,manage index templates>> from Stack
+Management in {kib}.
 
-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.
+The following requests create two component templates.
 
 [source,console]
---------------------------------------------------
+----
 PUT _component_template/component_template1
 {
   "template": {
@@ -76,19 +93,30 @@ PUT _component_template/component_template1
   }
 }
 
-PUT _component_template/other_component_template
+PUT _component_template/runtime_component_template
 {
   "template": {
     "mappings": {
-      "properties": {
-        "ip_address": {
-          "type": "ip"
+      "runtime": { <1>
+        "day_of_week": {
+          "type": "keyword",
+          "script": {
+            "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
+          }
         }
       }
     }
   }
 }
+----
+<1> This component template adds a <<runtime-mapping-fields,runtime field>>
+named `day_of_week` to the mappings when a new index matches the template.
+
+The following request creates an index template that is _composed of_ these
+component templates.
 
+[source,console]
+----
 PUT _index_template/template_1
 {
   "index_patterns": ["te*", "bar*"],
@@ -97,6 +125,9 @@ PUT _index_template/template_1
       "number_of_shards": 1
     },
     "mappings": {
+      "_source": {
+        "enabled": true
+      },
       "properties": {
         "host_name": {
           "type": "keyword"
@@ -112,23 +143,23 @@ PUT _index_template/template_1
     }
   },
   "priority": 500,
-  "composed_of": ["component_template1", "other_component_template"],
+  "composed_of": ["component_template1", "runtime_component_template"], <1>
   "version": 3,
   "_meta": {
     "description": "my custom"
   }
 }
---------------------------------------------------
-// TESTSETUP
+----
+// TEST[continued]
 
 ////
 
 [source,console]
---------------------------------------------------
+----
 DELETE _index_template/*
 DELETE _component_template/*
---------------------------------------------------
-// TEARDOWN
+----
+// TEST[continued]
 
 ////