【README】

0.本文部分内容（数据）总结自 es 开发文档， Document APIs | Elasticsearch Guide [7.2] | Elastic ；

1.本文的es版本是7.2.1；

2.elasticsearch 是一个数据存储，检索和分析引擎；本文介绍的是 es数据存储开发方式；

• es是以文档为单位存储数据的，数据被序列化为json文档进行存储；

3.文档存储包括文档保存，修改，删除；（文档查询的开发方式比较复杂，单独新开一篇阐述）

• 保存文档：使用 put 或 post请求；
• 修改文档：使用put和post请求；
  1. put请求更新文档是全量替换；
  2. post请求路径不带 _update 更新文档是 全量替换；
  3. post请求路径带 _update 更新文档是 部分更新；且 带了 _update 时，会比较新老数据是否相同，若相同则不执行更新，返回noop；
• 删除文档：用delete请求（包括删除文档，删除索引）；

---

【1】保存文档

保存文档可以用put请求或post请求；

• Put 与 post请求保存文档的区别：put必须带文档id，post可以带 或者不带id；

【1.1】put请求保存文档

1） 在customer索引下的 external类型下保存2号文档，文档id设置为2；

Put localhost:9200/customer/external/2{"name":"zhangsan2"
}{"_index": "customer","_type": "external","_id": "2","_version": 1,"result": "created", // 这里表示创建"_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 2,"_primary_term": 1
} 

2）再执行一次，result就是更新 updated 的了；

{"_index": "customer","_type": "external","_id": "2","_version": 2,"result": "updated", // 第2次执行就是更新 "_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 3,"_primary_term": 1
}

---

【1.2】post请求保存文档

1） 在customer索引下的 external类型下保存文档（不带文档id）；

Post localhost:9200/customer/external {"name":"zhangsan_post_1"
}{"_index": "customer","_type": "external","_id": "Qb1Gq4MBJc7j47GNcnTa", // 自动生成id，请求路径不需要设置id "_version": 1,"result": "created",  // 新增数据"_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 4,"_primary_term": 1
}

【Post请求小结】

• 不带id就是永远新增，带了id的规则是无则新增，有则更新；

2）post请求保存文档，带文档id

Post  localhost:9200/customer/external/Qr1Jq4MBJc7j47GNp3RF 
{"name":"zhangsan_post_3"
}{"_index": "customer","_type": "external","_id": "Qr1Jq4MBJc7j47GNp3RF","_version": 5,  // 版本号递增 "result": "updated",  // 更新 "_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 9,"_primary_term": 1
}

---

【2】es文档简单查询

为了方便验证es文档保存，修改，删除的效果，本文介绍了一个简单查询。

【2.1】get请求带文档id查询文档

Get localhost:9200/customer/external/1
{}{"_index": "customer", // 在哪个索引 "_type": "external", // 在哪个类型 "_id": "1",  // 记录id "_version": 2,  // 表明数据被更新过，因为新建数据的版本号是1 "_seq_no": 1,  // 并发控制字段，每次更新就会+1；用来做乐观锁；"_primary_term": 1,  // 同上，主分片重新分配，如重启，就会变化 "found": true,  // "_source": {  // 真正的内容 "name": "zhangsan"}
}

【2.2】seq_no 和 primary_term 做并发控制（乐观锁）

步骤1）查询id等于1的文档

{"_index": "customer","_type": "external","_id": "1","_version": 4,"_seq_no": 11,"_primary_term": 1,"found": true,"_source": {"name": "zhangsan2_update_seq_11"}
}

步骤2）把 seq_no 和 primary_term 作为更新条件

客户端1：（修改成功）

Post localhost:9200/customer/external/1?if_seq_no=11&if_primary_term=1
{"name":"zhangsan_post_update_c1"
}{"_index": "customer","_type": "external","_id": "1","_version": 5,"result": "updated","_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 12,"_primary_term": 1
}

客户端2（修改失败），因为 seq_no 因客户端1修改文档的事件而递增了，即不等于11 ：

Post  localhost:9200/customer/external/1?if_seq_no=11&if_primary_term=1 
{"name":"zhangsan_post_update_c2"
}{"error": {"root_cause": [{"type": "version_conflict_engine_exception","reason": "[1]: version conflict, required seqNo [11], primary term [1]. current document has seqNo [12] and primary term [1]","index_uuid": "IIq46lyCQMisw9_iPDheiw","shard": "0","index": "customer"}],......},"status": 409
}

---

【3】修改文档

1）post 或 put请求都可以修改文档；

• post请求修改文档又分为 请求路径带 _update 和 不带_update；（post不带_update更新文档是全量替换，带_update 是部分更新）
• put请求修改文档 时的请求路径不能带 _update ；（put更新文档是全量替换）

【3.1】post请求路径带_update更新文档

1）更新文档id为1的文档

