« 创建或更新组件模板 API 创建或更新索引模板 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›索引 API

创建或更新索引模板 API

编辑

创建或更新索引模板 API编辑

创建或更新索引模板。索引模板定义可自动应用于新索引的设置、映射和别名。

response = client.indices.put_index_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'te*'
    ],
    priority: 1,
    template: {
      settings: {
        number_of_shards: 2
      }
    }
  }
)
puts response
PUT /_index_template/template_1
{
  "index_patterns" : ["te*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    }
  }
}

请求编辑

PUT /_index_template/<index-template>

先决条件编辑

  • 如果启用了 Elasticsearch 安全功能，则必须具有 manage_index_templates 或 manage 集群权限 才能使用此 API。

描述编辑

Elasticsearch 根据与索引名称匹配的通配符模式将模板应用于新索引。

索引模板在数据流或索引创建期间应用。对于数据流，这些设置和映射在创建流的后台索引时应用。

在创建索引请求中指定的设置和映射会覆盖索引模板中指定的任何设置或映射。

对索引模板的更改不会影响现有索引，包括数据流的现有后台索引。

索引模板中的注释编辑

您可以在索引模板中使用 C 风格的 /* */ 块注释。您可以在请求正文中的任何位置包含注释，但在左大括号之前除外。

路径参数编辑

<index-template>
（必填，字符串）要创建的索引模板的名称。

查询参数编辑

create
（可选，布尔值）如果为 true，则此请求不能替换或更新现有索引模板。默认为 false。
master_timeout
（可选，时间单位）等待主节点的时间段。如果在超时到期之前主节点不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1 以指示请求永远不会超时。

请求正文编辑

composed_of
（可选，字符串数组）组件模板名称的有序列表。组件模板按指定的顺序合并，这意味着最后指定的组件模板具有最高优先级。有关示例，请参阅组合多个组件模板。
data_stream

（可选，对象）如果包含此对象，则该模板用于创建数据流及其后台索引。支持空对象。

数据流需要具有 data_stream 对象的匹配索引模板。请参阅创建索引模板。

data_stream 的属性
allow_custom_routing
（可选，布尔值）如果为 true，则数据流支持自定义路由。默认为 false。
hidden
（可选，布尔值）如果为 true，则数据流隐藏。默认为 false。
index_mode

（可选，字符串）要创建的数据流类型。有效值为 null（常规数据流）和 time_series（时间序列数据流）。

如果为 time_series，则每个后台索引的 index.mode 索引设置均为 time_series。

index_patterns

（必填，字符串数组）用于在创建期间匹配数据流和索引名称的通配符 (*) 表达式数组。

Elasticsearch 包含多个内置索引模板。为避免与这些模板发生命名冲突，请参阅避免索引模式冲突。

_meta
（可选，对象）有关索引模板的可选用户元数据。可以有任何内容。此映射不是由 Elasticsearch 自动生成的。
priority
（可选，整数）在创建新的数据流或索引时确定索引模板优先级的优先级。选择优先级最高的索引模板。如果未指定优先级，则将模板视为优先级为 0（最低优先级）。此数字不是由 Elasticsearch 自动生成的。
template

（可选，对象）要应用的模板。它可以选择性地包含 aliases、mappings 或 settings 配置。

template 的属性
aliases

（可选，对象的 object）要添加的别名。

如果索引模板包含 data_stream 对象，则这些是数据流别名。否则，这些是索引别名。数据流别名会忽略 index_routing、routing 和 search_routing 选项。

aliases 对象的属性
<alias>

（必填，对象）键是别名。索引别名支持日期数学。

对象正文包含别名的选项。支持空对象。

<alias> 的属性
filter
（可选，查询 DSL 对象）用于限制别名可以访问的文档的查询。
index_routing
（可选，字符串）用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden
（可选，布尔值）如果为 true，则别名隐藏。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index
（可选，布尔值）如果为 true，则索引是别名的写入索引。默认为 false。
routing
（可选，字符串）用于将索引和搜索操作路由到特定分片的值。
search_routing
（可选，字符串）用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。
mappings

（可选，映射对象）索引中字段的映射。如果指定，则此映射可以包括

请参阅映射。

settings
（可选，索引设置对象）索引的配置选项。请参阅索引设置。
version
（可选，整数）用于在外部管理索引模板的版本号。此数字不是由 Elasticsearch 自动生成的。
deprecated
（可选，布尔值）将此索引模板标记为已弃用。创建或更新使用已弃用组件的未弃用索引模板时，Elasticsearch 将发出弃用警告。

