Create or update a component template

POST also PUT /_component_template/{name}

Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

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.

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.

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.

Required authorization

Cluster privileges: manage_index_templates

Path Parameters

name string Name required: 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 using the cluster update settings API.

Query Parameters

Request

Response

application/json

Examples

Request Console 1 / 8 languages

Console Kibana Dev Tools

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

JavaScript Elasticsearch JavaScript Client

const response = await client.cluster.putComponentTemplate({
  name: "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",
        },
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.cluster.put_component_template(
    name="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"
                }
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_component_template/template_1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
          }
        }
      }
    }
  }'

Java Elasticsearch Java Client

client.cluster().putComponentTemplate(p -> p
    .name("template_1")
    .template(t -> t
        .mappings(m -> m
            .properties(Map.of("created_at", Property.of(pr -> pr
                    .date(d -> d
                        .format("EEE MMM dd HH:mm:ss Z yyyy")
                    )
                ),"host_name", Property.of(pro -> pro
                    .keyword(k -> k)
                )))
            .source(s -> s
                .enabled(false)
            )
        )
        .settings(s -> s
            .otherSettings(Map.of())
            .numberOfShards("1")
        )
    )
);

C# Elasticsearch .NET Client

var response = await client.Cluster
    .PutComponentTemplateAsync(name: "template_1", d1 => d1
        .Template(d2 => d2
            .Mappings(d3 => d3
                .Properties(d4 => d4
                    .Keyword(x => x.HostName)
                    .Date(x => x.CreatedAt, d5 => d5
                        .Format("EEE MMM dd HH:mm:ss Z yyyy")
                    )
                )
                .Source(d4 => d4
                    .Enabled(false)
                )
            )
            .Settings(d3 => d3
                .NumberOfShards(1)
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->cluster()->putComponentTemplate([
    "name" => "template_1",
    "body" => [
        "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",
                    ],
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.cluster.put_component_template(
  name: "template_1",
  body: {
    "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"
          }
        }
      }
    }
  }
)

Response

No example

You can include index aliases in a component template. During index creation, the {index} placeholder in the alias name will be replaced with the actual index name that the template gets applied to.

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_component_template/{name}" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "template": {
    "settings": {
      "number_of_shards": 1
    },
    "aliases": {
      "alias1": {},
      "alias2": {
        "filter": {
          "term": {
            "user.id": "kimchy"
          }
        },
        "routing": "shard-1"
      },
      "{index}-alias": {}
    }
  }
}'

Response

No example

Required authorization

Path Parameters

Query Parameters { create , cause , master_timeout , }

Request { template , version , _meta , deprecated , }

Response

Query Parameters

Request