templates.asciidoc 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192
  1. [[indices-templates]]
  2. === Index Templates
  3. // tag::index-template-def[]
  4. Index templates define <<index-modules-settings,settings>> and <<mapping,mappings>>
  5. that you can automatically apply when creating new indices.
  6. {es} applies templates to new indices
  7. based on an index pattern that matches the index name.
  8. // end::index-template-def[]
  9. NOTE: Templates are only applied at index creation time. Changing a template
  10. will have no impact on existing indices. When using the create index API, the
  11. settings/mappings defined as part of the create index call will take precedence
  12. over any matching settings/mappings defined in the template.
  13. For example:
  14. [source,js]
  15. --------------------------------------------------
  16. PUT _template/template_1
  17. {
  18. "index_patterns": ["te*", "bar*"],
  19. "settings": {
  20. "number_of_shards": 1
  21. },
  22. "mappings": {
  23. "_source": {
  24. "enabled": false
  25. },
  26. "properties": {
  27. "host_name": {
  28. "type": "keyword"
  29. },
  30. "created_at": {
  31. "type": "date",
  32. "format": "EEE MMM dd HH:mm:ss Z yyyy"
  33. }
  34. }
  35. }
  36. }
  37. --------------------------------------------------
  38. // CONSOLE
  39. // TESTSETUP
  40. NOTE: Index templates provide C-style /* */ block comments. Comments are allowed
  41. everywhere in the JSON document except before the initial opening curly bracket.
  42. Defines a template named `template_1`, with a template pattern of `te*` or `bar*`.
  43. The settings and mappings will be applied to any index name that matches
  44. the `te*` or `bar*` pattern.
  45. It is also possible to include aliases in an index template as follows:
  46. [source,js]
  47. --------------------------------------------------
  48. PUT _template/template_1
  49. {
  50. "index_patterns" : ["te*"],
  51. "settings" : {
  52. "number_of_shards" : 1
  53. },
  54. "aliases" : {
  55. "alias1" : {},
  56. "alias2" : {
  57. "filter" : {
  58. "term" : {"user" : "kimchy" }
  59. },
  60. "routing" : "kimchy"
  61. },
  62. "{index}-alias" : {} <1>
  63. }
  64. }
  65. --------------------------------------------------
  66. // CONSOLE
  67. // TEST[s/^/DELETE _template\/template_1\n/]
  68. <1> the `{index}` placeholder in the alias name will be replaced with the
  69. actual index name that the template gets applied to, during index creation.
  70. [float]
  71. [[delete]]
  72. ==== Deleting a Template
  73. Index templates are identified by a name (in the above case
  74. `template_1`) and can be deleted as well:
  75. [source,js]
  76. --------------------------------------------------
  77. DELETE /_template/template_1
  78. --------------------------------------------------
  79. // CONSOLE
  80. [float]
  81. [[getting]]
  82. ==== Getting templates
  83. See <<indices-get-template>>.
  84. [float]
  85. [[multiple-templates]]
  86. ==== Multiple Templates Matching
  87. Multiple index templates can potentially match an index, in this case,
  88. both the settings and mappings are merged into the final configuration
  89. of the index. The order of the merging can be controlled using the
  90. `order` parameter, with lower order being applied first, and higher
  91. orders overriding them. For example:
  92. [source,js]
  93. --------------------------------------------------
  94. PUT /_template/template_1
  95. {
  96. "index_patterns" : ["*"],
  97. "order" : 0,
  98. "settings" : {
  99. "number_of_shards" : 1
  100. },
  101. "mappings" : {
  102. "_source" : { "enabled" : false }
  103. }
  104. }
  105. PUT /_template/template_2
  106. {
  107. "index_patterns" : ["te*"],
  108. "order" : 1,
  109. "settings" : {
  110. "number_of_shards" : 1
  111. },
  112. "mappings" : {
  113. "_source" : { "enabled" : true }
  114. }
  115. }
  116. --------------------------------------------------
  117. // CONSOLE
  118. // TEST[s/^/DELETE _template\/template_1\n/]
  119. The above will disable storing the `_source`, but
  120. for indices that start with `te*`, `_source` will still be enabled.
  121. Note, for mappings, the merging is "deep", meaning that specific
  122. object/property based mappings can easily be added/overridden on higher
  123. order templates, with lower order templates providing the basis.
  124. NOTE: Multiple matching templates with the same order value will
  125. result in a non-deterministic merging order.
  126. [float]
  127. [[versioning-templates]]
  128. ==== Template Versioning
  129. Templates can optionally add a `version` number, which can be any integer value,
  130. in order to simplify template management by external systems. The `version`
  131. field is completely optional and it is meant solely for external management of
  132. templates. To unset a `version`, simply replace the template without specifying
  133. one.
  134. [source,js]
  135. --------------------------------------------------
  136. PUT /_template/template_1
  137. {
  138. "index_patterns" : ["*"],
  139. "order" : 0,
  140. "settings" : {
  141. "number_of_shards" : 1
  142. },
  143. "version": 123
  144. }
  145. --------------------------------------------------
  146. // CONSOLE
  147. To check the `version`, you can
  148. <<common-options-response-filtering, filter responses>>
  149. using `filter_path` to limit the response to just the `version`:
  150. [source,js]
  151. --------------------------------------------------
  152. GET /_template/template_1?filter_path=*.version
  153. --------------------------------------------------
  154. // CONSOLE
  155. // TEST[continued]
  156. This should give a small response that makes it both easy and inexpensive to parse:
  157. [source,js]
  158. --------------------------------------------------
  159. {
  160. "template_1" : {
  161. "version" : 123
  162. }
  163. }
  164. --------------------------------------------------
  165. // TESTRESPONSE