IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Put index template API Put mapping API »
Elastic Docs ›Elasticsearch Guide [7.10] ›REST APIs ›Index APIs

Put component template API

edit

Put component template API

edit

Creates or updates a component template. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

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

Request

edit

PUT /_component_template/<component-template>

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the manage_index_templates or manage cluster privilege to use this API.

Description

edit

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

edit

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.

Path parameters

edit
<component-template>

(Required, string) Name of the component template to create.

Elasticsearch includes the following built-in component templates:

  • logs-mappings
  • logs-settings
  • metrics-mappings
  • metrics-settings
  • synthetics-mapping
  • synthetics-settings

Elastic Agent uses these templates to configure backing indices for its data streams. If you use Elastic 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 Elastic Agent and want to disable all built-in component and index templates, set stack.templates.enabled to false in elasticsearch.yml.

Query parameters

edit
create
(Optional, Boolean) If true, this request cannot replace or update existing component templates. Defaults to false.
master_timeout
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Request body

edit
template
(Required, object) This is the template to be applied, may optionally include a mappings, settings, or aliases configuration.
aliases

(Optional, alias object) Index aliases which include the index. See Update index alias.

You cannot add data streams to an index alias.

mappings

(Optional, mapping object) Mapping for fields in the index. If specified, this mapping can include:

See Mapping.

settings
(Optional, index setting object) Configuration options for the index. See Index Settings.
version
(Optional, integer) Version number used to manage component templates externally. This number is not automatically generated or incremented by Elasticsearch.
_meta
(Optional, object) Optional user metadata about the component template. May have any contents. This map is not automatically generated by Elasticsearch.

Examples

edit

Component template with index aliases

edit

You can include index aliases in a component template.

PUT _component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user.id" : "kimchy" }
            },
            "routing" : "shard-1"
        },
        "{index}-alias" : {} 
    }
  }
}

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

edit

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 template versioning

edit

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

To unset a version, replace the template without specifying one.

PUT /_component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

To check the version, you can use the get component template API.

Component template metadata

edit

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

To unset _meta, replace the template without specifying one.

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 get component template API.

« Put index template API Put mapping API »