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 未完待續