示例编辑

具有索引别名的索引模板编辑

您可以在索引模板中包含索引别名。

PUT _index_template/template_1
{
  "index_patterns" : ["te*"],
  "template": {
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user.id" : "kimchy" }
            },
            "routing" : "shard-1"
        },
        "{index}-alias" : {} 
    }
  }
}

别名中的 {index} 占位符将在创建索引期间替换为模板应用到的实际索引名称。

多个匹配模板编辑

如果多个索引模板与新索引或数据流的名称匹配，则使用优先级最高的模板。例如

PUT /_index_template/template_1
{
  "index_patterns" : ["t*"],
  "priority" : 0,
  "template": {
    "settings" : {
      "number_of_shards" : 1,
      "number_of_replicas": 0
    },
    "mappings" : {
      "_source" : { "enabled" : false }
    }
  }
}

PUT /_index_template/template_2
{
  "index_patterns" : ["te*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    },
    "mappings" : {
      "_source" : { "enabled" : true }
    }
  }
}

对于以 te* 开头的索引，将启用 _source，并且该索引将具有两个主分片和一个副本，因为只会应用 template_2。

不允许在相同优先级下使用具有重叠索引模式的多个模板，并且在尝试创建与相同优先级的现有索引模板匹配的模板时将引发错误。

模板版本控制编辑

您可以使用 version 参数向索引模板添加版本号。外部系统可以使用这些版本号来简化模板管理。

version 参数是可选的，不会由 Elasticsearch 自动生成或使用。

要取消设置 version，请在不指定版本的情况下替换模板。

response = client.indices.put_index_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'foo',
      'bar'
    ],
    priority: 0,
    template: {
      settings: {
        number_of_shards: 1
      }
    },
    version: 123
  }
)
puts response
PUT /_index_template/template_1
{
  "index_patterns" : ["foo", "bar"],
  "priority" : 0,
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

要检查 version，您可以使用获取索引模板 API。

模板元数据编辑

您可以使用 _meta 参数向索引模板添加任意元数据。此用户定义的对象存储在集群状态中，因此最好将其保持简短。

_meta 参数是可选的，不会由 Elasticsearch 自动生成或使用。

要取消设置 _meta，请在不指定元数据的情况下替换模板。

response = client.indices.put_index_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'foo',
      'bar'
    ],
    template: {
      settings: {
        number_of_shards: 3
      }
    },
    _meta: {
      description: 'set number of shards to three',
      serialization: {
        class: 'MyIndexTemplate',
        id: 17
      }
    }
  }
)
puts response
PUT /_index_template/template_1
{
  "index_patterns": ["foo", "bar"],
  "template": {
    "settings" : {
        "number_of_shards" : 3
    }
  },
  "_meta": {
    "description": "set number of shards to three",
    "serialization": {
      "class": "MyIndexTemplate",
      "id": 17
    }
  }
}

要检查 _meta，您可以使用获取索引模板 API。

数据流定义编辑

要将索引模板用于数据流，该模板必须包含 data_stream 对象。请参阅创建索引模板。

response = client.indices.put_index_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'logs-*'
    ],
    data_stream: {}
  }
)
puts response
PUT /_index_template/template_1
{
  "index_patterns": ["logs-*"],
  "data_stream": { }
}

组合别名、映射和设置编辑

当在索引模板的 composed_of 字段中指定多个组件模板时，它们将按指定的顺序合并，这意味着后面的组件模板会覆盖前面的组件模板。来自父索引模板的任何映射、设置或别名都将合并到下一个。最后，合并索引请求本身上的任何配置。

在此示例中，两个组件模板的顺序更改了索引的分片数

PUT /_component_template/template_with_2_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/template_with_3_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 3
    }
  }
}

PUT /_index_template/template_1
{
  "index_patterns": ["t*"],
  "composed_of": ["template_with_2_shards", "template_with_3_shards"]
}

在这种情况下，匹配 t* 的索引将具有三个主分片。如果组合模板的顺序颠倒，则索引将具有两个主分片。

映射定义以递归方式合并，这意味着后面的映射组件可以引入新的字段映射并更新映射配置。如果字段映射已包含在前面的组件中，则其定义将被后面的组件完全覆盖。

这种递归合并策略不仅适用于字段映射，也适用于根选项，如 dynamic_templates 和 meta。如果前面的组件包含 dynamic_templates 块，则默认情况下，新的 dynamic_templates 条目会附加到末尾。如果已经存在具有相同键的条目，则它将被新定义覆盖。

« 创建或更新组件模板 API 创建或更新索引模板 API »