管理索引模板

创建、获取、删除可组合索引模板（Composable Index Templates）。

API #

PUT /_index_template/{name}
POST /_index_template/{name}
GET /_index_template
GET /_index_template/{name}
DELETE /_index_template/{name}

API 的作用 #

索引模板允许您定义在创建新索引时自动应用的设置、映射和别名。

可组合索引模板 #

可组合索引模板是 Easysearch 推荐的模板管理方式，具有以下特点：

模块化：由组件模板（component templates）组成
可组合：多个模板可以组合在一起
优先级：通过 priority 控制模板应用顺序
版本控制：支持版本号管理

API 的参数 #

创建/更新索引模板 #

路由参数 #

参数	类型	是否必填	描述
`{name}`	字符串	必需	索引模板名称

Query String 参数 #

参数	类型	是否必填	默认值	描述
`cause`	字符串	否	api	创建/更新索引模板的原因
`create`	布尔值	否	false	是否只创建新模板，不允许更新已存在的模板
`master_timeout`	时间值	否	30s	连接到主节点的超时时间

请求体参数 #

参数	类型	是否必填	描述
`index_patterns`	数组	必需	匹配的索引模式列表，如 `["logs-", "metrics-"]`
`priority`	整数	否	模板优先级，数值越大优先级越高
`template`	对象	是	模板配置，包含 settings、mappings、aliases
`version`	整数	否	模板版本号
`_meta`	对象	否	模板元数据

获取索引模板 #

路由参数 #

参数	类型	是否必填	描述
`{name}`	字符串	否	索引模板名称，支持逗号分隔的多个名称。不指定则获取所有模板

Query String 参数 #

参数	类型	是否必填	默认值	描述
`flat_settings`	布尔值	否	false	是否以扁平格式返回设置
`local`	布尔值	否	false	是否只从本地节点获取信息
`master_timeout`	时间值	否	30s	连接到主节点的超时时间

删除索引模板 #

路由参数 #

参数	类型	是否必填	描述
`{name}`	字符串	必需	要删除的索引模板名称

Query String 参数 #

参数	类型	是否必填	默认值	描述
`master_timeout`	时间值	否	30s	连接到主节点的超时时间
`timeout`	时间值	否	默认超时	操作超时时间

示例 #

创建索引模板 #

PUT /_index_template/logs_template
{
  "index_patterns": ["logs-*"],
  "priority": 100,
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" },
        "message": { "type": "text" },
        "level": { "type": "keyword" }
      }
    },
    "aliases": {
      "logs_current": {}
    }
  }
}

响应示例：

{
  "acknowledged": true
}

只创建不更新 #

PUT /_index_template/logs_template?create=true
{
  "index_patterns": ["logs-*"],
  "template": { ... }
}

获取所有模板 #

GET /_index_template

获取特定模板 #

GET /_index_template/logs_template

获取多个模板 #

GET /_index_template/logs_template,metrics_template

以扁平格式获取 #

GET /_index_template/logs_template?flat_settings=true

删除模板 #

DELETE /_index_template/logs_template

响应示例：

{
  "acknowledged": true
}

使用组件模板 #

# 先创建组件模板
PUT /_component_template/logs_settings
{
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    }
  }
}

# 在索引模板中引用组件模板
PUT /_index_template/logs_template
{
  "index_patterns": ["logs-*"],
  "priority": 100,
  "composed_of": ["logs_settings"],
  "template": {
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" }
      }
    }
  }
}

设置优先级 #

PUT /_index_template/default_logs
{
  "index_patterns": ["logs-*"],
  "priority": 50,
  "template": {
    "settings": {
      "number_of_replicas": 0
    }
  }
}

PUT /_index_template/production_logs
{
  "index_patterns": ["logs-prod-*"],
  "priority": 100,
  "template": {
    "settings": {
      "number_of_replicas": 2
    }
  }
}

添加版本和元数据 #

PUT /_index_template/logs_template
{
  "index_patterns": ["logs-*"],
  "version": 1,
  "_meta": {
    "description": "Logs index template",
    "owner": "data-team"
  },
  "template": { ... }
}

模板优先级 #

当多个模板匹配同一个索引时：

按 priority 降序应用
相同优先级时按名称字典序
后应用的模板设置会覆盖先应用的

优先级	应用顺序
高值	优先应用
相同	按名称排序

索引模式 #

支持通配符模式：

模式	匹配示例
`logs-*`	logs-2024, logs-app
`*_prod`	app_prod, db_prod
`test-*`	test-1, test-data

错误处理 #

模板已存在（create=true） #

{
  "error": {
    "type": "resource_already_exists_exception",
    "reason": "index_template [logs_template] already exists"
  }
}

模板不存在 #

{
  "error": {
    "type": "index_template_missing_exception",
    "reason": "index_template [logs_template] missing"
  }
}

使用场景 #

场景 1：时间序列索引 #

PUT /_index_template/metrics_template
{
  "index_patterns": ["metrics-*"],
  "priority": 100,
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1,
      "refresh_interval": "30s"
    }
  }
}

场景 2：环境特定配置 #

# 开发环境
PUT /_index_template/dev_logs
{
  "index_patterns": ["logs-dev-*"],
  "priority": 100,
  "template": {
    "settings": {
      "number_of_replicas": 0
    }
  }
}

# 生产环境
PUT /_index_template/prod_logs
{
  "index_patterns": ["logs-prod-*"],
  "priority": 200,
  "template": {
    "settings": {
      "number_of_replicas": 2
    }
  }
}

注意事项 #

全局模板限制：全局模板（使用 * 模式）不能设置 index.hidden
不可变设置：某些设置（如 number_of_shards）在索引创建后不能修改
模板验证：模板定义会进行严格验证
向后兼容：保留对旧版模板（/_template）的支持
优先级管理：合理设置优先级避免意外覆盖

标签

索引模板索引管理配置管理