创建索引别名

为一个或多个索引创建别名，别名可用于简化索引访问、实现零停机重建等场景。

API #

PUT /{index}/_alias/{name}
POST /{index}/_alias/{name}
PUT /{index}/_alias/{name}
PUT /_alias/{name}
PUT /_alias/{name}

API 的作用 #

为索引创建别名，别名是索引的替代名称，可以指向单个或多个索引。

别名的用途 #

用途	描述
简化命名	用简洁别名代替复杂的索引名
零停机切换	在新旧索引间切换实现无缝升级
多索引聚合	一个别名指向多个索引实现统一查询
数据过滤	创建带过滤条件的索引子集视图
路由控制	为别名设置特定的路由规则

创建方式 #

API	用途
`PUT /{index}/_alias/{name}`	为指定索引创建别名
`PUT /_alias/{name}`	创建别名并指定目标索引

API 的参数 #

PUT /{index}/_alias/{name} 参数 #

路由参数 #

参数	类型	是否必填	描述
`{index}`	字符串	必需	索引名称，支持逗号分隔多个索引或通配符
`{name}`	字符串	必需	别名名称

请求体参数 #

{
  "filter": { ... },
  "routing": "value",
  "index_routing": "value",
  "search_routing": "value",
  "is_write_index": true,
  "is_hidden": false
}

参数	类型	是否必填	默认值	描述
`filter`	对象	否	-	过滤查询，只有匹配的文档才会被返回
`routing`	字符串	否	-	默认路由值（索引和搜索操作）
`index_routing`	字符串	否	-	索引操作的路由值
`search_routing`	字符串	否	-	搜索操作的路由值
`is_write_index`	布尔值	否	false	是否为写入索引
`is_hidden`	布尔值	否	false	是否隐藏别名

Query String 参数 #

参数	类型	是否必填	默认值	描述
`timeout`	时间值	否	-	等待响应的超时时间
`master_timeout`	时间值	否	-	等待主节点响应的超时时间
`version`	整数	否	-	期望的版本号
`version_type`	枚举值	否	internal	版本类型：`internal`、`external`、`external_gte`

PUT /_alias/{name} 参数 #

路由参数 #

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

Query String 参数 #

参数	类型	是否必填	默认值	描述
`index`	列表	必需*	-	目标索引名称（逗号分隔）
`timeout`	时间值	否	-	等待响应的超时时间
`master_timeout`	时间值	否	-	等待主节点响应的超时时间

请求体参数 #

{
  "index": ["index1", "index2"],
  "filter": { ... },
  "routing": "value",
  "index_routing": "value",
  "search_routing": "value",
  "is_write_index": true,
  "is_hidden": false
}

示例 #

基本创建 #

PUT /my_index/_alias/my_alias

响应：

{
  "acknowledged": true
}

为多个索引创建别名 #

PUT /logs-2024-01,logs-2024-02/_alias/logs_current

使用通配符 #

PUT /logs-*/_alias/all_logs

创建带过滤器的别名 #

PUT /logs/_alias/error_logs
{
  "filter": {
    "term": {
      "level": "ERROR"
    }
  }
}

创建带路由的别名 #

PUT /my_index/_alias/user1_alias
{
  "routing": "user1"
}

分别设置索引和搜索路由 #

PUT /my_index/_alias/routed_alias
{
  "index_routing": "user1",
  "search_routing": "user1,user2"
}

创建写入索引别名 #

PUT /index_v2/_alias/my_index
{
  "is_write_index": true
}

创建隐藏别名 #

PUT /my_index/_alias/internal_alias
{
  "is_hidden": true
}

使用 PUT /_alias/{name} 创建 #

PUT /_alias/my_alias
{
  "index": "my_index"
}

为多个索引创建别名（使用请求体） #

PUT /_alias/logs
{
  "index": ["logs-2024-01", "logs-2024-02", "logs-2024-03"]
}

创建复杂过滤器别名 #

PUT /logs/_alias/critical_errors
{
  "filter": {
    "bool": {
      "must": [
        { "term": { "level": "ERROR" } },
        { "range": { "@timestamp": { "gte": "now-7d" } } }
      ]
    }
  }
}

零停机索引切换 #

# 1. 创建新索引
PUT /products_v2

