# 管理单元

ES 的管理单元从上到下依次分为：

index
type
document

# index

ES 中可以创建多个索引（index）。
index 名不能包含大写字母，不能以下划线开头。

# 查

相关 API ：

GET   /<index>                  # 查询索引的配置信息，包括 alias、mappings、settings
GET   /<index>/_alias
GET   /<index>/_mapping
GET   /<index>/_settings
GET   /<index>/_stats           # 查询索引的统计信息

HEAD  /<index>                  # 检查索引是否存在。如果查询的所有索引都存在，则返回 HTTP 200 ，否则返回 HTTP 404
GET   /_resolve/index/<name>    # 解析一个名称，返回与之匹配的所有的 indices、aliases、data_streams

<index> 可以填一个 index 名，或者 index pattern 。

# 增

相关 API ：

PUT   /<index>  [request_body]    # 创建索引，可以在 request_body 中加上配置信息，如果不加则使用索引模板的默认配置

例：直接创建索引

[[email protected] ~]# curl -X PUT 127.0.0.1:9200/class?pretty
{
  "acknowledged" : true,          # 表示操作成功
  "shards_acknowledged" : true,   # 表示已经启动分片
  "index" : "class"               # 索引名
}

如果请求创建的索引已存在，则会返回 HTTP 400 。

例：在创建索引时加上配置信息
```
PUT /my-index-1
{
  "aliases": {...},
  "mappings": {...},
  "settings": {...}
}
```
- index 的配置主要分为 aliases、mappings、settings 三种。
- 如果在创建 index 时不指定某一配置，则采用 index template 中的默认配置。

# 改

相关 API ：

PUT   /<index>/_alias     <request_body>    # 修改索引的别名
PUT   /<index>/_mapping   <request_body>
PUT   /<index>/_settings  <request_body>    # 修改索引的配置。这是增量修改，不会覆盖未指定的配置参数

POST  /<index>/_close   # 关闭索引，禁止读、写操作，但可以删除索引
POST  /<index>/_open    # 打开已关闭的索引

# 删

相关 API ：

DELETE /<index>         # 删除索引。如果该索引不存在，则会返回 HTTP 404

# type

向一个 index 新增 document 时，需要指定其所属的索引类型（type）。

官方计划逐步取消 type 的设定：

老版本的 ES 允许在每个 index 的 mappings 中定义多个 type ，格式如下：

PUT /my-index-1
{
  "mappings": {
    "_default_": {      # 该 type 名为 _default_ ，会用作新增文档时的默认类型
      "dynamic_templates": [...],
      "properties": {...}
    },
    "type-1": {
      "dynamic_templates": [...],
      "properties": {...}
    },
    "type-2": {
      "dynamic_templates": [...],
      "properties": {...}
    }
  }
}

ES 6.0 版本开始，每个索引只能定义一个 type ，默认命名为 _doc 。格式如下：

PUT /my-index-1
{
  "mappings": {
    "_doc": {
      "dynamic_templates": [...],
      "properties": {...}
    }
  }
}

ES 7.0 版本开始，不推荐使用 type 。配置 mappings 的格式如下：

PUT /my-index-1
{
  "mappings": {
    "dynamic_templates": [...],
    "properties": {...}
  }
}

ES 8.0 版本开始，禁用 type 。

# document

一个 index 中可以写入多个文档，每个文档（document）是一个 JSON 格式的文本。
新增文档的过程又称为 "索引文档" 。
ES 默认会对文档的每个字段建立倒排索引，因此支持全文搜索。

# 查

相关 API ：

GET   /<index>/_doc/<_id>   # 查询指定 _id 的文档的内容
HEAD  /<index>/_doc/<_id>   # 查询指定 _id 的文档是否存在

GET   /_count               # 查询所有索引包含的文档数
GET   /<index>/_count       # 查询指定索引包含的文档数

例：查询文档

[[email protected] ~]# curl -X GET 127.0.0.1:9200/student/_doc/1?pretty
{
  "_index" : "student",
  "_type" : "_doc",
  "_id" : "1",
  "_version" : 9,
  "_seq_no" : 17,
  "_primary_term" : 1,
  "found" : true,       # 表示成功找到了该文档
  "_source" : {
    "name" : "Leo",
    "age" : 10,
    "interests" : [
      "sports",
      "music"
    ]
  }
}

# 增

相关 API ：

POST  /<index>/_doc         <request_body>  # 新增文档
POST  /<index>/_doc/<_id>   <request_body>  # 新增文档，覆盖指定 _id 的文档

写入文档时，可以带上以下 URL 参数：
- timeout
  - 默认为 1m 。
