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

创建或更新索引模板 API

编辑

创建或更新索引模板 API

编辑

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

resp = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "template*"
    ],
    priority=1,
    template={
        "settings": {
            "number_of_shards": 2
        }
    },
)
print(resp)
const response = await client.indices.putIndexTemplate({
  name: "template_1",
  index_patterns: ["template*"],
  priority: 1,
  template: {
    settings: {
      number_of_shards: 2,
    },
  },
});
console.log(response);
PUT /_index_template/template_1
{
  "index_patterns" : ["template*"],
  "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（时间序列数据流）和 logsdb（日志数据流）。

模板的 index_mode 设置后备索引的 index.mode。

index_patterns

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

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

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

(可选，对象) 要应用的模板。它可能可选地包含 aliases、mappings 或 settings 配置。

template 的属性
aliases

(可选，对象的对象) 要添加的别名。

如果索引模板包含 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 将发出弃用警告。

示例

编辑

具有索引别名的索引模板

编辑

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

resp = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "template*"
    ],
    template={
        "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.putIndexTemplate({
  name: "template_1",
  index_patterns: ["template*"],
  template: {
    settings: {
      number_of_shards: 1,
    },
    aliases: {
      alias1: {},
      alias2: {
        filter: {
          term: {
            "user.id": "kimchy",
          },
        },
        routing: "shard-1",
      },
      "{index}-alias": {},
    },
  },
});
console.log(response);
PUT _index_template/template_1
{
  "index_patterns" : ["template*"],
  "template": {
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user.id" : "kimchy" }
            },
            "routing" : "shard-1"
        },
        "{index}-alias" : {} 
    }
  }
}

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

多个匹配模板

编辑

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

resp = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "temp*"
    ],
    priority=0,
    template={
        "settings": {
            "number_of_shards": 1,
            "number_of_replicas": 0
        },
        "mappings": {
            "_source": {
                "enabled": False
            }
        }
    },
)
print(resp)

resp1 = client.indices.put_index_template(
    name="template_2",
    index_patterns=[
        "template*"
    ],
    priority=1,
    template={
        "settings": {
            "number_of_shards": 2
        },
        "mappings": {
            "_source": {
                "enabled": True
            }
        }
    },
)
print(resp1)
const response = await client.indices.putIndexTemplate({
  name: "template_1",
  index_patterns: ["temp*"],
  priority: 0,
  template: {
    settings: {
      number_of_shards: 1,
      number_of_replicas: 0,
    },
    mappings: {
      _source: {
        enabled: false,
      },
    },
  },
});
console.log(response);

const response1 = await client.indices.putIndexTemplate({
  name: "template_2",
  index_patterns: ["template*"],
  priority: 1,
  template: {
    settings: {
      number_of_shards: 2,
    },
    mappings: {
      _source: {
        enabled: true,
      },
    },
  },
});
console.log(response1);
PUT /_index_template/template_1
{
  "index_patterns" : ["temp*"],
  "priority" : 0,
  "template": {
    "settings" : {
      "number_of_shards" : 1,
      "number_of_replicas": 0
    },
    "mappings" : {
      "_source" : { "enabled" : false }
    }
  }
}

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

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

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

模板版本控制

编辑

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

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

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

resp = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "foo",
        "bar"
    ],
    priority=0,
    template={
        "settings": {
            "number_of_shards": 1
        }
    },
    version=123,
)
print(resp)
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
const response = await client.indices.putIndexTemplate({
  name: "template_1",
  index_patterns: ["foo", "bar"],
  priority: 0,
  template: {
    settings: {
      number_of_shards: 1,
    },
  },
  version: 123,
});
console.log(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，请替换模板而不指定它。

resp = client.indices.put_index_template(
    name="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
        }
    },
)
print(resp)
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
const response = await client.indices.putIndexTemplate({
  name: "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,
    },
  },
});
console.log(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 对象。请参阅创建索引模板。

resp = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "logs-*"
    ],
    data_stream={},
)
print(resp)
response = client.indices.put_index_template(
  name: 'template_1',
  body: {
    index_patterns: [
      'logs-*'
    ],
    data_stream: {}
  }
)
puts response
const response = await client.indices.putIndexTemplate({
  name: "template_1",
  index_patterns: ["logs-*"],
  data_stream: {},
});
console.log(response);
PUT /_index_template/template_1
{
  "index_patterns": ["logs-*"],
  "data_stream": { }
}

组合别名、映射和设置

编辑

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

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

resp = client.cluster.put_component_template(
    name="template_with_2_shards",
    template={
        "settings": {
            "index.number_of_shards": 2
        }
    },
)
print(resp)

resp1 = client.cluster.put_component_template(
    name="template_with_3_shards",
    template={
        "settings": {
            "index.number_of_shards": 3
        }
    },
)
print(resp1)

resp2 = client.indices.put_index_template(
    name="template_1",
    index_patterns=[
        "t*"
    ],
    composed_of=[
        "template_with_2_shards",
        "template_with_3_shards"
    ],
)
print(resp2)
const response = await client.cluster.putComponentTemplate({
  name: "template_with_2_shards",
  template: {
    settings: {
      "index.number_of_shards": 2,
    },
  },
});
console.log(response);

const response1 = await client.cluster.putComponentTemplate({
  name: "template_with_3_shards",
  template: {
    settings: {
      "index.number_of_shards": 3,
    },
  },
});
console.log(response1);

const response2 = await client.indices.putIndexTemplate({
  name: "template_1",
  index_patterns: ["t*"],
  composed_of: ["template_with_2_shards", "template_with_3_shards"],
});
console.log(response2);
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 »