elasticsearch/docs/reference/indices/put-component-template.asciidoc

[[indices-component-template]]
=== Create or update component template API
++++
<titleabbrev>Create or update component template</titleabbrev>
++++

Creates or updates a component template. Component templates are building blocks
for constructing <<index-templates,index templates>> that specify index
<<mapping,mappings>>, <<index-modules-settings,settings>>, and
<<alias,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-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
privilege>> to use this API.

[[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.
+
[IMPORTANT]
====
{es} includes the following built-in component templates:

// tag::built-in-component-templates[]
- `logs-mappings`
- `logs-settings`
- `metrics-mappings`
- `metrics-settings`
- `synthetics-mapping`
- `synthetics-settings`
// end::built-in-component-templates[]

{fleet-guide}/fleet-overview.html[{agent}] uses these templates to configure
backing indices for its data streams. If you use {agent} and want to overwrite
one of these templates, set the `version` for your replacement template higher
than the current version.

If you don't use {agent} and want to disable all built-in component and index
templates, set <<stack-templates-enabled,`stack.templates.enabled`>> to `false`
using the <<cluster-update-settings,cluster update settings API>>.
====

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

[role="child_attributes"]
[[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.
+
.Properties of `template`
[%collapsible%open]
====
`aliases`::
(Optional, object of objects) Aliases for the index. If an index template
includes `data_stream`, this parameter is not supported.
+
include::{es-repo-dir}/indices/create-index.asciidoc[tag=aliases-props]

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

`allow_auto_create`::
(Optional, Boolean)
This setting overrides the value of the
<<index-creation,`action.auto_create_index`>> cluster setting. If set to
`true` in a template, then indices can be automatically created using that
template even if auto-creation of indices is disabled via
`actions.auto_create_index`. If set to `false`, then indices or data streams matching the
template must always be explicitly created, and may never be automatically
created.

`_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 <<alias,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 <<index-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 preferable.

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.