# 管理单元

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

:用于批量处理多个文档,提高效率。

用法:

  1. 准备一组 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" } }
      
  2. /_bulk 作为目标 URL ,发出 POST 请求:

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