模拟索引模板匹配，验证特定索引名称会应用哪些模板配置。
API #
POST /_index_template/{name}/_simulate
POST /_template/{name}/_simulate
POST /_template/_simulate
API 的作用 #
该 API 用于模拟索引模板的匹配和应用，帮助您：
- 测试特定索引名称会匹配到哪些模板
- 查看模板应用后的最终配置
- 发现可能存在的模板冲突
- 验证新模板配置而无需实际创建索引
两种模拟方式的区别 #
| API | 用途 | name 参数含义 |
|---|---|---|
POST /_index_template/{name}/_simulate | 测试索引名称匹配 | {name} 是索引名称 |
POST /_template/{name}/_simulate | 模拟模板配置 | {name} 是模板名称 |
API 的参数 #
模拟索引名称匹配 #
路由参数 #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
{name} | 字符串 | 必需 | 要测试的索引名称 |
Query String 参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
master_timeout | 时间值 | 否 | 30s | 等待主节点响应的超时时间 |
请求体参数（可选） #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
index_template | 对象 | 否 | 临时模板配置，用于测试 |
create | 布尔值 | 否 | false |
cause | 字符串 | 否 | api |
模拟模板配置 #
路由参数 #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
{name} | 字符串 | 否 | 模板名称，与请求体二选一 |
Query String 参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
master_timeout | 时间值 | 否 | 30s | 等待主节点响应的超时时间 |
请求体参数（可选，但需指定 name 或请求体） #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
index_template | 对象 | 是* | 模板配置对象 |
create | 布尔值 | 否 | false |
cause | 字符串 | 否 | api |
*如果不指定
{name}，则必须在请求体中提供index_template
示例 #
模拟索引名称匹配 #
POST /_index_template/logs-2024-01-01/_simulate
响应示例：
{
"template": {
"settings": {
"index": {
"number_of_shards": "3",
"number_of_replicas": "1"
}
},
"mappings": { ... },
"aliases": { ... }
},
"overlapping": [
{
"name": "logs_template",
"index_patterns": ["logs-*"]
}
]
}
使用临时模板配置测试 #
POST /_index_template/test-index/_simulate
{
"index_template": {
"index_patterns": ["test-*"],
"priority": 100,
"template": {
"settings": {
"number_of_shards": 5
}
}
}
}
模拟现有模板 #
POST /_template/logs_template/_simulate
模拟新模板配置 #
POST /_template/_simulate
{
"index_template": {
"index_patterns": ["logs-*"],
"priority": 100,
"template": {
"settings": {
"number_of_shards": 3
},
"mappings": {
"properties": {
"@timestamp": { "type": "date" }
}
}
}
}
}
测试多个组件模板的组合 #
# 先创建组件模板
PUT /_component_template/common_settings
{
"template": {
"settings": {
"refresh_interval": "5s"
}
}
}
# 模拟索引模板使用组件模板
POST /_index_template/test-index/_simulate
{
"index_template": {
"index_patterns": ["test-*"],
"composed_of": ["common_settings"],
"template": {
"settings": {
"number_of_shards": 3
}
}
}
}
响应字段说明 #
| 字段 | 类型 | 描述 |
|---|---|---|
template | 对象 | 应用后的最终模板配置 |
template.settings | 对象 | 合并后的索引设置 |
template.mappings | 对象 | 合并后的映射定义 |
template.aliases | 对象 | 合并后的别名配置 |
overlapping | 数组 | 与模拟模板产生重叠的其他模板列表 |
overlapping 字段 #
| 字段 | 描述 |
|---|---|
name | 重叠的模板名称 |
index_patterns | 该模板的索引模式 |
使用场景 #
场景 1：验证模板匹配 #
在创建索引前验证模板会正确应用：
POST /_index_template/my_app-prod/_simulate
场景 2：测试新模板配置 #
在部署新模板前测试其效果：
POST /_index_template/test-logs/_simulate
{
"index_template": {
"index_patterns": ["logs-*"],
"priority": 100,
"template": {
"settings": {
"number_of_shards": 5,
"number_of_replicas": 2
}
}
}
}
场景 3：发现模板冲突 #
检查可能产生冲突的模板：
POST /_index_template/app-logs/_simulate
查看 overlapping 字段了解冲突情况。
场景 4：验证组件模板组合 #
POST /_index_template/test-index/_simulate
{
"index_template": {
"index_patterns": ["test-*"],
"composed_of": ["settings_template", "mappings_template"],
"template": {
"aliases": {
"test_alias": {}
}
}
}
}
场景 5：比较不同优先级 #
# 测试低优先级模板
POST /_index_template/test/_simulate
{
"index_template": {
"index_patterns": ["*"],
"priority": 50,
"template": {
"settings": {
"number_of_replicas": 0
}
}
}
}
# 测试高优先级模板
POST /_index_template/test/_simulate
{
"index_template": {
"index_patterns": ["test-*"],
"priority": 100,
"template": {
"settings": {
"number_of_replicas": 2
}
}
}
}
模板优先级模拟 #
当多个模板匹配时，响应会显示最终合并的配置：
{
"template": {
"settings": {
"number_of_shards": "3", // 来自基础模板
"number_of_replicas": "2", // 被高优先级模板覆盖
"refresh_interval": "5s" // 来自组件模板
}
},
"overlapping": [
{
"name": "base_template",
"index_patterns": ["*"],
"priority": 1
},
{
"name": "specific_template",
"index_patterns": ["test-*"],
"priority": 100
}
]
}
两个 API 的选择指南 #
| 需求 | 使用 API |
|---|---|
| 测试特定索引名称会匹配哪些模板 | POST /_index_template/{index_name}/_simulate |
| 验证现有模板的配置 | POST /_template/{template_name}/_simulate |
| 测试新模板配置而不创建 | POST /_template/_simulate + 请求体 |
| 检查模板冲突 | 任一 API，查看 overlapping 字段 |
注意事项 #
- 不会创建索引：模拟操作不会创建实际索引
- 不会保存模板：请求体中的临时模板不会被保存
- 覆盖检测：
overlapping字段帮助发现潜在的配置冲突 - 优先级验证：可以验证不同优先级模板的应用顺序
- 组件模板引用：引用的组件模板必须存在才能正确模拟