Post localhost:9200/customer/external/1/_update
{"doc":{ // 注意 post请求路径带update的更新的请求体不同"name":"post_update_202210061135"}
}{"_index": "customer","_type": "external","_id": "1","_version": 6,"result": "updated","_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 13,"_primary_term": 1
}

2）再发送一次相同请求，且报文体也相同，则得到 noop ;

Post localhost:9200/customer/external/1/_update
{"doc":{"name":"post_update_202210061135"}
}{"_index": "customer","_type": "external","_id": "1","_version": 6,"result": "noop", // 没有做任何操作 "_shards": {"total": 0,"successful": 0,"failed": 0}
}

---

【3.2】post请求路径不带_update更新文档

1）更新id等于1的文档

Post localhost:9200/customer/external/1
{"name":"zhangsan_post_update_noupdate"
}{"_index": "customer","_type": "external","_id": "1","_version": 7,"result": "updated","_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 14,"_primary_term": 1
}

2）再发一次相同请求，相同报文体，如下：

{"_index": "customer","_type": "external","_id": "1","_version": 8,"result": "updated","_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 15,"_primary_term": 1
}

【小结】

• Post请求路径带update，会检查新老数据是否相同，若相同，则无需更新；即version， seq_no 都不会增加；
• Post请求路径不带update，则不会检查新老数据是否相同，无论是否相同，都会更新；即 version 和 seq_no 都会增加；

---

【3.3】put请求路径带_update更新文档（API不存在）

put请求更新文档时，其请求路径不能带 _update ；

【3.4】put请求路径不带_update更新文档 （全量替换）

0）初始数据：id为2的文档；

post localhost:9200/customer/external/2
{}
{"_index": "customer","_type": "external","_id": "2","_version": 6,"_seq_no": 8,"_primary_term": 2,"found": true,"_source": {"name": "post_zhangsan_02","addr": "post_addr_02"}
}

1）更新id为2的文档

Put localhost:9200/customer/external/2
{"doc":{"name":"put_update_202210071519"        }
}
// 更新后的结果 
{"_index": "customer","_type": "external","_id": "2","_version": 7,"_seq_no": 9,"_primary_term": 2,"found": true,"_source": {"doc": {"name": "put_update_202210071519"}}
}

【小结】

• put请求路径不带_update可以更新成功； 不会检查新老数据是否相同，都会更新；
• put请求更新文档是全量覆盖（虽然put请求仅更新了name字段，但结果是addr字段被删除了）；

---

【3.5】post请求为索引新增字段

1）为id为1的文档新增 addr 字段；

Post localhost:9200/customer/external/1 
{"doc":{"name":"post_noupdate_202210061151", "addr":"成都高新区01_post_新增属性"}
}{"_index": "customer","_type": "external","_id": "1","_version": 11,"result": "updated","_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 18,"_primary_term": 1
}

---

【3.6】put请求为索引新增字段

1）为id为1的文档新增 addr 字段；

Put localhost:9200/customer/external/1  
{"doc":{"name":"post_noupdate_202210061154", "addr":"成都高新区02_put_新增属性"}
}{"_index": "customer","_type": "external","_id": "1","_version": 12,"result": "updated","_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 19,"_primary_term": 1
}

---

【3.7】post请求更新文档时带_update与不带_update的区别

1）post请求路径带_update，仅部分更新（我想大部分场景应该选择带 _update）

• 如文档有字段1，字段2；
• 通过post带update的更新，可以仅更新字段1 或 字段2； 

2）post请求路径不带update，是全量覆盖

• 如文档有字段1，字段2；
• 通过post不带update的更新，是全量覆盖；

3）例子（post请求带与不带_update 更新文档的区别）：

3.0）初始数据

get localhost:9200/customer/external/2 
{}
{"_index": "customer","_type": "external","_id": "2","_version": 6,"_seq_no": 24,"_primary_term": 1,"found": true,"_source": {"name": "zhangsan2_insert","addr": "post_带update_成都04"}
}

3.1）Post请求路径带update的部分更新 ；

Post localhost:9200/customer/external/2/_update 
{"doc":{"addr":"post_带update_成都05"}
}// 更新后的结果（部分更新）： 
{"_index": "customer","_type": "external","_id": "2","_version": 7,"_seq_no": 25,"_primary_term": 1,"found": true,"_source": {"name": "zhangsan2_insert","addr": "post_带update_成都05"}
}

3.2）post请求路径不带_update 的全量替换 ；

Post localhost:9200/customer/external/2
{    "addr":"post_不带update_成都06"    
}// 更新后的结果（全量替换）：
{"_index": "customer","_type": "external","_id": "2","_version": 8,"_seq_no": 26,"_primary_term": 1,"found": true,"_source": {"addr": "post_不带update_成都06" // （显然，这里是全量替换）}
}

---

【4】删除数据（删除文档和索引）

【4.1】删除文档

1）删除文档id为2的文档

Delete localhost:9200/customer/external/2{"_index": "customer","_type": "external","_id": "2","_version": 9,"result": "deleted", // 删除成功 "_shards": {"total": 2,"successful": 1,"failed": 0},"_seq_no": 27,"_primary_term": 1
}

2）删除完成后，再次查询id为2的文档，如下：

Get localhost:9200/customer/external/2 
{}{"_index": "customer","_type": "external","_id": "2","found": false  // 显然没有找到 
}

---

【4.2】删除索引

注意： es中没有提供删除类型的api  ；

1）删除customer索引；

Delete localhost:9200/customer{"acknowledged": true
}

2）删除索引文档后，，再次查询（报索引不存在）；

Get localhost:9200/customer/external/2
{}
{"error": {"root_cause": [{"type": "index_not_found_exception","reason": "no such index [customer]","resource.type": "index_expression","resource.id": "customer","index_uuid": "_na_","index": "customer"}],...... },"status": 404
}