* [DOCS] Refactored index-templates topic. * [DOCS] Add separate files. * [DOCS] Add delete component template. * Apply suggestions from code review Co-authored-by: James Rodewig <james.rodewig@elastic.co> * [DOCS] Incorporated review comments
This commit is contained in:
debadair
GitHub
parent
2665bfffce
commit
284c61ad19
|
|
@ -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 <<indices-templates,index templates>> that specifies index
|
||||
<<mapping,mappings>>, <<index-modules-settings,settings>>, and <<indices-aliases,aliases>>.
|
||||
// end::component-template-def[]
|
||||
|
||||
[[glossary-ccr]] {ccr} (CCR)::
|
||||
|
||||
The {ccr} feature enables you to replicate indices in remote clusters to your
|
||||
|
|
|
|||
|
|
@ -20,6 +20,8 @@ include::setup.asciidoc[]
|
|||
|
||||
include::upgrade.asciidoc[]
|
||||
|
||||
include::indices/index-templates.asciidoc[]
|
||||
|
||||
include::data-streams/data-streams.asciidoc[]
|
||||
|
||||
include::search/index.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -49,14 +49,21 @@ index settings, aliases, mappings, and index templates.
|
|||
* <<indices-analyze>>
|
||||
|
||||
[discrete]
|
||||
[[index-templates]]
|
||||
[[index-templates-apis]]
|
||||
=== Index templates:
|
||||
* <<indices-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.
|
||||
The index template associated with a data stream configures its backing indices.
|
||||
For more information, see <<indices-templates, Index Templates>>.
|
||||
|
||||
* <<indices-put-template>>
|
||||
* <<indices-get-template>>
|
||||
* <<indices-delete-template>>
|
||||
* <<indices-component-template>>
|
||||
* <<getting-component-templates>>
|
||||
* <<indices-delete-component-template>>
|
||||
* <<indices-template-exists>>
|
||||
* <<indices-simulate-index>>
|
||||
* <<indices-simulate-template>>
|
||||
|
|
@ -103,6 +110,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[]
|
||||
|
|
@ -111,6 +120,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[]
|
||||
|
|
@ -121,6 +132,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[]
|
||||
|
|
@ -139,11 +152,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[]
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,52 @@
|
|||
[[indices-delete-component-template]]
|
||||
=== Delete component template API
|
||||
++++
|
||||
<titleabbrev>Delete component template</titleabbrev>
|
||||
++++
|
||||
|
||||
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/<component-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 <<indices-templates,index templates>>
|
||||
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]
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
<titleabbrev>Delete index template</titleabbrev>
|
||||
++++
|
||||
|
||||
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 <<index-modules-settings,settings>>, <<mapping,mappings>>,
|
||||
and <<indices-aliases,aliases>> that can be applied automatically to new indices.
|
||||
|
||||
|
||||
[[delete-template-api-path-params]]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,88 @@
|
|||
[[getting-component-templates]]
|
||||
=== Get component template API
|
||||
++++
|
||||
<titleabbrev>Get component template</titleabbrev>
|
||||
++++
|
||||
|
||||
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/<component-template>`
|
||||
|
||||
|
||||
[[get-component-template-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`<component-template>`
|
||||
(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
|
||||
--------------------------------------------------
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
[[indices-get-template-v1]]
|
||||
=== Get index template API
|
||||
++++
|
||||
<titleabbrev>Get index template (legacy)</titleabbrev>
|
||||
++++
|
||||
|
||||
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, <<indices-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/<index-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
|
||||
--------------------------------------------------
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
[[indices-get-template-v1]]
|
||||
=== Get index template API
|
||||
[[indices-get-template]]
|
||||
=== Get index template API [[getting-templates]]
|
||||
++++
|
||||
<titleabbrev>Get index template</titleabbrev>
|
||||
++++
|
||||
|
|
@ -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/<index-template>`
|
||||
`GET /_index_template/<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
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -1,18 +1,9 @@
|
|||
[[indices-templates]]
|
||||
=== Index templates
|
||||
++++
|
||||
<titleabbrev>Index template</titleabbrev>
|
||||
++++
|
||||
[[index-templates]]
|
||||
= Index templates
|
||||
|
||||
This documentation is about composable templates. For legacy templates please see the
|
||||
<<indices-templates-v1,legacy template documentation>>.
|
||||
|
||||
[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 <<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.
|
||||
|
|
@ -29,6 +20,10 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -92,7 +87,7 @@ PUT _index_template/template_1
|
|||
--------------------------------------------------
|
||||
// TESTSETUP
|
||||
|
||||
//////////////////////////
|
||||
////
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
|
|
@ -101,516 +96,6 @@ DELETE _component_template/*
|
|||
--------------------------------------------------
|
||||
// TEARDOWN
|
||||
|
||||
//////////////////////////
|
||||
////
|
||||
|
||||
[[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
|
||||
++++
|
||||
<titleabbrev>Put index template</titleabbrev>
|
||||
++++
|
||||
|
||||
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/<index-template>`
|
||||
|
||||
|
||||
[[put-index-template-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
// tag::index-template-def[]
|
||||
Index templates define <<index-modules-settings,settings>> and <<mapping,mappings>> that you can
|
||||
automatically apply when creating new indices.
|
||||
|
||||
For data streams, these settings and mappings are applied to the stream's backing indices when created.
|
||||
|
||||
{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 data stream or index creation. Changes to index templates do not affect
|
||||
existing indices, including the existing backing indices of a data stream.
|
||||
Settings and mappings specified in <<indices-create-index, create index>> 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}
|
||||
|
||||
`<index-template>`::
|
||||
(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 data streams and indices during creation.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases]
|
||||
+
|
||||
NOTE: You cannot add data streams to an index alias.
|
||||
|
||||
[xpack]#`data_stream`#::
|
||||
(Optional, object)
|
||||
Indicates whether the template is used to create data streams and their backing
|
||||
indices. If so, use an empty object as the argument: +
|
||||
`data_stream: { }`.
|
||||
+
|
||||
Data streams require a matching index template with a `data_stream` object.
|
||||
See <<create-a-data-stream-template>>.
|
||||
|
||||
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
|
||||
<<multiple-component-templates,Composing multiple component templates>> for an example.
|
||||
|
||||
`priority`::
|
||||
(Optional, integer)
|
||||
Priority to determine index template precedence when a new data stream or 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 <<indices-aliases,index aliases>> 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}.
|
||||
|
||||
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 <<indices-get-template, get index template>> 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 <<indices-get-template, get index template>> API.
|
||||
|
||||
[[data-stream-definition]]
|
||||
===== Data stream definition
|
||||
|
||||
If an index template should create data streams, the template must include an
|
||||
empty `data_stream` object. See <<create-a-data-stream-template>>.
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /_index_template/template_1
|
||||
{
|
||||
"index_patterns": ["logs-*"],
|
||||
"data_stream": { }
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[[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.
|
||||
|
||||
[[indices-get-template]]
|
||||
=== Get index template API [[getting-templates]]
|
||||
++++
|
||||
<titleabbrev>Get index template</titleabbrev>
|
||||
++++
|
||||
|
||||
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/<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
|
||||
--------------------------------------------------
|
||||
include::simulate-multi-component-templates.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,212 @@
|
|||
[[indices-component-template]]
|
||||
=== Put component template API
|
||||
++++
|
||||
<titleabbrev>Put component template</titleabbrev>
|
||||
++++
|
||||
|
||||
Creates or updates a component template.
|
||||
Component templates are building blocks for constructing <<indices-templates,index templates>>.
|
||||
that specify index <<mapping,mappings>>, <<index-modules-settings,settings>>,
|
||||
and <<indices-aliases,aliases>>.
|
||||
|
||||
[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/<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 new data streams and indices
|
||||
as part of a matching index template.
|
||||
|
||||
Settings and mappings specified directly in the index template or the <<indices-create-index, create index>>
|
||||
request override any settings or mappings specified in a component template.
|
||||
|
||||
Component templates are only used during index creation. For data streams, this
|
||||
includes data stream creation and the creation of a stream's backing indices.
|
||||
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}
|
||||
|
||||
`<component-template>`::
|
||||
(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]
|
||||
+
|
||||
NOTE: You cannot add data streams to an index alias.
|
||||
|
||||
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 <<indices-aliases,index aliases>> 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 a data stream or index.
|
||||
To be applied, a component template must be included in an index template's `composed_of` list. See <<indices-templates>>.
|
||||
|
||||
[[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 <<getting-component-templates,get component template API>>.
|
||||
|
||||
[[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 <<getting-component-templates,get component template>> API.
|
||||
|
|
@ -1,18 +1,12 @@
|
|||
[[indices-templates-v1]]
|
||||
=== Put index template API
|
||||
++++
|
||||
<titleabbrev>Put index template</titleabbrev>
|
||||
<titleabbrev>Put index template (legacy)</titleabbrev>
|
||||
++++
|
||||
|
||||
This documentation is about legacy index templates, which are deprecated and will be replaced by
|
||||
composable templates. For information about composable templates, see <<indices-templates>>.
|
||||
|
||||
[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, <<indices-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 <<index-modules-settings,settings>> and <<mapping,mappings>>
|
||||
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.
|
||||
|
|
@ -0,0 +1,337 @@
|
|||
[[indices-put-template]]
|
||||
=== Put index template API
|
||||
++++
|
||||
<titleabbrev>Put index template</titleabbrev>
|
||||
++++
|
||||
|
||||
Creates or updates an index template.
|
||||
Index templates define <<index-modules-settings,settings>>, <<mapping,mappings>>,
|
||||
and <<indices-aliases,aliases>> 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/<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 data stream or index creation.
|
||||
For data streams, these settings and mappings are applied when the stream's backing indices are created.
|
||||
|
||||
Settings and mappings specified in a <<indices-create-index, create index>>
|
||||
request override any settings or mappings specified in an index template.
|
||||
|
||||
Changes to index templates do not affect
|
||||
existing indices, including the existing backing indices of a data stream.
|
||||
|
||||
===== 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}
|
||||
|
||||
`<index-template>`::
|
||||
(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 data streams and indices during creation.
|
||||
|
||||
include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases]
|
||||
+
|
||||
NOTE: You cannot add data streams to an index alias.
|
||||
|
||||
[xpack]#`data_stream`#::
|
||||
(Optional, object)
|
||||
Indicates whether the template is used to create data streams and their backing
|
||||
indices. If so, use an empty object as the argument: +
|
||||
`data_stream: { }`.
|
||||
+
|
||||
Data streams require a matching index template with a `data_stream` object.
|
||||
See <<create-a-data-stream-template>>.
|
||||
|
||||
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
|
||||
<<multiple-component-templates,Composing multiple component templates>> for an example.
|
||||
|
||||
`priority`::
|
||||
(Optional, integer)
|
||||
Priority to determine index template precedence when a new data stream or 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 <<indices-aliases,index aliases>> 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 or data stream,
|
||||
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 <<indices-get-template, get index template>> 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 <<indices-get-template, get index template>> API.
|
||||
|
||||
[[data-stream-definition]]
|
||||
===== Data stream definition
|
||||
|
||||
To use an index template for a data stream, the template must include an empty `data_stream` object.
|
||||
Data stream templates are only used for a stream's backing indices,
|
||||
they are not applied to regular indices.
|
||||
See <<create-a-data-stream-template>>.
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /_index_template/template_1
|
||||
{
|
||||
"index_patterns": ["logs-*"],
|
||||
"data_stream": { }
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[[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.
|
||||
|
|
@ -0,0 +1,124 @@
|
|||
[[simulate-multi-component-templates]]
|
||||
== Simulate multi-component templates
|
||||
|
||||
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 particular index name:
|
||||
|
||||
////
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /_index_template/template_1
|
||||
{
|
||||
"index_patterns" : ["my*"],
|
||||
"priority" : 1,
|
||||
"template": {
|
||||
"settings" : {
|
||||
"number_of_shards" : 2
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTSETUP
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
DELETE /_index_template/template_1
|
||||
--------------------------------------------------
|
||||
// TEARDOWN
|
||||
|
||||
////
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
POST /_index_template/_simulate_index/myindex
|
||||
--------------------------------------------------
|
||||
|
||||
To simulate the settings that would be applied from an existing template:
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
POST /_index_template/_simulate/template_1
|
||||
--------------------------------------------------
|
||||
|
||||
You can also specify a template definition in the simulate request.
|
||||
This enables you to verify that settings will be applied as expected before you add a new template.
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
PUT /_component_template/ct1
|
||||
{
|
||||
"template": {
|
||||
"settings": {
|
||||
"index.number_of_shards": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
PUT /_component_template/ct2
|
||||
{
|
||||
"template": {
|
||||
"settings": {
|
||||
"index.number_of_replicas": 0
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"@timestamp": {
|
||||
"type": "date"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
POST /_index_template/_simulate
|
||||
{
|
||||
"index_patterns": ["my*"],
|
||||
"template": {
|
||||
"settings" : {
|
||||
"index.number_of_shards" : 3
|
||||
}
|
||||
},
|
||||
"composed_of": ["ct1", "ct2"]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
The response shows the settings, mappings, and aliases that would be applied to matching indices,
|
||||
and any overlapping templates whose configuration would be superseded by the simulated template body
|
||||
or higher-priority templates.
|
||||
|
||||
[source,console-result]
|
||||
---------------------------------------------------------
|
||||
{
|
||||
"template" : {
|
||||
"settings" : {
|
||||
"index" : {
|
||||
"number_of_shards" : "3", <1>
|
||||
"number_of_replicas" : "0"
|
||||
}
|
||||
},
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"@timestamp" : {
|
||||
"type" : "date" <2>
|
||||
}
|
||||
}
|
||||
},
|
||||
"aliases" : { }
|
||||
},
|
||||
"overlapping" : [
|
||||
{
|
||||
"name" : "template_1", <3>
|
||||
"index_patterns" : [
|
||||
"my*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
---------------------------------------------------------
|
||||
<1> The number of shards 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
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
<titleabbrev>Index template exists</titleabbrev>
|
||||
++++
|
||||
|
||||
Checks if an index template exists.
|
||||
Checks if an <<index-templates, index template>> 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 <<index-modules-settings,settings>>, <<mapping,mappings>>,
|
||||
and <<indices-aliases,aliases>> that can be applied automatically to new indices.
|
||||
|
||||
[[template-exists-api-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
|
|
|||
|
|
@ -907,6 +907,11 @@ See <<release-highlights>>.
|
|||
|
||||
The `xpack.sql.enabled` setting has been deprecated. SQL access is always enabled.
|
||||
|
||||
[role="exclude",id="indices-templates"]
|
||||
=== Index templates [[getting]]
|
||||
|
||||
See <<index-templates>>.
|
||||
|
||||
////
|
||||
[role="exclude",id="search-request-body"]
|
||||
=== Request body search
|
||||
|
|
|
|||
|
|
@ -535,6 +535,13 @@ Comma-separated list or wildcard expression of index template names
|
|||
used to limit the request.
|
||||
end::index-template[]
|
||||
|
||||
tag::component-template[]
|
||||
`<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
|
||||
|
|
|
|||
Loading…
Reference in New Issue