ClusterPutComponentTemplateRequest.ts

/*
 * Licensed to Elasticsearch B.V. under one or more contributor
 * license agreements. See the NOTICE file distributed with
 * this work for additional information regarding copyright
 * ownership. Elasticsearch B.V. licenses this file to you under
 * the Apache License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import { RequestBase } from '@_types/Base'
import { MediaType, Metadata, Name, VersionNumber } from '@_types/common'
import { Duration } from '@_types/Time'
import { IndexTemplateMapping } from '@indices/put_index_template/IndicesPutIndexTemplateRequest'

/**
 * Create or update a component template.
 * 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.
 * @rest_spec_name cluster.put_component_template
 * @availability stack since=7.8.0 stability=stable
 * @availability serverless stability=stable visibility=public
 * @cluster_privileges manage_index_templates
 * @doc_id indices-component-template
 * @doc_tag indices
 */
export interface Request extends RequestBase {
  urls: [
    {
      path: '/_component_template/{name}'
      methods: ['PUT', 'POST']
    }
  ]
  path_parts: {
    /**
     * 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.
     */
    name: Name
  }
  request_media_type: MediaType.Json
  response_media_type: MediaType.Json
  query_parameters: {
    /**
     *  If `true`, this request cannot replace or update existing component templates.
     * @server_default false */
    create?: boolean
    /**
     * User defined reason for create the component template.
     * @server_default api
     */
    cause?: string
    /**
     * 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.
     * @server_default 30s */
    master_timeout?: Duration
  }
  body: {
    /**
     * The template to be applied which includes mappings, settings, or aliases configuration.
     */
    template: IndexTemplateMapping
    /**
     * Version number used to manage component templates externally.
     * This number isn't automatically generated or incremented by Elasticsearch.
     * To unset a version, replace the template without specifying a version.
     */
    version?: VersionNumber
    /**
     * Optional user metadata about the component template.
     * It may have any contents. This map is not automatically generated by Elasticsearch.
     * This information is stored in the cluster state, so keeping it short is preferable.
     * To unset `_meta`, replace the template without specifying this information.
     */
    _meta?: Metadata
    /**
     * Marks this index template as deprecated. When creating or updating a non-deprecated index template
     * that uses deprecated components, Elasticsearch will emit a deprecation warning.
     */
    deprecated?: boolean
  }
}