213 lines
6.0 KiB
Plaintext
213 lines
6.0 KiB
Plaintext
[[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.id" : "kimchy" }
|
|
},
|
|
"routing" : "shard-1"
|
|
},
|
|
"{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.
|