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

创建或更新索引模板 API

编辑

创建或更新索引模板 API

编辑

本文档介绍的是旧版索引模板，该模板已弃用，将被 Elasticsearch 7.8 中引入的可组合模板取代。有关可组合模板的信息，请参阅索引模板。

创建或更新索引模板。

PUT _template/template_1
{
  "index_patterns": ["te*", "bar*"],
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date"
      }
    }
  }
}

请求

编辑

PUT /_template/<index-template>

先决条件

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

描述

编辑

索引模板定义了 设置和 映射，您可以在创建新索引时自动应用这些设置和映射。 Elasticsearch 会根据与索引名称匹配的索引模式将模板应用于新索引。

可组合模板始终优先于旧版模板。如果没有任何可组合模板与新索引匹配，则会按照其顺序应用匹配的旧版模板。

索引模板仅在创建索引期间应用。对索引模板的更改不会影响现有索引。创建索引 API 请求中指定的设置和映射将覆盖索引模板中指定的任何设置或映射。

索引模板中的注释

编辑

您可以在索引模板中使用 C 风格的 /* */ 块注释。您可以将注释包含在请求正文中的任何位置，但不能在开头的花括号之前。

获取模板

编辑

请参阅获取索引模板（旧版）。

路径参数

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

查询参数

编辑
create
（可选，布尔值）如果为 true，则此请求无法替换或更新现有索引模板。默认为 false。
order

（可选，整数）如果索引匹配多个模板，则 Elasticsearch 应用此模板的顺序。

具有较低 order 值的模板首先合并。具有较高 order 值的模板稍后合并，从而覆盖具有较低值的模板。

master_timeout
（可选，时间单位）等待主节点的时间段。如果主节点在超时到期之前不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1 以表示请求永远不应超时。

请求正文

编辑
index_patterns
（必需，字符串数组）用于在创建期间匹配索引名称的通配符表达式数组。
aliases

（可选，对象数组）索引的别名。

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 自动生成的。

示例

编辑

带有索引别名的索引模板

编辑

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

resp = client.indices.put_template(
    name="template_1",
    index_patterns=[
        "te*"
    ],
    settings={
        "number_of_shards": 1
    },
    aliases={
        "alias1": {},
        "alias2": {
            "filter": {
                "term": {
                    "user.id": "kimchy"
                }
            },
            "routing": "shard-1"
        },
        "{index}-alias": {}
    },
)
print(resp)
const response = await client.indices.putTemplate({
  name: "template_1",
  index_patterns: ["te*"],
  settings: {
    number_of_shards: 1,
  },
  aliases: {
    alias1: {},
    alias2: {
      filter: {
        term: {
          "user.id": "kimchy",
        },
      },
      routing: "shard-1",
    },
    "{index}-alias": {},
  },
});
console.log(response);
PUT _template/template_1
{
  "index_patterns" : ["te*"],
  "settings" : {
    "number_of_shards" : 1
  },
  "aliases" : {
    "alias1" : {},
    "alias2" : {
      "filter" : {
        "term" : {"user.id" : "kimchy" }
      },
      "routing" : "shard-1"
    },
    "{index}-alias" : {} 
  }
}

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

匹配多个模板的索引

编辑

多个索引模板可能会匹配一个索引，在这种情况下，设置和映射都会合并到索引的最终配置中。可以使用 order 参数控制合并顺序，较低的顺序先应用，较高的顺序覆盖它们。例如

resp = client.indices.put_template(
    name="template_1",
    index_patterns=[
        "te*"
    ],
    order=0,
    settings={
        "number_of_shards": 1
    },
    mappings={
        "_source": {
            "enabled": False
        }
    },
)
print(resp)

resp1 = client.indices.put_template(
    name="template_2",
    index_patterns=[
        "tes*"
    ],
    order=1,
    settings={
        "number_of_shards": 1
    },
    mappings={
        "_source": {
            "enabled": True
        }
    },
)
print(resp1)
const response = await client.indices.putTemplate({
  name: "template_1",
  index_patterns: ["te*"],
  order: 0,
  settings: {
    number_of_shards: 1,
  },
  mappings: {
    _source: {
      enabled: false,
    },
  },
});
console.log(response);

const response1 = await client.indices.putTemplate({
  name: "template_2",
  index_patterns: ["tes*"],
  order: 1,
  settings: {
    number_of_shards: 1,
  },
  mappings: {
    _source: {
      enabled: true,
    },
  },
});
console.log(response1);
PUT /_template/template_1
{
  "index_patterns" : ["te*"],
  "order" : 0,
  "settings" : {
    "number_of_shards" : 1
  },
  "mappings" : {
    "_source" : { "enabled" : false }
  }
}

PUT /_template/template_2
{
  "index_patterns" : ["tes*"],
  "order" : 1,
  "settings" : {
    "number_of_shards" : 1
  },
  "mappings" : {
    "_source" : { "enabled" : true }
  }
}

上面会禁用存储 _source，但是对于以 tes* 开头的索引，_source 仍将启用。请注意，对于映射，合并是“深层的”，这意味着可以轻松地在较高顺序的模板上添加/覆盖特定的基于对象/属性的映射，而较低顺序的模板提供基础。

具有相同顺序值的多个匹配模板将导致不确定的合并顺序。

模板版本控制

编辑

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

version 参数是完全可选的，不是由 Elasticsearch 自动生成的。

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

resp = client.indices.put_template(
    name="template_1",
    index_patterns=[
        "my-index-*"
    ],
    order=0,
    settings={
        "number_of_shards": 1
    },
    version=123,
)
print(resp)
response = client.indices.put_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'my-index-*'
    ],
    order: 0,
    settings: {
      number_of_shards: 1
    },
    version: 123
  }
)
puts response
const response = await client.indices.putTemplate({
  name: "template_1",
  index_patterns: ["my-index-*"],
  order: 0,
  settings: {
    number_of_shards: 1,
  },
  version: 123,
});
console.log(response);
PUT /_template/template_1
{
  "index_patterns" : ["my-index-*"],
  "order" : 0,
  "settings" : {
    "number_of_shards" : 1
  },
  "version": 123
}

要检查 version，您可以使用带有filter_path查询参数的 获取索引模板 API，以便仅返回版本号

$params = [
    'name' => 'template_1',
];
$response = $client->indices()->getTemplate($params);
resp = client.indices.get_template(
    name="template_1",
    filter_path="*.version",
)
print(resp)
response = client.indices.get_template(
  name: 'template_1',
  filter_path: '*.version'
)
puts response
const response = await client.indices.getTemplate({
  name: "template_1",
  filter_path: "*.version",
});
console.log(response);
GET /_template/template_1?filter_path=*.version

API 返回以下响应

{
  "template_1" : {
    "version" : 123
  }
}
« 创建或更新索引模板 API 删除组件模板 API »