- op_type
  - ：操作类型。如果在 URL 中指定了文档 _id ，则默认为 index 类型，否则为 create 类型。
  - 若为 create ，则不存在相同 _id 的文档时才能写入，否则报错：version conflict, document already exists
  - 若为 index ，则写入的文档会覆盖相同 _id 的文档。
- refresh
  - 默认为 false 。
  - 若为 true ，则立即执行一次 Refresh ，刷新完之后才返回响应。注意只会刷新当前修改的 Shards ，不会影响所有 Shards 。
  - 若为 wait_for ，则等到下一次定时刷新之后，才返回响应。
- wait_for_active_shards
  - ：等待写操作同步到多少个 shard ，才返回响应。
  - 默认为 1 ，即只需写入 1 个主分片，不需要同步到副分片。
- routing
  - ES 会计算 hash(routing) % number_of_shards = shard_id ，决定将 HTTP 请求路由到当前索引的哪个分片。
  - routing 参数默认等于文档的 _id ，也可以指定其它值。
  - 因此，ES 创建索引之后不支持修改 number_of_shards ，否则路由关系变化，不能定位已有的文档。

例：新增文档

[[email protected]ntOS ~]# curl -X POST 127.0.0.1:9200/student/_doc?pretty -H 'content-Type:application/json' -d '
> {
>   "name" : "Leo",
>   "age" : 10,
>   "interests": [ "sports", "music" ]
> }'
{
  "_index" : "student",
  "_type" : "_doc",
  "_id" : "ZhzMiXABzduhqPWX7mUX",
  "_version" : 1,
  "result" : "created",             # 表示成功创建了该文档
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

这里是以 /<index>/<type> 作为 HTTP 请求的目标 URL 。
新增文档时，如果对应的 index 和 type 不存在，则 ES 会自动创建。

ES 会自动为每个文档添加一些元数据，元数据的字段名以一个下划线开头，如下：

_index          # 该文档所属的索引名
_type           # 该文档所属的 type 名
_id             # 一个任意内容的字符串，默认是随机生成。同一 type 下，每个文档的 _id 值是唯一的
_source         # 一个字典，保存该文档的主体内容，即新增该文档时的 POST body 。 _source 字段没有建立索引，不支持直接搜索它
_version        # 一个从 1 开始递增的数字，表示该文档经过了几次写操作（包括 POST、PUT、DELETE）
_seq_no         # 一个从 0 开始递增的数字，表示这是对该 type 的第几次写操作
_primary_term   # 一个从 1 开始递增的数字，表示这是第几次 Primary Shard

# 删

相关 API ：

DELETE /<index>/_doc/<_id>    # 删除文档

例：删除文档

[[email protected] ~]# curl -X DELETE 127.0.0.1:9200/student/_doc/8?pretty
{
  "_index" : "student",
  "_type" : "_doc",
  "_id" : "8",
  "_version" : 2,
  "result" : "deleted",       # 已删除该文档
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 25,
  "_primary_term" : 1
}

[[email protected] ~]# curl -X DELETE 127.0.0.1:9200/student/_doc/8?pretty
{
  "_index" : "student",
  "_type" : "_doc",
  "_id" : "8",
  "_version" : 3,
  "result" : "not_found",     # 该文档不存在
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 26,
  "_primary_term" : 1
}

# bulk

：用于批量处理多个文档，提高效率。

用法：

准备一组 JSON 文本，描述需要处理的多个文档。每个文档需要声明两行信息：

{ action: { metadata }}
{ request_body        }

action 表示操作类型，分为多种：

create    # 新增文档。如果不指定 id ，则自动生成。如果指定了 id ，且已存在相同 id 的文档，则不新增
index     # 写入文档。如果不指定 id ，则自动生成。如果指定了 id ，且已存在相同 id 的文档，则覆盖它
update    # 更新文档。如果不指定 id ，则自动生成。如果指定了 id ，且已存在相同 id 的文档，则更新它的部分内容
delete    # 删除文档，必须指定 id ，不需要带上 request_body

例：创建一个 students.json 文件

{ "index" : { "_index" : "student", "_id" : "1" } }
{ "name" : "Leo", "age" : 10 }
{ "create" : { "_index" : "student", "_id" : "1" } }
{ "name" : "Leo", "age" : 10 }
{ "update" : {"_index" : "student", "_id" : "1"} }
{ "doc" : {"age" : 20} }
{ "delete" : { "_index" : "student", "_id" : "1" } }

以 /_bulk 作为目标 URL ，发出 POST 请求：

curl -X POST 127.0.0.1:9200/_bulk?pretty -H 'content-Type:application/json' --data-binary "@students.json"