获取 API
从索引中读取指定的 JSON 文档。
GET my-index-000001/_doc/0
请求
GET <index>/_doc/<_id>
HEAD <index>/_doc/<_id>
GET <index>/_source/<_id>
HEAD <index>/_source/<_id>
前置条件
- 开启 Elasticsearch 安全功能后,您必须拥有目标索引或索引别名的
read
索引权限。
描述
使用 GET 可从特定索引中检索文档及其源字段或存储字段。使用 HEAD 可验证文档是否存在。您可以使用 _source
资源检索文档源或验证其是否存在。
实时
编辑
默认情况下,get API 是实时的,不受索引刷新率的影响(数据何时可见以供搜索)。如果请求的是存储字段(参见 stored_fields
参数),且文档已更新但尚未刷新,则 get API 必须解析和分析源以提取存储字段。要禁用实时 GET,可将 realtime
参数设置为 false
。
源过滤
默认情况下,除非使用了 stored_fields
参数或禁用了 _source
字段,否则 get 操作将返回 _source
字段的内容。您可以使用 _source
参数关闭 _source
检索:
GET my-index-000001/_doc/0?_source=false
如果只需要 _source
中的一个或两个字段,可以使用 _source_includes
或 _source_excludes
参数来包含或过滤掉特定字段。这对大型文档尤其有用,因为部分检索可以节省网络开销。这两个参数都使用逗号分隔的字段列表或通配符表达式。例如:
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
如果只想指定包含内容,可以使用更短的符号:
GET my-index-000001/_doc/0?_source=*.id
路由(Routing)
如果在索引编制过程中使用了路由,则在检索文档时也需要指定路由值。例如:
GET my-index-000001/_doc/2?routing=user1
该请求获取 id 为 2
的文档,但其路由基于用户。如果未指定正确的路由,则不会获取文档。
偏好(Preference)
控制在哪个分片副本上执行获取请求的偏好。默认情况下,操作会在分片副本之间随机进行。
preference
可设置为:
_local
如果可能,操作将优先在本地分配的分块上执行。
自定义(字符串)值
自定义值将用于保证相同的分区将用于相同的自定义值。这有助于解决在不同刷新状态下访问不同分区时出现的“跳值”问题。示例值可以是网络会话 ID 或用户名。
刷新(Refreshe)
可以将 refresh
参数设置为 true
,以便在获取操作之前刷新相关分片,使其可以被搜索。将该参数设置为 true
之前,应仔细考虑并验证这样做不会给系统带来沉重负担(降低索引速度)。
分布式
获取操作会被散列到一个特定的分片 ID 中。然后,它会被重定向到该分区 id 中的一个副本,并返回结果。副本是指主分区及其在该分区 ID 组内的副本。这意味着,我们拥有的副本越多,GET 扩展性就越好。
版本支持
只有当文档的当前版本等于指定版本时,才能使用 version
参数检索文档。
在内部,Elasticsearch 已将旧文档标记为已删除,并添加了一个全新的文档。旧版本的文档不会立即消失,不过你将无法访问它。当你继续索引更多数据时,Elasticsearch 会在后台清理已删除的文档。
路径参数
<index>
(必填,字符串)包含文档的索引的名称。<_id>
(必填,字符串)文档的唯一标识符。
查询参数
preference
(可选,字符串) 指定应在哪个节点或分片上执行操作。默认为随机。realtime
(可选,布尔) 如果为true
,则表示请求是实时的,而不是近实时的。默认为true
。参阅实时。refresh
(可选,布尔) 如果为true
,请求会在检索文档前刷新相关分区。默认为false
。routing
(可选,字符串) 用于将操作路由到特定分区的自定义值。stored_fields
(可选,布尔) 如果为true
,则检索存储在索引中的文档字段,而不是文档_source
。默认为false
。_source
(可选,字符串)返回_source
字段与否的真或假,或者要返回的字段列表。_source_excludes
(可选,字符串)以逗号分隔的源字段列表,用于从响应中排除。也可以使用该参数从
_source_includes
查询参数指定的子集中排除字段。如果
_source
参数为false
,该参数将被忽略。_source_includes
(可选,字符串)以逗号分隔的源字段列表,包含在响应中。如果指定了该参数,则只返回这些源字段。你可以使用
_source_excludes
查询参数从该子集中排除字段。如果
_source
参数为false
,该参数将被忽略。version
(可选,整数)用于并发控制的明确版本号。指定的版本必须与文档的当前版本一致,请求才能成功。version_type
(可选,枚举) 特定版本类型:external
、external_gte
。
响应体
_index
文档所属索引的名称。_id
文档的唯一标识符。_version
文档版本。文档每次更新时都会递增。_seq_no
为索引操作分配给文档的序列号。序列号用于确保文档的旧版本不会覆盖新版本。参阅乐观并发控制。_primary_term
为索引操作分配给文档的主要术语。参阅乐观并发控制。found
表示文档是否存在:true
或false
。_routing
显式路由(如果已设置)。_source
如果found
为true
,则包含 JSON 格式的文档数据。如果_source
参数设置为false
或stored_fields
参数设置为true
,则排除在外。_fields
如果stored_fields
参数设置为true
且found
为true
,则包含存储在索引中的文档字段。
示例
从 my-index-000001
索引中读取 _id
为 0 的 JSON 文档:
GET my-index-000001/_doc/0
API 返回以下结果:
{
"_index": "my-index-000001",
"_id": "0",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"found": true,
"_source": {
"@timestamp": "2099-11-15T14:12:12",
"http": {
"request": {
"method": "get"
},
"response": {
"status_code": 200,
"bytes": 1070000
},
"version": "1.1"
},
"source": {
"ip": "127.0.0.1"
},
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
}
检查是否存在 _id
为 0 的文档:
HEAD my-index-000001/_doc/0
如果文档存在,Elasticsearch 返回状态代码 200 - OK
;如果不存在,则返回 404 - Not Found
。
仅获取源字段
使用 <index>/_source/<id>
资源只获取文档的 _source
字段。例如:
GET my-index-000001/_source/1
您可以使用源过滤参数来控制 _source
的哪些部分会被返回:
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
您可以使用 HEAD 和 _source
端点来有效地测试文档 _source
是否存在。如果在映射中禁用了文档源,则文档源不可用。
HEAD my-index-000001/_source/1
获取存储字段
使用 stored_fields
参数指定要检索的存储字段集。任何未存储的请求字段都将被忽略。例如,请考虑以下映射:
PUT my-index-000001
{
"mappings": {
"properties": {
"counter": {
"type": "integer",
"store": false
},
"tags": {
"type": "keyword",
"store": true
}
}
}
}
现在我们可以添加一个文件:
PUT my-index-000001/_doc/1
{
"counter": 1,
"tags": [ "production" ]
}
然后再试着找回它:
GET my-index-000001/_doc/1?stored_fields=tags,counter
API 返回以下结果:
{
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"_seq_no" : 22,
"_primary_term" : 1,
"found": true,
"fields": {
"tags": [
"production"
]
}
}
从文档本身获取的字段值总是以数组形式返回。由于 counter
字段没有存储,因此获取请求会忽略它。
您还可以检索 _routing
字段等元数据字段:
PUT my-index-000001/_doc/2?routing=user1
{
"counter" : 1,
"tags" : ["env2"]
}
GET my-index-000001/_doc/2?routing=user1&stored_fields=tags,counter
API 返回以下结果:
{
"_index": "my-index-000001",
"_id": "2",
"_version": 1,
"_seq_no" : 13,
"_primary_term" : 1,
"_routing": "user1",
"found": true,
"fields": {
"tags": [
"env2"
]
}
}
使用 stored_field
选项只能检索叶字段。如果指定了对象字段,则请求失败。