获取文档 | Easysearch | 分布式搜索型数据库

根据文档 ID 获取文档内容、源字段或检查文档是否存在。

API #

GET /{index}/_doc/{id}
HEAD /{index}/_doc/{id}
GET /{index}/_doc/{id}/_source
HEAD /{index}/_doc/{id}/_source
GET /{index}/{type}/_doc/{id}

API 的作用 #

该 API 用于根据文档 ID 获取文档信息。

API 变体 #

API	作用	返回内容
`GET /{index}/_doc/{id}`	获取文档	元数据 + 源字段
`HEAD /{index}/_doc/{id}`	检查文档是否存在	仅状态码
`GET /{index}/_doc/{id}/_source`	获取源字段	仅源字段
`GET /{index}/{type}/_doc/{id}`	获取文档（已弃用）	元数据 + 源字段

实时性 #

默认情况下，API 是实时的，即使文档未刷新也能获取到最新版本。

API 的参数 #

路由参数 #

参数	类型	是否必填	描述
`{index}`	字符串	必需	索引名称
`{id}`	字符串	必需	文档 ID
`{type}`	字符串	否	文档类型（已弃用）

Query String 参数 #

参数	类型	是否必填	默认值	描述
`preference`	字符串	否	-	指定从哪个分片获取结果：`_local`（本地）、自定义值
`realtime`	布尔值	否	true	是否实时获取：`true`（实时）、`false`（近实时）
`refresh`	布尔值	否	false	是否刷新分片以获取最新版本
`routing`	字符串	否	-	路由参数，确保请求到达正确的分片
`stored_fields`	列表	否	-	返回存储的字段（逗号分隔）
`_source`	布尔值/字符串	否	true	是否包含 `_source` 字段或指定返回的字段
`_source_excludes`	字符串	否	-	排除的源字段（逗号分隔）
`_source_includes`	字符串	否	-	包含的源字段（逗号分隔）
`version`	整数	否	-	指定要获取的文档版本号
`version_type`	枚举值	否	-	版本类型：`external`、`external_gte`

示例 #

获取完整文档 #

GET /my_index/_doc/1

响应示例：

{
  "_index": "my_index",
  "_type": "_doc",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "user": "kimchy",
    "post_date": "2026-02-04T08:00:00",
    "message": "Trying out Easysearch"
  }
}

仅获取源字段 #

GET /my_index/_doc/1/_source

响应示例：

{
  "user": "kimchy",
  "post_date": "2026-02-04T08:00:00",
  "message": "Trying out Easysearch"
}

检查文档是否存在 #

HEAD /my_index/_doc/1

如果文档存在，返回 200 OK；否则返回 404 Not Found。

获取特定字段 #

GET /my_index/_doc/1?_source=user,message

排除大字段 #

GET /my_index/_doc/1?_source_excludes=large_field,comments

只包含特定字段 #

GET /my_index/_doc/1?_source_includes=name,email

使用路由 #

GET /my_index/_doc/1?routing=user123

从本地分片获取 #

GET /my_index/_doc/1?preference=_local

指定版本 #

GET /my_index/_doc/1?version=2&version_type=external

近实时获取 #

GET /my_index/_doc/1?realtime=false

刷新后获取 #

GET /my_index/_doc/1?refresh=true

获取存储字段 #

GET /my_index/_doc/1?stored_fields=field1,field2

组合过滤参数 #

GET /my_index/_doc/1?_source_includes=name,title&_source_excludes=metadata

响应字段说明 #

完整文档响应 #

字段	描述
`_index`	文档所在的索引
`_type`	文档类型（固定为 `_doc`）
`_id`	文档 ID
`_version`	文档版本号
`_seq_no`	序列号
`_primary_term`	主版本号
`found`	是否找到文档：`true` 或 `false`
`_source`	文档的源数据
`fields`	存储的字段（如果使用 `stored_fields`）

文档未找到响应 #

{
  "_index": "my_index",
  "_type": "_doc",
  "_id": "1",
  "found": false
}

参数详解 #

preference #

值	描述
`_local`	从本地分片获取
`_primary`	从主分片获取
自定义值	从指定分片获取

realtime #

值	描述
`true`	实时获取（默认），可能需要从事务日志读取
`false`	近实时获取，只从已刷新的段读取

_source 参数 #

格式	描述
`true`	返回所有源字段（默认）
`false`	不返回源字段
`field1,field2`	只返回指定字段

错误处理 #

文档不存在 #

{
  "_index": "my_index",
  "_type": "_doc",
  "_id": "999",
  "found": false
}

索引不存在 #

{
  "error": {
    "type": "index_not_found_exception",
    "reason": "no such index [my_index]"
  },
  "status": 404
}

版本不匹配 #

{
  "error": {
    "type": "version_conflict_engine_exception",
    "reason": "version conflict"
  },
  "status": 409
}

使用场景 #

场景 1：获取用户信息 #

GET /users/_doc/user123

场景 2：获取配置 #

GET /configs/_doc/app_config/_source

场景 3：检查文档存在 #

HEAD /products/_doc/PROD-001

场景 4：只获取需要的字段 #

GET /users/_doc/123?_source=name,email

场景 5：排除大字段 #

GET /articles/_doc/1?_source_excludes=content,attachments

场景 6：使用路由确保正确分片 #

GET /logs/_doc/log123?routing=shard1

性能考虑 #

参数	性能影响
`realtime=true`	可能需要从事务日志读取，较慢
`realtime=false`	只从已刷新的段读取，较快
`preference=_local`	避免网络开销，最快
`_source=false`	减少数据传输，更快
排除大字段	减少数据传输，更快

最佳实践 #

字段过滤：使用 _source_includes 只获取需要的字段
排除大字段：使用 _source_excludes 排除不需要的大字段
本地读取：使用 preference=_local 提高性能
HEAD 请求：只需检查存在时使用 HEAD 方法
批量获取：需要获取多个文档时使用 _mget API

标签

文档操作查询操作数据读取