--- title: "创建索引别名" date: 2026-01-25 lastmod: 2026-01-25 description: "为索引创建别名，支持过滤、路由等高级配置" tags: ["索引管理", "别名", "索引别名"] summary: "为一个或多个索引创建别名，别名可用于简化索引访问、实现零停机重建等场景。 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": { ." --- 为一个或多个索引创建别名，别名可用于简化索引访问、实现零停机重建等场景。 ## 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}` | 字符串 | 必需 | 别名名称 | #### 请求体参数 ```json { "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` | 时间值 | 否 | - | 等待主节点响应的超时时间 | #### 请求体参数 ```json { "index": ["index1", "index2"], "filter": { ... }, "routing": "value", "index_routing": "value", "search_routing": "value", "is_write_index": true, "is_hidden": false } ``` ## 示例 ### 基本创建 ```bash PUT /my_index/_alias/my_alias ``` **响应：** ```json { "acknowledged": true } ``` ### 为多个索引创建别名 ```bash PUT /logs-2024-01,logs-2024-02/_alias/logs_current ``` ### 使用通配符 ```bash PUT /logs-*/_alias/all_logs ``` ### 创建带过滤器的别名 ```bash PUT /logs/_alias/error_logs { "filter": { "term": { "level": "ERROR" } } } ``` ### 创建带路由的别名 ```bash PUT /my_index/_alias/user1_alias { "routing": "user1" } ``` ### 分别设置索引和搜索路由 ```bash PUT /my_index/_alias/routed_alias { "index_routing": "user1", "search_routing": "user1,user2" } ``` ### 创建写入索引别名 ```bash PUT /index_v2/_alias/my_index { "is_write_index": true } ``` ### 创建隐藏别名 ```bash PUT /my_index/_alias/internal_alias { "is_hidden": true } ``` ### 使用 PUT /_alias/{name} 创建 ```bash PUT /_alias/my_alias { "index": "my_index" } ``` ### 为多个索引创建别名（使用请求体） ```bash PUT /_alias/logs { "index": ["logs-2024-01", "logs-2024-02", "logs-2024-03"] } ``` ### 创建复杂过滤器别名 ```bash PUT /logs/_alias/critical_errors { "filter": { "bool": { "must": [ { "term": { "level": "ERROR" } }, { "range": { "@timestamp": { "gte": "now-7d" } } } ] } } } ``` ### 零停机索引切换 ```bash # 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" } } ] } ``` ### 创建多租户别名 ```bash PUT /data/_alias/tenant1 { "filter": { "term": { "tenant_id": "tenant1" } }, "routing": "tenant1" } PUT /data/_alias/tenant2 { "filter": { "term": { "tenant_id": "tenant2" } }, "routing": "tenant2" } ``` ### 使用 URL 参数指定索引 ```bash PUT /_alias/my_alias?index=index1,index2 ``` ### 设置超时时间 ```bash PUT /my_index/_alias/my_alias?timeout=30s ``` ### 带版本控制 ```bash PUT /my_index/_alias/my_alias?version=1&version_type=external ``` ### 读写分离配置 ```bash # 读别名（多索引） PUT /index_v1,index_v2/_alias/my_index_read # 写别名（单索引） PUT /index_v2/_alias/my_index_write { "is_write_index": true } ``` ### 时间序列索引别名 ```bash # 当前月份 PUT /logs-2024-02/_alias/logs_current # 所有历史 PUT /logs-*/_alias/logs_all # 仅错误日志 PUT /logs-*/_alias/logs_errors { "filter": { "term": { "level": "ERROR" } } } ``` ## 响应字段说明 | 字段 | 描述 | |------|------| | `acknowledged` | 是否确认成功 | ## 使用场景 ### 场景 1：简化应用配置 ```bash # 应用只需知道简单的别名 PUT /production-orders-2024.02.01/_alias/orders # 应用使用 GET /orders/_search { "query": { "match_all": {} } } ``` ### 场景 2：蓝绿部署 ```bash # 创建蓝环境 PUT /api_blue PUT /api_blue/_alias/api # 切换到绿环境 PUT /api_green PUT /api_green/_alias/api DELETE /api_blue/_alias/api ``` ### 场景 3：数据视图 ```bash # 只显示活跃用户 PUT /users/_alias/active_users { "filter": { "term": { "status": "active" } } } # 只显示特定地区 PUT /logs/_alias/asia_logs { "filter": { "term": { "region": "asia" } } } ``` ### 场景 4：按路由分片 ```bash # 为每个用户创建独立路由的别名 PUT /logs/_alias/user_123_logs { "routing": "user_123" } ``` ### 场景 5：索引滚动 ```bash # 日索引滚动到月度别名 PUT /logs-2024-02-01/_alias/logs_feb PUT /logs-2024-02-02/_alias/logs_feb PUT /logs-2024-02-03/_alias/logs_feb ``` ## 注意事项 1. **别名唯一性**：别名名称在集群中必须唯一 2. **索引存在性**：索引必须存在才能创建别名 3. **写入索引**：一个别名只能有一个写入索引 4. **路由优先级**：search_routing 优先于 index_routing 5. **别名限制**：别名不能指向其他别名 6. **隐藏别名**：is_hidden=true 的别名不会在通配符查询中返回 ## 常见错误 ### 别名已存在 ```json { "error": { "type": "invalid_alias_name_exception", "reason": "Invalid alias name [my_alias], already exists" } } ``` **解决**：先删除现有别名再创建 ### 索引不存在 ```json { "error": { "type": "index_not_found_exception", "reason": "no such index [nonexistent_index]" } } ``` **解决**：先创建索引 ### 多个写入索引 ```json { "error": { "type": "illegal_argument_exception", "reason": "Alias [my_alias] has more than one write index" } } ``` **解决**：确保只有一个索引设置 is_write_index=true ### 无效的别名名称 ```json { "error": { "type": "invalid_alias_name_exception", "reason": "Invalid alias name [_invalid] (must not start with '_')" } } ``` **解决**：使用不以 _ 开头的别名名称（除了系统别名） ## 最佳实践 1. **命名规范**：使用有意义的别名名称，如 `products_current`、`logs_errors` 2. **文档化**：记录别名用途和配置，便于维护 3. **测试**：在测试环境验证别名配置后再应用到生产 4. **监控**：监控别名的使用情况和性能影响 5. **清理**：定期清理不再使用的别名