Component template APIs

You can use the component template APIs to create, retrieve, update, and delete component templates. A component template is a reusable building block that defines settings, mappings, and aliases and can be shared across multiple index templates.

An index template can be constructed using multiple component templates. To incorporate a component template into an index template, you need to list it in the composed_of section of the index template. Component templates are only applied to newly created data streams and indexes that match the criteria specified in the index template.

If any settings or mappings are directly defined in the index template or the index creation request, those settings will take precedence over the settings or mappings specified in a component template.

Component templates are used solely during the process of index creation. For data streams, this includes the creation of the data stream itself and the creation of the backing indexes that support the stream. Modifications made to component templates will not affect existing indexes, including the backing indexes of a data stream.

Endpoints

PUT _component_template/<component-template-name>
GET _component_template/<component-template-name>
DELETE _component_template/<component-template-name>
HEAD _component_template/<component-template-name>

• PUT: Creates or updates a component template. Accepts both query parameters and a request body.
• GET: Retrieves information about an existing component template. Accepts only query parameters.
• DELETE: Deletes an existing component template. Accepts only query parameters.
• HEAD: Returns whether a component template exists. Returns only HTTP status codes.

Path parameters

The following table lists the available path parameters.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Create or update a component template

Use the PUT operation to create a new component template or update an existing one.

Endpoints

PUT _component_template/<component-template-name>

Request body fields

The following table lists the available request body fields.

Template

You can use the following objects with the template option in the request body.

alias

The name of the alias to associate with the template as a key. Required when the template option exists in the request body. This option supports multiple aliases.

The object body contains the following optional alias parameters.

mappings

The field mappings that exist in the index. For more information, see Mappings and field types. Optional.

settings

Any configuration options for the index. For more information, see Index settings.

Example request: Create a component template with index aliases

The following example request creates a component template including index aliases:

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

response = client.cluster.put_component_template(
  name = "alias_template",
  body =   {
    "template": {
      "settings": {
        "number_of_shards": 1
      },
      "aliases": {
        "alias1": {},
        "alias2": {
          "filter": {
            "term": {
              "user.id": "hamlet"
            }
          },
          "routing": "shard-1"
        },
        "{index}-alias": {}
      }
    }
  }
)

Example request: Add component versioning

The following example adds a version number to a component template which simplifies template management for external systems:

PUT /_component_template/version_template
{
  "template": {
    "settings": {
      "number_of_shards": 1
    }
  },
  "version": 3
}

response = client.cluster.put_component_template(
  name = "version_template",
  body =   {
    "template": {
      "settings": {
        "number_of_shards": 1
      }
    },
    "version": 3
  }
)

Example request: Add template metadata

The following example request uses the _meta parameter to add metadata to the component template. All metadata is stored in the cluster state.

PUT /_component_template/meta_template
{
  "template": {
    "settings": {
      "number_of_shards": 1
    }
  },
  "_meta": {
    "description": "Where art thou",
    "serialization": {
      "class": "MyIndexTemplate",
      "id": 12
    }
  }
}

response = client.cluster.put_component_template(
  name = "meta_template",
  body =   {
    "template": {
      "settings": {
        "number_of_shards": 1
      }
    },
    "_meta": {
      "description": "Where art thou",
      "serialization": {
        "class": "MyIndexTemplate",
        "id": 12
      }
    }
  }
)

Retrieve component template

Use the GET operation to retrieve one or more component templates and their information.

Endpoints

GET /_component_template/<component-template-name>
GET /_component_template

Path parameters

The following table lists the available path parameters. All path parameters are optional.

Example request: Retrieve a component template by name

GET /_component_template/my_template

response = client.cluster.get_component_template(
  name = "my_template"
)

Example request: Retrieve component templates using a wildcard pattern

GET /_component_template/my_template*

response = client.cluster.get_component_template(
  name = "my_template*"
)

Example request: Retrieve all component templates

GET /_component_template

response = client.cluster.get_component_template()

Delete component template

Use the DELETE operation to remove a component template from the cluster.

Important considerations:

• Deleting a component template does not affect existing indexes that were created using the template.
• You cannot delete a component template that is currently referenced by an index template.
• The operation is irreversible.

Endpoints

DELETE _component_template/<component-template-name>

Example request

DELETE /_component_template/my_template

response = client.cluster.delete_component_template(
  name = "my_template"
)

Check whether a component template exists

Use the HEAD operation to check whether a component template exists without retrieving its contents. This operation returns only HTTP status codes and headers, with no response body.

Endpoints

HEAD _component_template/<component-template-name>

Example request

HEAD /_component_template/my_template

response = client.cluster.exists_component_template(
  name = "my_template"
)

Response codes

• 200: The component template exists.
• 404: The component template does not exist.