Juconcurrent 学而不思则罔,思而不学则殆。

Elasticsearch学习笔记(05) - 文档API


前言

在Elasticsearch中,文档API分为单文档API(Single document APIs)和多文档API(Multi-document APIs)。楼主希望通过这篇文档,让读者对单文档API和部分多文档API有一个比较入门和直观的了解。

单文档API包括:

多文档API包括:

Index API

索引API,作用于特定索引,对其文档进行新增或修改。如果指定id文档不存在,那么创建新的文档。否则,先删除现有的文档,再创建新的文档。同时,版本也会增加。

PUT my_index/_doc/1
{
  "user": "mike"
}

索引API还可接受一个参数op_type,当指定其值为create时,将强制执行索引的创建操作,如果索引存在,那么文档创建将失败。

PUT my_index/_doc/1?op_type=create
{
  "user": "mike"
}
// 另一种等价的写法如下,↓↓↓↓↓
PUT my_index/_create/1
{
  "user": "mike"
}

Get API

读取API主要用于文档的读操作,最简单的操作为:GET my_index/_doc/1

执行结果

另外,我们可以只查看_source里面的内容,GET my_index/_source/1。我们还可查看除_source之外的其他内容,GET my_index/_doc/1?_source=false

Delete API

用于在指定索引下删除特定id的文档。DELETE my_index/_doc/1

Update API

更新的时候,文档必须已经存在。同时,更新只对相应字段做增量修改,或者说是合并操作(Merge Operation)。

POST my_index/_update/1
{
  "doc": {
    "user1": "mike1"
    }
}

有的时候,我们想对文档进行全部替换,而非增量操作,可考虑使用Index API来实现。例如:

PUT /my_index/_doc/1
{
  "user": "mike"
}

Update API还支持upsert操作,即:当文档不存在时,插入文档,否则什么都不做。类似于put-if-absent操作。

POST my_index/_update/2
{
  "doc": {
    "name" : "new_name"
  },
  "doc_as_upsert" : true
}

Multi Get API

批量获取API,用于查询一个或多个索引。从Elasticsearch7.x开始,索引下面的类型推荐只有一个,且名称必须为_doc。

GET /_mget
{
  "docs" : [
    {
      "_index" : "test0",
      "_type" : "_doc",
      "_id" : "1"
    },
    {
      "_index" : "test1",
      "_type" : "_doc",
      "_id" : "2"
    }
  ]
}

我们还可以查询同一个索引。

GET /test/_mget
{
  "docs" : [
    {
      "_type" : "_doc",
      "_id" : "1"
    },
    {
      "_type" : "_doc",
      "_id" : "2"
    }
  ]
}

我们还可以进一步简写。

GET /test/_doc/_mget
{
  "docs" : [
    {
      "_id" : "1"
    },
    {
      "_id" : "2"
    }
  ]
}

我们还可以再进一步简写。

GET /test/_doc/_mget
{
  "ids" : ["1", "2"]
}

Bulk API

Bulk,中文译为,也就是批量操作。支持在一次API调用中,对不同或相同索引进行操作。支持Index、Get、Update和Delete的操作。同时,我们需要注意以下几点:

  1. 可以在URI中指定Index,也可以在请求的Payload中指定
  2. 操作中的单条操作失败,不会影响其他操作
  3. 返回结果包含了每一条操作的执行结果

其语法格式如下:

action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n

URI可以是/_bulk,也可以是/{index}/_bulk,当索引名称被指定,批量中的所有操作将作用于同一个索引,同时可以不必在Payload中重复指定。

POST _bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }

在上述例子中,所有操作作用于一个索引。因此,我们可以进一步简写如下:

POST test/_bulk
{ "index" : { "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_id" : "2" } }
{ "create" : { "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1"} }
{ "doc" : {"field2" : "value2"} }

错误说明

在本文的末尾,我们说明一下常见的错误。

错误 原因
无法连接 网络故障或集群挂了
连接无法关闭 网络故障或节点出错
429 集群过于繁忙
4xx 请求体格式出错
500 集群内部错误

总结

我们简单地介绍了单文档的操作、mget和bulk这些操作。同时,也给出了一些常见的错误说明。

参考

  • https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html
  • https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-replication.html

Content