# 2. 复制数据
POST /_reindex
{
  "source": { "index": "products_v1" },
  "dest": { "index": "products_v2" }
}

# 3. 创建别名到新索引
PUT /products_v2/_alias/products
{
  "is_write_index": true
}

# 4. 删除旧索引的别名（使用管理索引别名 API）
POST /_aliases
{
  "actions": [
    { "remove": { "index": "products_v1", "alias": "products" } }
  ]
}

创建多租户别名 #

PUT /data/_alias/tenant1
{
  "filter": {
    "term": { "tenant_id": "tenant1" }
  },
  "routing": "tenant1"
}

PUT /data/_alias/tenant2
{
  "filter": {
    "term": { "tenant_id": "tenant2" }
  },
  "routing": "tenant2"
}

使用 URL 参数指定索引 #

PUT /_alias/my_alias?index=index1,index2

设置超时时间 #

PUT /my_index/_alias/my_alias?timeout=30s

带版本控制 #

PUT /my_index/_alias/my_alias?version=1&version_type=external

读写分离配置 #

# 读别名（多索引）
PUT /index_v1,index_v2/_alias/my_index_read

# 写别名（单索引）
PUT /index_v2/_alias/my_index_write
{
  "is_write_index": true
}

时间序列索引别名 #

# 当前月份
PUT /logs-2024-02/_alias/logs_current

# 所有历史
PUT /logs-*/_alias/logs_all

# 仅错误日志
PUT /logs-*/_alias/logs_errors
{
  "filter": {
    "term": { "level": "ERROR" }
  }
}

响应字段说明 #

字段	描述
`acknowledged`	是否确认成功

使用场景 #

场景 1：简化应用配置 #

# 应用只需知道简单的别名
PUT /production-orders-2024.02.01/_alias/orders

# 应用使用
GET /orders/_search
{
  "query": { "match_all": {} }
}

场景 2：蓝绿部署 #

# 创建蓝环境
PUT /api_blue
PUT /api_blue/_alias/api

# 切换到绿环境
PUT /api_green
PUT /api_green/_alias/api
DELETE /api_blue/_alias/api

场景 3：数据视图 #

# 只显示活跃用户
PUT /users/_alias/active_users
{
  "filter": {
    "term": { "status": "active" }
  }
}

# 只显示特定地区
PUT /logs/_alias/asia_logs
{
  "filter": {
    "term": { "region": "asia" }
  }
}

场景 4：按路由分片 #

# 为每个用户创建独立路由的别名
PUT /logs/_alias/user_123_logs
{
  "routing": "user_123"
}

场景 5：索引滚动 #

# 日索引滚动到月度别名
PUT /logs-2024-02-01/_alias/logs_feb
PUT /logs-2024-02-02/_alias/logs_feb
PUT /logs-2024-02-03/_alias/logs_feb

注意事项 #

别名唯一性：别名名称在集群中必须唯一
索引存在性：索引必须存在才能创建别名
写入索引：一个别名只能有一个写入索引
路由优先级：search_routing 优先于 index_routing
别名限制：别名不能指向其他别名
隐藏别名：is_hidden=true 的别名不会在通配符查询中返回

常见错误 #

别名已存在 #

{
  "error": {
    "type": "invalid_alias_name_exception",
    "reason": "Invalid alias name [my_alias], already exists"
  }
}

解决：先删除现有别名再创建

索引不存在 #

{
  "error": {
    "type": "index_not_found_exception",
    "reason": "no such index [nonexistent_index]"
  }
}

解决：先创建索引

多个写入索引 #

{
  "error": {
    "type": "illegal_argument_exception",
    "reason": "Alias [my_alias] has more than one write index"
  }
}

解决：确保只有一个索引设置 is_write_index=true

无效的别名名称 #

{
  "error": {
    "type": "invalid_alias_name_exception",
    "reason": "Invalid alias name [_invalid] (must not start with '_')"
  }
}

解决：使用不以 _ 开头的别名名称（除了系统别名）

最佳实践 #

命名规范：使用有意义的别名名称，如 products_current、logs_errors
文档化：记录别名用途和配置，便于维护
测试：在测试环境验证别名配置后再应用到生产
监控：监控别名的使用情况和性能影响
清理：定期清理不再使用的别名

标签

索引管理别名索引别名