ElasticSearch的REST APIs 之 索引的别名(alias)管理
基于 ES 7.7, 官方文档
注意: 7.15版本中调整了分类, 把7.7版本中的Add和Update合并为"Create or Update", 更符合es api的定义
主要内容:
- Add index alias: 创建或更新别名
- Delete index alias: 删除索引别名
- Get index alias: 获取索引别名
- Index alias exists: 检查索引别名是否存在
- Update index alias: 添加/删除索引别名
1. Add index alias: 创建或更新索引别名
索引别名， 是一个或多个索引的辅助名称。
大多数 ES api 都接受使用索引别名来代替索引名称。官方文档链接
请求方式
# 支持PUT, POST方式
PUT|POST /<index>/_alias/<alias>
# 用 _aliases 也可以的, 但是我们通常用 _alias, 字母能少写一个是一个
PUT|POST /<index>/_aliases/<alias>
当然也可以使用 `_all`来给当前集群的所有索引添加别名 => 这个有点不正常了
`PUT|POST` /_all/_alias/<alias>
查询参数
- master_timeout
(可选，时间单位）连接到主节点的等待超时时间。如果在超时时间已过之前没有响应, 则返回错误。 默认是值 30s。
- timeout
(可选，时间单位） 等待超时时间。如果在超时时间已过之前没有响应, 则返回错误。 默认是值 30s。
Request body
- filter
(Required, query object) . 筛选查询(Filter query) 用来限制索引别名, 使用该别名时只返回符合过滤条件的文档。（这个应该是有body的时候才是必填的， 没有body就不用填写了）
这个有点像mysql中的view， 同一个table可以建立很多个view， 可以组合不同table的数据， 也可以给不同权限的账号建立不同的view来限制其可以访问的数据
- routing
(Optional, string) 用于将操作路由到特定分片的自定义路由。
几个栗子
1. 添加基于时间(time-based)的别名
比如给索引logs_20302801创建一个别名2030:
PUT /logs_20302801/_alias/2030
2. 添加基于用户(user-based)的别名
创建索引users, 它有一个字段user_id, 然后给个别名user_12, 限制user_id=12的文档:
PUT /users
{
"mappings": {
"properties": {
"user_id":{"type": "integer"}
}
}
}
# 插入几个文档
POST /users/_doc/10
{
"user_id": 10
}
POST /users/_doc/11
{
"user_id": 11
}
POST /users/_doc/12
{
"user_id": 12
}
# 查询, 能看到所有的文档
GET /users/_search
# 给个别名`user_12`, 限制user_id=12的文档:
PUT /users/_alias/user_12
{
"routing": "12",
"filter":{
"term":{
"user_id": 12
}
}
}
# 查询别名, 只能看到 user_id=12的文档
GET /user_12/_search
官方文档举的这个栗子, 朕觉得不是太合适。maybe用"订单列表" 索引, 然后根据订单状态去建别名更适合
3. 在创建索引时添加别名
建立索引 logs_20302801, 同时添加别名 2030
PUT /logs_20302801
{
"mappings" : {
"properties" : {
"year" : {"type" : "integer"}
}
},
"aliases" : {
"current_day" : {},
"2030" : {
"filter" : {
"term" : {"year" : 2030 }
}
}
}
}
2. Delete index alias: 删除索引别名
DELETE /<index>/_alias/<alias>
# 用 _aliases 也可以的, 但是我们通常用 _alias, 字母能少写一个是一个
DELETE /<index>/_aliases/<alias>
路径参数
<index>
支持多个索引以英文逗号连接, 支持通配符。
要匹配所有索引, 可以使用 _all 或者 *
# 删除多个索引的别名
DELETE /twitter,users,orders/_alias/<alias>
# 删除所有索引的别名 ---这个比较危险, 请勿随意测试
DELETE /_all/_alias/<alias>
DELETE /*/_alias/<alias>
<alias>
支持多个索引以英文逗号连接, 支持通配符。
要匹配所有索引别名, 可以使用 _all 或者 *
# 删除指定索引的多个别名
DELETE /<index>/_alias/alias1,alias2,alias3
# 按通配符删除指定索引的别名
DELETE /<index>/_alias/ab*
# 删除指定索引的所有别名
DELETE /<index>/_alias/*
查询参数
- master_timeout
(可选，时间单位）连接到主节点的等待超时时间。如果在超时时间已过之前没有响应, 则返回错误。 默认是值 30s。
- timeout
(可选，时间单位） 等待超时时间。如果在超时时间已过之前没有响应, 则返回错误。 默认是值 30s。
3. Get index alias: 获取索引别名
获取一个或多个索引别名。 官方文档
GET /_alias
GET /_alias/<alias>
GET /<index>/_alias/<alias>
路径参数
<alias>
支持多个索引以英文逗号连接, 支持通配符。
要匹配所有索引别名, 可以使用 _all 或者 *
<index>
支持多个索引以英文逗号连接, 支持通配符。
查询参数
allow_no_indices
默认true。如果设置为true, 则当全部使用通配符*、_all只检索不存在(missing)或者已关闭(closed)的索引时，不会抛出错误。
这个是和参数 expand_wildcards 一起使用时的描述。如果只用通配符去检索expand_wildcards=all的别名, 则无论如何不会抛出错误。但是这里的missing条件怎么理解呢 ？？
# 只是通配符检索别名: 不存在user2开头的别名, 不会报错(返回状态200, 空json)
GET /_alias/user2*?allow_no_indices=false
# 检索不存在的user2, 以及user2开头的别名时, 一定会报错(404 + 错误信息json)
GET /_alias/user2?allow_no_indices=true
GET /_alias/user2,user2*?allow_no_indices=true
# 会报错 - 这个才是符合描述的(条件 expand_wildcards=closed)
GET /_alias/user2*?allow_no_indices=false&expand_wildcards=closed
expand_wildcards
通配符查询时的范围限制. 支持多个条件的逗号连接.
- all: 默认, 匹配open和closed的索引, 包括隐藏的.
- open: 表示只查询开放中的索引
- closed: 只匹配closed的
- hidden: 隐藏的(hidden)索引, 必须和open/closed联合使用.
- none: 不接受通配符.
默认 all
ignore_unavailable
默认false. 如果设置为true, missing或closed的索引不会包括在返回数据中. (官方文档的这种表达, 至今还未理解是什么意思...)
local
是否仅从本地节点获取信息
默认false, 表示从master节点获取信息.
如果设置为true, 则表示只从本地节点获取.
栗子
- 获取当前集群下的所有别名。返回所有索引, 无别名的显示空json
GET /_alias
GET /_all/_alias
GET /*/_alias
返回的json中包含当前集群的所有index, 但是每次返回的顺序可能不同.
- 获取所有索引中有指定别名的，多个别名以英文逗号连接。
只要有一个别名不存在时抛出错误, 返回404状态, 以及能匹配到的部分索引
比如: 存在别名 user_12 和 2030, 不存在别名user_13
GET /_alias/user_13
GET /_alias/user_12,user_13,2030
- 通配符匹配指定的索引别名, 没有数据时返回空json
# 查询所有索引的所有以ab开头的别名
GET /_alias/ab*
# 查询索引user的所有别名
GET /users/_alias/*
# 查询索引user的所有以ab开头的别名
GET /users/_alias/ab*
通配符*的位置任意放, 也可以有多个*
4. Index alias exists: 检查索引别名是否存在
检查一个或多个索引别名是否存在. 官方文档
HEAD /_alias/<alias>
HEAD /<index>/_alias/<alias>
路径参数
<alias>
支持多个索引以英文逗号连接, 支持通配符。
<index>
支持多个索引以英文逗号连接, 支持通配符。
查询参数
同索引别名的获取, 这里省略....
5. Update index alias: 添加/删除索引别名
添加或删除索引别名。
POST /_aliases
{
"actions": [
{
"add": { "index": "twitter", "alias": "twitter_alias1" }
}
]
}
查询参数
- master_timeout
(可选，时间单位）连接到主节点的等待超时时间。如果在超时时间已过之前没有响应, 则返回错误。 默认是值 30s。
- timeout
(可选，时间单位） 等待超时时间。如果在超时时间已过之前没有响应, 则返回错误。 默认是值 30s。
Request body
ES 7.15 对本节内容进行了修正, 结构和描述都更清晰(但是属性列表按字母排序了, 而不是优先级排序), 详见官方文档
actions
(必填, json数组对象) 要执行的一系列操作, 可用的action(json的key)包括:
add给索引添加一个别名remove从指定的索引移除一个别名remove_index删除一个索引或索引别名, 类似删除索引api
这些action的属性可以为空. 可用的属性包括:
-
index: 带通配符的表达式. 当参数indices没有指定时必填. -
indices: 索引名称数组. 当参数index没有指定时必填. -
alias: 逗号连接的多个别名, 或带通配符的表达式. 当参数aliases没有指定时必填. -
aliases: 索引别名的数组. 当参数alias没有指定时必填. -
filter: 使用Filter query过滤别名. -
is_hidden: 如果设置为true, 默认将从通配符表达式中排除别名，除非在请求中使用expand_wildcards参数重写别名，类似于hidden indices。对于共享一个别名的素有索引来说, 这个属性必须设置成相同的值。默认是false。 -
is_write_index: 如果为true，则将此索引指定为该别名下的写索引。 默认值为false。一个别名同时只能存在一个写索引。参考write index
-
routing: 用于将操作路由到特定分片的自定义路由值。 参考 Routing -
index_routing: 用于别名索引操作的自定义路由值。 -
search_routing: 用于别名搜索操作的自定义路由值。
栗子
1. 添加别名(Add an alias)
# 添加别名
POST /_aliases
{
"actions":[
{
"remove":{
"index": "my_index",
"alias": "my_index_alias1"
}
}
]
}
2.移除一个别名(Remove an alias)
# 移除别名
POST /_aliases
{
"actions":[
{
"remove":{
"index": "my_index",
"alias": "my_index_alias1"
}
}
]
}
3. 别名重命名(Rename an alias)
Rename = Remove + Add
重命名实际上是两个操作: 先删除, 后添加, 可以一起操作. 而且这是一个原子操作, 不会出现短时间内别名无法使用的情况
# 别名重命名: 删除 + 添加
POST /_aliases
{
"actions":[
{
"remove":{
"index": "my_index",
"alias": "my_index_alias1"
}
},
{
"add":{
"index": "my_index",
"alias": "my_index_alias_1"
}
}
]
}
4. 同时给多个索引添加别名
- 同时给多个索引添加不同的别名
# 同时给多个索引添加不同的别名(这个写法也支持添加相同的别名)
POST /_aliases
{
"actions":[
{
"add": {
"index": "my_index",
"alias": "my_index_alias1"
}
},
{
"add":{
"index": "my_index2",
"alias": "my_index2_alias1"
}
}
]
}
- 同时给多个索引添加相同的别名
同时给多个索引添加相同的别名
POST /_aliases
{
"actions":[
{
"add":{
"index": "my_index",
"alias": "alias1"
}
},
{
"add":{
"index": "my_index2",
"alias": "alias1"
}
}
]
}
同时给多个索引添加相同的别名时, 可以直接设置一个indices数组以取代多个add操作:
# 同时给多个索引添加相同的别名, 可以使用indices数组以取代多个add操作
POST /_aliases
{
"actions":[
{
"add":{
"indices": ["test1", "test2"],
"alias": "alias1"
}
}
]
}
也可以对index使用通配符来同时给一批索引添加同一个别名:
# 添加多个索引
PUT /test1
PUT /test2
PUT /test3
# 查看索引
GET /test*
# 批量添加别名
POST /_aliases
{
"actions":[
{
"add":{
"index": "test*",
"alias": "all_test_indices"
}
}
]
}
# 查看索引, 我们会看到这三个以test开头的索引都有一个相同的别名
GET /test*
我们还可以交换(swap)一个索引和一个索引别名的名字, 而且是一个原子操作, 这不会出现短时间内别名无法使用的情况.
# 我们先建了一个索引`log`, 但是这个是错误的
PUT /log
# 现在建立了正确的索引`log_001`, 但是我现在想把那个索引名称`log`给这个当别名
PUT /log_001
# 我们可以使用如下的原子操作, 保证服务不会中断
POST /_aliases
{
"actions":[
{
"add": {
"index": "log_001", "alias": "log"
}
},
{
"remove_index":{
"index": "log"
}
}
]
}
# 查看索引/别名, 我们我们会发现别名log也指向了log_001
GET /log_001,log
5. 过滤别名(Filter aliases)
带过滤器的别名提供了一种简单的创建一个索引的不同“视图”的方法。 该过滤器可以使用Query DSL定义，并应用于使用此别名的所有搜索、计数、按查询删除等操作。
我们先创建一个索引, 然后使用filter条件建立一个索引别名
# 创建一个索引, 包含字段 user
PUT /test1
{
"mappings": {
"properties": {
"user":{
"type": "keyword"
}
}
}
}
# 然后我们对字段user建"视图": 使用条件 user="kimchy" 的全匹配, 添加过滤别名
POST /_aliases
{
"actions":[
{
"add":{
"index": "test1",
"alias": "test1_kimchy",
"filter":{
"term":{
"user": "kimchy"
}
}
}
}
]
}
好了, 现在如果我们查询索引别名test1_kimchy, 则只显示test1中 user="kimchy" 的文档
6. 路由(Routing)
可以将路由值(routing values)与别名关联起来, 还可以与过滤别名(filter aliases)一起使用以减少不必要的分片操作.
我们给索引test建一个别名alias1, 定义这个别名的操作都自动指向路由值为"1"的分片.
POST /_aliases
{
"actions":[
{
"add":{
"index": "test",
"alias": "alias1",
"routing": "1"
}
}
]
}
也可以按操作区分搜索(searching)和索引(indexing)分别指向不同的路由:
POST /_aliases
{
"actions":[
{
"add":{
"index": "test",
"alias": "alias1",
"search_routing": "1,2",
"index_routing": "1"
}
}
]
}
上面的例子中，搜索路由包含多个用逗号分隔的值，索引路由只包含一个值。
If a search operation that uses routing alias also has a routing parameter, an intersection of both search alias routing and routing specified in the parameter is used. For example the following command will use "2" as a routing value: 如果使用路由别名的搜索操作也有路由参数，则使用搜索别名路由和参数中指定的路由的交集。 例如，下面的命令将使用"2"作为路由值:
GET /alias2/_search?q=user:kimchy&routing=2,3
alias2的search_routing是"1,2", 而上面的搜索命令中指定"2,3", 他们的交集是 "2"
7. 写索引(Write index)
可以关联设置别名所指向的索引为写索引。 指定后，指向多个索引的别名的所有索引(index, 动词)和更新(update)请求将尝试解析到那个写索引。 每次只能为每个别名分配一个索引作为写索引。 如果没有指定写索引，并且别名引用了多个索引，则不允许写。
可以使用aliases API和创建索引API将与别名关联的索引指定为写索引。
Setting an index to be the write index with an alias also affects how the alias is manipulated during Rollover
通过别名来设置一个索引为写索引会影响在Rollover期间如何操作别名, 参考 Rollover With Write Index
POST /_aliases
{
"actions":[
{
"add":{
"index": "test",
"alias": "alias1",
"is_write_index": true
}
},
{
"add":{
"index": "test2",
"alias": "alias1"
}
}
]
}
这个例子中, 我们把别名alias1同时执行索引test和test2, 但是只指定索引test为写索引.
PUT /alias1/_doc/1
{
"foo": "bar"
}
然后通过别名alias1的写和索引操作将指向索引test, 上面的代码会把id=1的文档写入索引test中:
GET /test/_doc/1
To swap which index is the write index for an alias, the Aliases API can be leveraged to do an atomic swap. The swap is not dependent on the ordering of the actions.
要在一个别名所指向的多个索引之间交换写索引的设置, 可以利用Aliases API来执行原子交换。 交换不依赖于操作的顺序。
POST /_aliases
{
"actions":[
{
"add": {
"index": "test",
"alias": "alias1",
"is_write_index": false
}
},
{
"add": {
"index": "test2",
"alias": "alias1",
"is_write_index": true
}
}
]
}
last update at 2021/10/25 23:17
