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