273 lines
7.7 KiB
Plaintext
273 lines
7.7 KiB
Plaintext
[[indices-component-template]]
|
|
=== Component template API
|
|
++++
|
|
<titleabbrev>Component template</titleabbrev>
|
|
++++
|
|
|
|
Component templates are building blocks that specify mappings, settings, or alias configuration, but
|
|
don't apply to a set of indices themselves. To be used a component template must be specified in the
|
|
`composed_of` of an <<indices-templates,index template>>.
|
|
|
|
[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}
|
|
|
|
Use the PUT component template API to create or update a component template.
|
|
|
|
// tag::component-template-def[]
|
|
Component templates define <<index-modules-settings,settings>>, <<mapping,mappings>>, and
|
|
<<indices-aliases,aliases>> that you can automatically apply when creating new indices. On their own
|
|
component templates are not matched or applied to an index, instead they are used in the
|
|
`composed_of` definition of an <<indices-templates,index template>> to make up the final index
|
|
configuration.
|
|
// end::component-template-def[]
|
|
|
|
Component templates are only used during index creation. Changes to component templates do not
|
|
affect existing indices. Settings and mappings specified in <<indices-create-index, create index>>
|
|
API requests and <<indices-templates,index templates>> override any settings or mappings specified
|
|
in a component template.
|
|
|
|
===== 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.
|
|
|
|
[[getting-component-templates]]
|
|
===== Getting component templates
|
|
|
|
=== Get component template API
|
|
++++
|
|
<titleabbrev>Get component template</titleabbrev>
|
|
++++
|
|
|
|
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/<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
|
|
--------------------------------------------------
|
|
|
|
[[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::{docdir}/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::{docdir}/rest-api/common-parms.asciidoc[tag=aliases]
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings]
|
|
|
|
include::{docdir}/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
|
|
|
|
Component templates on their own don't apply or interact with indices at all. In order for them to
|
|
be effective, they must be used as part of index template's `composed_of` field to take effect. See
|
|
the <<indices-templates,index templates>> documentation for more information.
|
|
|
|
[[component-templates-version]]
|
|
===== Component template versioning
|
|
|
|
You can use the `version` parameter to add an optional version number to a component 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 /_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 optional metadata to a component 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 /_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.
|