IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Get Composable Index Templates API Delete Composable Index Template API »

› › ›

Put Composable Index Template API

edit

Put Composable Index Template API

edit

Put Composable Index Template Request

edit

A PutIndexTemplateV2Request specifies the name of a template and the index template configuration which consists of the patterns that control whether the template should be applied to the new index, and the optional mappings, settings and aliases configuration.

PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template"); 
ComposableIndexTemplate composableIndexTemplate =
    new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"), null, null, null, null, null); 
request.indexTemplate(composableIndexTemplate);
assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

	The name of the template
	The index template configuration that specifies the index name patterns this template will match

Settings

edit

The settings of the template will be applied to the new index whose name matches the template’s patterns.

PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template");
Settings settings = Settings.builder() 
    .put("index.number_of_shards", 3)
    .put("index.number_of_replicas", 1)
    .build();
Template template = new Template(settings, null, null); 
ComposableIndexTemplate composableIndexTemplate = new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"),
    template, null, null, null, null); 
request.indexTemplate(composableIndexTemplate);

assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

	Settings for this template
	Configure the settings on the template building block
	Create the IndexTemplateV2 object that configures the index template to apply the defined template to indices matching the patterns

Mappings

edit

The mapping of the template will be applied to the new index whose name matches the template’s patterns.

String mappingJson = "{\n" +
    "  \"properties\": {\n" +
    "    \"message\": {\n" +
    "      \"type\": \"text\"\n" +
    "    }\n" +
    "  }\n" +
    "}"; 
PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template");
Template template = new Template(null, new CompressedXContent(mappingJson), null); 
ComposableIndexTemplate composableIndexTemplate = new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"),
    template, null, null, null, null); 
request.indexTemplate(composableIndexTemplate);

assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

	The mapping, provided as a JSON string
	Configure the mapping on the template building block

Aliases

edit

The aliases of the template will define aliasing to the index whose name matches the template’s patterns. A placeholder {index} can be used in an alias of a template.

PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template");
AliasMetadata twitterAlias = AliasMetadata.builder("twitter_alias").build(); 
AliasMetadata placeholderAlias = AliasMetadata.builder("{index}_alias").searchRouting("xyz").build(); 
Map<String, AliasMetadata> aliases = new HashMap<>();
aliases.put("twitter_alias", twitterAlias);
aliases.put("{index}_alias", placeholderAlias);
Template template = new Template(null, null, aliases); 
ComposableIndexTemplate composableIndexTemplate = new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"),
    template, null, null, null, null); 
request.indexTemplate(composableIndexTemplate);

assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

	The alias to define
	The alias to define with placeholder
	Configure the aliases on the template building block

Component templates

edit

Component templates can be used as building blocks for specifying mappings, settings or aliases configurations, but they don’t apply to indices themselves. To be applied to an index, the component templates must be specified in the componentTemplates list of the IndexTemplateV2 index template definition object. The order in which they are specified in the list is the order in which the component templates are applied.

PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template");
ComposableIndexTemplate composableIndexTemplate =
        new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"), null,
                Collections.singletonList("ct1"), null, null, null); 
request.indexTemplate(composableIndexTemplate);

assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

The component template used by this index template

Priority

edit

In case multiple templates match an index, the priority of matching templates determines the index template which will be applied. Index templates with higher priority "win" over index templates with lower priority.

PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template");
ComposableIndexTemplate composableIndexTemplate = new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"),
    null, null, 20L, null, null); 
request.indexTemplate(composableIndexTemplate);

assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

The priority of the template

Version

edit

A template can optionally specify a version number which can be used to simplify template management by external systems.

PutComposableIndexTemplateRequest request = new PutComposableIndexTemplateRequest()
    .name("my-template");
ComposableIndexTemplate composableIndexTemplate = new ComposableIndexTemplate(Arrays.asList("pattern-1", "log-*"),
    null, null, null, 3L, null); 
request.indexTemplate(composableIndexTemplate);

assertTrue(client.indices().putIndexTemplate(request, RequestOptions.DEFAULT).isAcknowledged());

The version number of the template

Optional arguments

edit

The following arguments can optionally be provided:

request.create(true);

To force to only create a new template; do not overwrite the existing template

request.setMasterTimeout(TimeValue.timeValueMinutes(1));

Timeout to connect to the master node as a TimeValue

Synchronous execution

edit

When executing a PutIndexTemplateV2Request in the following manner, the client waits for the AcknowledgedResponse to be returned before continuing with code execution:

AcknowledgedResponse putTemplateResponse = client.indices().putIndexTemplate(request, RequestOptions.DEFAULT);

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous execution

edit

Executing a PutIndexTemplateV2Request can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous put-index-template-v2 method:

client.indices().putIndexTemplateAsync(request, RequestOptions.DEFAULT, listener);

The PutIndexTemplateV2Request to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for put-index-template-v2 looks like:

ActionListener<AcknowledgedResponse> listener =
    new ActionListener<AcknowledgedResponse>() {
        @Override
        public void onResponse(AcknowledgedResponse putIndexTemplateResponse) {
            
        }

        @Override
        public void onFailure(Exception e) {
            
        }
    };

	Called when the execution is successfully completed.
	Called when the whole `PutIndexTemplateV2Request` fails.

Put Composable Index Template Response

edit

The returned AcknowledgedResponse allows to retrieve information about the executed operation as follows:

boolean acknowledged = putTemplateResponse.isAcknowledged();

Indicates whether all of the nodes have acknowledged the request

« Get Composable Index Templates API Delete Composable Index Template API »