Multi Get API
multiget API根据index,type(可选) 和id(可能还有路由)返回多个文档。响应包含一个docs数组,其中包含所有获取的文档,按照与原始 multi-get请求对应的顺序排列(如果某个特定get出现故障,则在响应中包含一个包含此错误的对象)。成功获取的结构在结构上类似于Get API 提供的文档 。
GET /_mget
{
"docs" : [
{
"_index" : "test",
"_type" : "_doc",
"_id" : "1"
},
{
"_index" : "test",
"_type" : "_doc",
"_id" : "2"
}
]
}
Mget也可以使用单独的索引在Get路径上 (在这种情况下,在body中不需要它):
GET /test/_mget
{
"docs" : [
{
"_type" : "_doc",
"_id" : "1"
},
{
"_type" : "_doc",
"_id" : "2"
}
]
}
使用类型:
GET /test/_doc/_mget
{
"docs" : [
{
"_id" : "1"
},
{
"_id" : "2"
}
]
}
也可以使用id数组来简化请求
GET /test/_doc/_mget
{
"ids" : ["1", "2"]
}
Source filtering
默认情况下,将为每个文档返回_source字段(如果存储的话)。与get API类似,可以使用_source参数只检索_source的一部分(或者根本不检索)。您还可以使用url参数_source、_source_includes和_source_exclude来指定缺省值,当没有针对每个文档的指令时,将使用缺省值。
GET /_mget
{
"docs" : [
{
"_index" : "test",
"_type" : "_doc",
"_id" : "1",
"_source" : false
},
{
"_index" : "test",
"_type" : "_doc",
"_id" : "2",
"_source" : ["field3", "field4"]
},
{
"_index" : "test",
"_type" : "_doc",
"_id" : "3",
"_source" : {
"include": ["user"],
"exclude": ["user.location"]
}
}
]
}
Fileds
可以为每个要获取的文档指定要检索的特定存储字段,类似于get API的stored_fields参数。例如:
GET /_mget
{
"docs" : [
{
"_index" : "test",
"_type" : "_doc",
"_id" : "1",
"stored_fields" : ["field1", "field2"]
},
{
"_index" : "test",
"_type" : "_doc",
"_id" : "2",
"stored_fields" : ["field3", "field4"]
}
]
}
或者,您可以在查询字符串中指定stored_fields参数作为应用于所有文档的默认值。
GET /test/_doc/_mget?stored_fields=field1,field2
{
"docs" : [
{
"_id" : "1" ------1
},
{
"_id" : "2",
"stored_fields" : ["field3", "field4"] --------2
}
]
}
1: Returns field1 and field2
2: Returns field3 and field4
Routing
您还可以指定一个路由值作为参数:
GET /_mget?routing=key1
{
"docs" : [
{
"_index" : "test",
"_type" : "_doc",
"_id" : "1",
"routing" : "key2"
},
{
"_index" : "test",
"_type" : "_doc",
"_id" : "2"
}
]
}
在此示例中,test/_doc/2将从与路由键对应的分片中提取key1文档,但是test/_doc/1将从与路由键对应的分片中提取文档key2。
安全
参阅基于url的访问控制,这里暂时不描述
部分回复
为确保快速响应,如果一个或多个分片失败,多重获取API将响应部分结果。
Bulk API
批量API使得在一个API调用中执行许多索引/删除操作成为可能。这可以大大提高索引速度。
REST API的端点是/_bulk,它期望使用以下换行分隔的JSON (NDJSON)结构:
action_and_meta_data \ n
optional_source \ n
action_and_meta_data \ n
optional_source \ n
....
action_and_meta_data \ n
optional_source \ n
注意:数据的最终行必须以换行符结束\n。每个换行符前面可以有一个回车\r。向该端点发送请求时,应该将Content-Type头设置为application/x-ndjson。
可能的操作包括索引、创建、删除和更新。Index和creat需要在下一行有一个source源数据,并且要和标准的Index API的op_type参数具有相同的语义(例如,如果已经存在具有相同索引的文档,create将失败,而index将根据需要添加或替换文档)。delete则不需要在下一行有源数据。Update则需指定部分doc、upsert和脚本及其其他选项。
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_type":"_doc","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
因为这种格式使用literal \n作为分隔符,所以请确保JSON操作和源文件有没有被很好地打印出来。下面是一个正确的批量命令序列的例子:
POST _bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }{ "doc" : {"field2" : "value2"} }
Response:
{
"took": 30,"took": 30,
"errors": false,"errors": false,
"items": ["items": [
{{
"index": {"index": {
"_index": "test","_index": "test",
"_type": "_doc","_type": "_doc",
"_id": "1","_id": "1",
"_version": 1,"_version": 1,
"result": "created","result": "created",
"_shards": {"_shards": {
"total": 2,"total": 2,
"successful": 1,"successful": 1,
"failed": 0"failed": 0
},},
"status": 201,"status": 201,
"_seq_no" : 0,"_seq_no" : 0,
"_primary_term": 1"_primary_term": 1
}}
},},
{{
"delete": {"delete": {
"_index": "test","_index": "test",
"_type": "_doc","_type": "_doc",
"_id": "2","_id": "2",
"_version": 1,"_version": 1,
"result": "not_found","result": "not_found",
"_shards": {"_shards": {
"total": 2,"total": 2,
"successful": 1,"successful": 1,
"failed": 0"failed": 0
},},
"status": 404,"status": 404,
"_seq_no" : 1,"_seq_no" : 1,
"_primary_term" : 2"_primary_term" : 2
}}
},},
{{
"create": {"create": {
"_index": "test","_index": "test",
"_type": "_doc","_type": "_doc",
"_id": "3","_id": "3",
"_version": 1,"_version": 1,
"result": "created","result": "created",
"_shards": {"_shards": {
"total": 2,"total": 2,
"successful": 1,"successful": 1,
"failed": 0"failed": 0
},},
"status": 201,"status": 201,
"_seq_no" : 2,"_seq_no" : 2,
"_primary_term" : 3"_primary_term" : 3
}}
},},
{{
"update": {"update": {
"_index": "test","_index": "test",
"_type": "_doc","_type": "_doc",
"_id": "1","_id": "1",
"_version": 2,"_version": 2,
"result": "updated","result": "updated",
"_shards": {"_shards": {
"total": 2,"total": 2,
"successful": 1,"successful": 1,
"failed": 0"failed": 0
},},
"status": 200,"status": 200,
"_seq_no" : 3,"_seq_no" : 3,
"_primary_term" : 4"_primary_term" : 4
}}
}}
]]
}}
端点为/bulk或/{index}/_bulk。在提供索引时,默认情况下,它将用于未显式提供索引的bulk 元素。
格式说明, 这里的想法是使这个过程尽可能快。由于一些操作将被重定向到其他节点上的其他切分,因此只有action_meta_data在接收节点端被解析。
支持此协议的客户端应该多使用该API,并尽可能减少缓冲。
针对 bulk action 的响应是一个大的 Json 结构,包含着每个 action 执行后的结果。单一的 action 故障不会影响其余的操作。
在一个单独的 bulk call 中没有正确的执行数目。你应该使用不同的设置实验来确定适合您的特定工作负载的最佳大小。
如果使用 HTTP API,请确保客户端不发送 HTTP 块,因为这会使得运行速度降低。
乐观并发控制
在批量API调用中,每个索引和删除操作都可能在各自的操作和元数据行中包含if_seq_no和if_primary_term参数。if_seq_no和if_primary_term参数根据对现有文档的最后修改控制操作的执行方式。有关详细信息,请参阅乐观并发控制。
版本控制
每个批量项目都可以使用version字段包含version值。它自动遵循基于_version映射的索引/删除操作的行为。它还支持version_type(参见版本控制)。
Routing
每个批量项都可以使用routing字段包含路由值。它自动遵循基于_routing映射的索引/删除操作的行为。
Wait For Active Shards
在进行批量调用时,可以将wait_for_active_shards参数设置为在开始处理批量请求之前,需要激活最少数量的副本分片。
Refresh
控制何时可以搜索到此请求所做的更改。
注意:只有接收到批量请求的分片才会受到refresh的影响。想象一个_bulk?refresh=wait_for请求,其中包含三个文档,恰好路由到一个包含五个切分的索引中的不同切分。请求将只等待这三个碎片刷新。构成索引的另外两个切分根本不参与_bulk请求。
Update
当使用update操作时,retry_on_conflict可以在action中用作字段(不在额外的行中),以指定在版本冲突的情况下,更新应该重试多少次。
更新操作有效支持于以下选项:doc(部分文档)、upsert、doc_as_upsert、脚本、params(用于脚本)、lang(用于脚本)和_source。
POST _bulk
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}
Security
参见 URL-based access control.
Partial responses局部响应
为了确保快速响应,如果一个或多个碎片失败,则bulk API将响应部分结果