› › ›

创建或更新索引模板 API

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

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

创建或更新索引模板。

$params = [
    'name' => 'template_1',
    'body' => [
        'index_patterns' => [
            'te*',
            'bar*',
        ],
        'settings' => [
            'number_of_shards' => 1,
        ],
        'mappings' => [
            '_source' => [
                'enabled' => false,
            ],
            'properties' => [
                'host_name' => [
                    'type' => 'keyword',
                ],
                'created_at' => [
                    'type' => 'date',
                    'format' => 'EEE MMM dd HH:mm:ss Z yyyy',
                ],
            ],
        ],
    ],
];
$response = $client->indices()->putTemplate($params);

const response = await client.indices.putTemplate({
  name: 'template_1',
  body: {
    index_patterns: [
      'te*',
      'bar*'
    ],
    settings: {
      number_of_shards: 1
    },
    mappings: {
      _source: {
        enabled: false
      },
      properties: {
        host_name: {
          type: 'keyword'
        },
        created_at: {
          type: 'date',
          format: 'EEE MMM dd HH:mm:ss Z yyyy'
        }
      }
    }
  }
})
console.log(response)

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",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}

请求编辑

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: (可选，字符串) 用于将索引操作路由到特定分片的 value。如果指定，则会覆盖索引操作的 routing value。
is_hidden: (可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引都必须具有相同的 is_hidden value。
is_write_index: (可选，布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的 value。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的 value。如果指定，则会覆盖搜索操作的 routing value。

mappings

(可选，映射对象) 索引中字段的映射。如果指定，则此映射可以包含

请参见映射。

settings

(可选，索引设置对象) 索引的配置选项。请参见索引设置。

version

(可选，整数) 用于在外部管理索引模板的版本号。此数字不是由 Elasticsearch 自动生成的。

示例编辑

包含索引别名的索引模板编辑

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

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 参数控制合并顺序，较低的顺序会先应用，较高的顺序会覆盖它们。例如

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，请在不指定版本的情况下替换模板。

response = client.indices.put_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'my-index-*'
    ],
    order: 0,
    settings: {
      number_of_shards: 1
    },
    version: 123
  }
)
puts response

PUT /_template/template_1
{
  "index_patterns" : ["my-index-*"],
  "order" : 0,
  "settings" : {
    "number_of_shards" : 1
  },
  "version": 123
}

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

$params = [
    'name' => 'template_1',
];
$response = $client->indices()->getTemplate($params);

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 »