elasticsearch/docs/reference/indices/component-templates.asciidoc

[[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 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.

[[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]

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

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.

[[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
--------------------------------------------------