OpenSearch/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 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
--------------------------------------------------