ES基础篇 常用API之文档API
文章目录
- 前言
-
- 文档操作
-
- 单个文档操作
-
- 添加文档
- 获取文档
- 更新文档
-
- 全部覆盖
- 部分修改
- 删除文档
- 批量文档操作
-
- 批量操作
- 批量获取
前言
前面写了一篇常用API之索引类、映射类、别名类API，主要是介绍Elasticsearch的集群类、索引类、映射类、别名类等，这些在开发中或许不会经常用到，但API的存在定有它存在的价值，作为程序猿的我们，或使用Java，或使用Python等等，虽然使用编程语言调用接口，但有时候，需要便捷的操作、查看相关信息的时候，明显在Kinbana上操作API会更加便捷，这或许就是它所存在的意义，所以这次在追加一篇文档API，供大家开发的时候参考
文档操作
单个文档操作
| method | URL | remark |
|---|---|---|
| PUT | localhost:9200/索引名称/类型名称/文档id | 创建文档-指定文档id |
| POST | localhost:9200/索引名称/类型名称 | 创建文档-随机文档id |
| POST | localhost:9200/索引名称/类型名称/文档id/_update | 修改文档(部分修改) |
| DELETE | localhost:9200/索引名称/类型名称/文档id | 删除文档 |
| GET | localhost:9200/索引名称/类型名称/文档id | 查询某条文档 |
| POST | localhost:9200/索引名称/类型名称/_search | 搜索文档 |
添加文档
-
指定文档ID
#PUT localhost:9200/索引名称/类型名称/文档id # 添加文档时，防止覆盖已存在的文档，可通过_create加以限制，如：PUT blog/_doc/1/_create PUT {index}/_doc/{id} { "filed":"value", …… }样例：
在创建的索引中添加文档（指定id）
- 输入
PUT /nav_web_video/_doc/1 { "name":"爱奇艺", "url":"https://www.iqiyi.com/", "ipAddr":"110.242.72.5", "desc":"爱奇艺(iQIYI.COM)是拥有海量、优质、高清的网络视频的大型视频网站,专业的网络视频播放平台。爱奇艺影视内容丰富多元,涵盖电影、电视剧、动漫、综艺、生活、音乐、搞笑、财经、军事、体育、片花..." }- 输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 1, "result" : "created", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 0, "_primary_term" : 3 }响应说明：
- _index：文档所在的索引名
- _type：文档所在的类型名
- _id：文档ID
- _version：文档版本
- result：created已经创建
- _shards：索引操作的复制过程的信息
- total：指示应在其上执行索引操作的分片副本（主分片和副本分片）的数量
- successful：表示索引操作成功的分片副本数。
- failed：在副本分片上索引操作失败的情况下包含复制相关错误。
-
**不指定文档ID **
添加文档时可以不指定文档id，则文档id是自动生成的字符串。注意，需要使用POST方法，而不是PUT方法。
# POST localhost:9200/索引名称/类型名称 POST {index}/_doc { "filed":"value", …… }样例：
在创建的索引中添加文档(不指定id)
- 输入
POST /nav_web_video/_doc/ { "name":"爱奇艺", "url":"https://www.iqiyi.com/", "ipAddr":"110.242.72.5", "desc":"爱奇艺(iQIYI.COM)是拥有海量、优质、高清的网络视频的大型视频网站,专业的网络视频播放平台。爱奇艺影视内容丰富多元,涵盖电影、电视剧、动漫、综艺、生活、音乐、搞笑、财经、军事、体育、片花..." }- 输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "2T3ydogBRXiZstgWuI_C", "_version" : 1, "result" : "created", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 1, "_primary_term" : 3 }
获取文档
-
通过id获取指定文档
# GET localhost:9200/索引名称/类型名称/文档id GET /{index}/_doc/{id}
样例：
在创建的索引中获取文档
-
输入
GET /nav_web_video/_doc/1 -
输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 1, "_seq_no" : 0, "_primary_term" : 3, "found" : true, "_source" : { "name" : "爱奇艺", "url" : "https://www.iqiyi.com/", "ipAddr" : "110.242.72.5", "desc" : "爱奇艺(iQIYI.COM)是拥有海量、优质、高清的网络视频的大型视频网站,专业的网络视频播放平台。爱奇艺影视内容丰富多元,涵盖电影、电视剧、动漫、综艺、生活、音乐、搞笑、财经、军事、体育、片花..." } }
响应结果说明：
-
found值为true，说明查询到该文档
found值为false，说明文档不存在
-
_source字段是文档的内容
-
判定文档是否存在
# 使用HEAD判断文档是否存在 HEAD {index}/_doc/{id}样例：
在创建的索引上判断id为1的文档是否存在
- 输入
HEAD /nav_web_video/_doc/1- 输出
200 - OK
更新文档
全部覆盖
PUT方式（同添加文档）进行更改，覆盖文档所有数据，没有的值的字段将会被清空覆盖
#PUT修改数据
PUT {index}/_doc/{id}
{
"filed":"value",
……
}
样例：
在创建的索引中修改文档(PUT方式全部覆盖)
-
输入
# 1 PUT /nav_web_video/_doc/1 { "name":"爱奇艺" } # 2 GET /nav_web_video/_doc/1 -
输出
# 2 { "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 2, "_seq_no" : 2, "_primary_term" : 3, "found" : true, "_source" : { "name" : "爱奇艺" } }
部分修改
部分修改，只修改文档部分字段，其他字段不变
2.1 添加字段
POST {index}/_doc/{id}/_update
{
"script": {
"source": "ctx._source.{field}=\"{value}\""
}
}
样例：
在创建的索引中，id为1的文档新增字段
-
输入
# 1 POST nav_web_video/_doc/1/_update { "script": { "source": "ctx._source.ceo=\"陈百强\"" } } # 2 GET /nav_web_video/_doc/1 -
输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 3, "_seq_no" : 3, "_primary_term" : 3, "found" : true, "_source" : { "name" : "爱奇艺", "ceo" : "陈百强" } }
2.2 删除字段
POST {index}/_doc/{id}/_update
{
"script": {
"source": "ctx._source.remove(\"{field}\")"
}
}
样例：
在创建的索引中移除指定id的文档字段
-
输入
# 1 POST nav_web_video/_doc/1/_update { "script": { "source": "ctx._source.remove(\"ceo\")" } } # 2 GET /nav_web_video/_doc/1 -
输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 6, "_seq_no" : 6, "_primary_term" : 3, "found" : true, "_source" : { "name" : "爱奇艺" } }
2.3 更新字段
通过脚本更新制定字段，其中ctx是脚本语言中的一个执行对象，先获取_source，再修改content字段
POST {index}/_doc/{id}/_update
{
"script": {
"source": "ctx._source.{field}=\"{value}\""
}
}
样例：
在创建的索引中，修改id为1的文档的属性
-
输入
# 1 POST nav_web_video/_doc/1/_update { "script": { "source": "ctx._source.name=\"aiqiyi\"" } } # 2 GET /nav_web_video/_doc/1 -
输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 7, "_seq_no" : 7, "_primary_term" : 3, "found" : true, "_source" : { "name" : "aiqiyi" } }
删除文档
- 根据id删除文档
# DELETE localhost:9200/索引名称/类型名称/文档id
DELETE {index}/_doc/{id}
样例：
在创建的索引中，删除id为1的文档
-
输入
DELETE nav_web_video/_doc/1 -
输出
{ "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 8, "result" : "deleted", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 8, "_primary_term" : 3 }
-
查询删除
# 查询删除 POST /{index}/_delete_by_query { "query":{ # "match_all":{} 表示删除所有 "match":{ "{field}": "{value}" } } }样例：
在创建的索引中删除匹配查询到的文档
-
输入
POST /nav_web_video/_delete_by_query { "query": { "match": { "name": "爱奇艺" } } } -
输出
{ "took" : 709, "timed_out" : false, "total" : 1, "deleted" : 1, "batches" : 1, "version_conflicts" : 0, "noops" : 0, "retries" : { "bulk" : 0, "search" : 0 }, "throttled_millis" : 0, "requests_per_second" : -1.0, "throttled_until_millis" : 0, "failures" : [ ] }
-
批量文档操作
ElasticSearch提供了文档的批量操作机制.
ElasticSearch提供了Bulk API，可以执行批量索引、批量删除、批量更新等操作，也就是说Bulk API允许使用在单个步骤中进行多次 create 、 index 、 update 或 delete 请求。
create 和index的区别：
如果数据存在，使用create操作失败，会提示文档已经存在，使用index则可以成功执行。
bulk一次最大处理多少数据量？
bulk会把将要处理的数据载入内存中，所以数据量是有限制的，最佳的数据量不是一个确定的数值，它取决于你的硬件，你的文档大小以及复杂性，你的索引以及搜索的负载。
一般建议是1000-5000个文档，如果你的文档很大，可以适当减少队列，大小建议是5-15MB，默认不能超过100M，可以在es的配置文件（即$ES_HOME下的config下的elasticsearch.yml）中。
bulk 与其他的请求体格式稍有不同，bulk请求格式如下：
{ action: { metadata }}\n
{ request body }\n
{ action: { metadata }}\n
{ request body }\n
...
分成action、metadata和doc三部份
action : 必须是以下4种选项之一
index(最常用) : 如果文档不存在就创建他，如果文档存在就更新他
create : 如果文档不存在就创建他，但如果文档存在就返回错误使用时一定要在metadata设置_id值，他才能去判断这个文档是否存在
update : 更新一个文档，如果文档不存在就返回错误使用时也要给_id值，且后面文档的格式和其他人不一样，若修改单个字段不会覆盖别的字段
delete : 删除一个文档，如果要删除的文档id不存在，就返回错误使用时也必须在metadata中设置文档_id，且后面不能带一个doc，因为没意义，他是用_id去删除文档的.
metadata : 设置这个文档的metadata，像是_id、_index、_type…
doc : 就是一般的文档格式
这种格式类似一个有效的单行 JSON 文档 流 ，它通过换行符(\n)连接到一起。注意两个要点：
- 每行一定要以换行符(\n)结尾， 包括最后一行 。这些换行符被用作一个标记，可以有效分隔行。
- 这些行不能包含未转义的换行符，因为他们将会对解析造成干扰。这意味着这个 JSON 不 能使用 pretty 参数打印。
- action/metadata 行指定 哪一个文档 做 什么操作 。metadata 应该 指定被索引、创建、更新或者删除的文档的 _index 、 _type 和 _id 。
- request body 行由文档的 _source 本身组成–文档包含的字段和值。它是 index 和 create 操作所必需的。
批量操作
批量操作，包括新增、更新和删除
POST _bulk：未指定索引的批量操作， 可以操作不同索引文档，action/metadata中指定索引
POST /{index}/_bulk：指定索引的批量操作 ，只能操作被指定的索引文档
POST _bulk
{"create":{"_index":"{index}", "_id":"{id}"}}
{${json_value}}
{"update":{"_index":"{index}", "_id":"{id}"}}
{ "doc" : {${json_value}} }
{"delete":{"_index":"{index}", "_id":"{id}"}}
样例：
批量操作创建的索引下的数据，包含不同索引的增删改
-
输入
POST _bulk {"create":{"_index":"nav_web_video","_id":"1"}} {"name":"爱奇艺","url":"https://www.iqiyi.com/","ipAddr":"110.242.72.5","desc":"爱奇艺(iQIYI.COM)是拥有海量、优质、高清的网络视频的大型视频网站,专业的网络视频播放平台。爱奇艺影视内容丰富多元,涵盖电影、电视剧、动漫、综艺、生活、音乐、搞笑、财经、军事、体育、片花..."} {"update":{"_index":"nav_web_video","_id":"1"}} {"doc":{"name":"爱奇艺update"}} {"delete":{"_index":"nav_web_video", "_id":"1"}} {"index":{"_index":"nav_web_game","_id":"1"}} {"name":"腾讯游戏","url":"https://game.qq.com/","ipAddr":"157.255.245.60","desc":"腾讯游戏成立于2003年,是全球领先的游戏研发和运营商。作为“超级数字场景”理念的倡导者和实践者,腾讯游戏致力于为用户创造高品质数字生活体验,为产业和社会发展创造更多建设性的..."} -
输出
{ "took" : 16, "errors" : false, "items" : [ { "create" : { "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 1, "result" : "created", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 20, "_primary_term" : 3, "status" : 201 } }, { "update" : { "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 2, "result" : "updated", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 21, "_primary_term" : 3, "status" : 200 } }, { "delete" : { "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 3, "result" : "deleted", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 22, "_primary_term" : 3, "status" : 200 } }, { "index" : { "_index" : "nav_web_game", "_type" : "_doc", "_id" : "1", "_version" : 4, "result" : "updated", "_shards" : { "total" : 1, "successful" : 1, "failed" : 0 }, "_seq_no" : 3, "_primary_term" : 1, "status" : 200 } } ] }
批量获取
GET {index}/_mget
{
"ids" : [${id}, ${id},${id}]
}
样例：
根据id批量获取创建的索引的文档
-
输入
GET /nav_web_video/_mget { "ids":["1", "2"] } -
输出
"docs" : [ { "_index" : "nav_web_video", "_type" : "_doc", "_id" : "1", "_version" : 1, "_seq_no" : 23, "_primary_term" : 3, "found" : true, "_source" : { "name" : "爱奇艺", "url" : "https://www.iqiyi.com/", "ipAddr" : "110.242.72.5", "desc" : "爱奇艺(iQIYI.COM)是拥有海量、优质、高清的网络视频的大型视频网站,专业的网络视频播放平台。爱奇艺影视内容丰富多元,涵盖电影、电视剧、动漫、综艺、生活、音乐、搞笑、财经、军事、体育、片花..." } }, { "_index" : "nav_web_video", "_type" : "_doc", "_id" : "2", "found" : false } ] }