ElasticSearch的REST APIs 之 索引的mapping管理

基于ES 7.7

包括4个api: Put mapping, Get mapping, Get field mapping, Type exists

获取/Get mapping

获取集群中索引的mapping定义。 官方文档

# 获取集群里所有索引的mapping
GET /_all/_mapping
GET /_mapping

# 获取指定索引的mapping, 可以指定索引名称或者别名
GET /<index_name_OR_index_alias>/_mappig

# 同时获取多个索引的maping, 多个索引之间以逗号连接
GET /index1,index2,index3/_mapping

ES 7.0.0版本开始弃用type, mapping定义中不再返回. 如果需要旧的格式, 可以使用参数 include_type_name=true

查询参数

allow_no_indices

当没有匹配的索引时，是否正常返回数据(否则抛出错误)。

如果设置为true, 则当使用通配符(*)、索引别名、_all匹配到的索引不存在(missing)或者已关闭(closed)时, 不会抛出错误。

默认false, 表示会抛出错误。

expand_wildcards

通配符查询时可以匹配的索引的条件， 多个值之间以英文逗号连接， 比如"open,hidden"。默认open。可用的值有：

• all: 匹配所有open和closed的索引, 包括隐藏的(hidden).
• open: 默认, 表示只匹配开放中的索引
• closed: 只匹配关闭的(closed)的索引
• hidden: 匹配隐藏的(hidden)的索引, 必须和open/closed联合使用. (官方文档说open和closed可以一起用, WAF??)
• none: 不接受通配符.

ignore_unavailable

如果有索引不存在时是否忽略。

默认false，就是返回404并抛出错误信息。查询时只要有一个索引不存在，则都抛出错误。

官方文档说"If true, missing or closed indices are not included in the response." 这个与实测不同

local

是否仅从本地节点获取信息

默认false，表示从master节点获取信息。

master_timeout

连接到master节点的超时时间，默认 30s

---

---

---

更新/Put mapping

给已现有的索引添加字段, 或者修改现有字段的搜索设置(search settings)。官方文档

#设置单个索引
PUT /<index_name>/_mapping

# 同时设置多个索引(使用同样的mapping)
PUT /<index_name,index_name2>/_mapping

# 更新所有索引: 可以忽略索引名称, 或者使用参数 `_all`
PUT /_all/_mapping
PUT /_maping

查询参数

allow_no_indices

当没有匹配的索引时，是否正常返回数据(否则抛出错误)。

如果设置为true, 则当使用通配符(*)、索引别名、_all匹配到的索引不存在(missing)或者已关闭(closed)时，不会抛出错误。

默认false, 表示会抛出错误。

expand_wildcards

通配符查询时可以匹配的索引的条件， 多个值之间以英文逗号连接， 比如"open,hidden"。默认是open。可用的值有：

• all: 匹配所有open和closed的索引, 包括隐藏的(hidden).
• open: 默认, 表示只匹配开放中的索引
• closed: 只匹配关闭的(closed)的索引
• hidden: 匹配隐藏的(hidden)的索引, 必须和open/closed联合使用. (官方文档说open和closed可以一起用, WAF??)
• none: 不接受通配符.

ignore_unavailable

如果有索引不存在时是否忽略。

默认false，就是返回404并抛出错误信息。查询时只要有一个索引不存在，则都抛出错误。

master_timeout

连接到master节点的超时时间，默认 30s

timeout

等待返回结果的超时时间，默认 30s

Request Body

*properties

必填, mapping对象。字段的mapping。

如果是一个新的字段，会包含以下映射：

• 字段名称
• 字段数据类型
• mapping的参数

如果是已存在的字段, 则参照本节内容后面的 "如果修改已存在字段的映射".

几个栗子

1. 新建索引时

单个索引:

# 单个索引

## 先建立一个索引, 不带mapping
PUT /publications

## 再定义索引的mapping
PUT /publications/_mapping
{
  "properties": {
    "title":  { "type": "text"}
  }
}

同时给多个索引定义一样的mapping:

# 先建立两个索引, 不带mapping
PUT /twitter-1
PUT /twitter-2

# 给这两个索引设置一样的mapping
PUT /twitter-1,twitter-2/_mapping
{
  "properties": {
    "user_name": {
      "type": "text"
    }
  }
}

同时给多个索引设置mapping时, 可以使用通配符, 且遵循 多个索引名称规则(multiple index names)

2. 给已存在的object字段增加新的属性

我们可以使用"put mapping api"给已有的object类型的字段增加新的属性。

我们先新建一个索引，同时指定一个object类型的字段name, 它内部有一个text类型的字段first。

DELETE /my_index
PUT /my_index
{
  "mappings":{
    "properties":{
      "name":{
        "properties": {
          "first":{
            "type": "text"
          }
        }
      }
    }
  }
}

查看mapping, 这时name只有一个字段:

现在我们给这个object类型的字段name添加一个内部的text类型的字段last:

PUT /my_index/_mapping
{
  "properties":{
    "name":{
      "properties":{
        "last":{
          "type": "text"
        }
      }
    }
  }
}

再次查看mapping定义, 会发现name多了一个字段last:

3. 给一个已有的字段增加 multi-fields

multi-fields 可以让你以不同的方式去索引一个字段，从而达到不同的搜索目的。

比如, 建立一个索引, 字段city初始时是一个text类型, 支持全文搜索。

DELETE /my_index
# 建立索引
PUT /my_index
{
  "mappings":{
    "properties":{
      "city":{
        "type": "text"
      }
    }
  }
}

但是在进行 排序 或 聚合 时需要用到keyword类型以提供更高的查询效率。现在我们来给city字段添加一个keyword类型的multi-filed字段raw, 这样就可以提高该字段的排序(sorting)效率。

PUT /my_index/_mapping
{
  "properties":{
    "city":{
      "type":"text",
      "fields":{
        "raw":{
          "type":"keyword"
        }
      }
    }
  }
}

4. 更改已有字段支持的mapping参数

每个mapping参数的文档里有说明是否可以使用 put mapping api 对现有字段进行更新。例如，您可以使用 put mapping api 来更新ignore_above参数。

例如, 我们创建一个索引, 含有一个keyword类型的字段user_id, 且这个字段有一个值为20的参数ignore_above:

DELETE /my_index
PUT /my_index
{
  "mappings":{
    "properties":{
      "user_id":{
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}

现在我们要用api把这个ignore_above参数的值修改为100:

PUT /my_index/_mapping
{
  "properties":{
    "user_id":{
      "type": "keyword",
      "ignore_above": 100
    }
  }
}

5. 修改已有字段的mapping

2021/10/21 18:00 未完待续