|
@@ -1,275 +0,0 @@
|
|
|
-[[indices-component-template]]
|
|
|
-=== Put component template API
|
|
|
-++++
|
|
|
-<titleabbrev>Put 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 data streams and indices. On their own
|
|
|
-component templates are not matched or applied to a data stream or index, instead they are used in the
|
|
|
-`composed_of` definition of an <<indices-templates,index template>>.
|
|
|
-// end::component-template-def[]
|
|
|
-
|
|
|
-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.
|
|
|
-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.
|
|
|
-
|
|
|
-[[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
|
|
|
-
|
|
|
-Component templates on their own don't apply or interact with data streams or indices at all.
|
|
|
-To take effect, they must be used as part of an index template's `composed_of` field. See
|
|
|
-the <<indices-templates,index templates>>.
|
|
|
-
|
|
|
-[[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.
|
|
|
-
|
|
|
-[[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}
|
|
|
-
|
|
|
-`<component-template>`
|
|
|
-(Required, 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
|
|
|
---------------------------------------------------
|