---
title: "获取文档"
date: 2026-03-02
lastmod: 2026-03-02
description: "根据文档ID获取文档内容或源字段"
tags: ["文档操作", "查询操作", "数据读取"]
summary: "根据文档 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 是实时的，即使文档未刷新也能获取到最新版本。"
---


根据文档 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` |

## 示例

### 获取完整文档

```bash
GET /my_index/_doc/1
```

**响应示例：**

```json
{
  "_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"
  }
}
```

### 仅获取源字段

```bash
GET /my_index/_doc/1/_source
```

**响应示例：**

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

### 检查文档是否存在

```bash
HEAD /my_index/_doc/1
```

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

### 获取特定字段

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

### 排除大字段

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

### 只包含特定字段

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

### 使用路由

```bash
GET /my_index/_doc/1?routing=user123
```

### 从本地分片获取

```bash
GET /my_index/_doc/1?preference=_local
```

### 指定版本

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

### 近实时获取

```bash
GET /my_index/_doc/1?realtime=false
```

### 刷新后获取

```bash
GET /my_index/_doc/1?refresh=true
```

### 获取存储字段

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

### 组合过滤参数

```bash
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`） |

### 文档未找到响应

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

## 参数详解

### preference

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

### realtime

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

### _source 参数

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

## 错误处理

### 文档不存在

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

### 索引不存在

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

### 版本不匹配

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

## 使用场景

### 场景 1：获取用户信息

```bash
GET /users/_doc/user123
```

### 场景 2：获取配置

```bash
GET /configs/_doc/app_config/_source
```

### 场景 3：检查文档存在

```bash
HEAD /products/_doc/PROD-001
```

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

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

### 场景 5：排除大字段

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

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

```bash
GET /logs/_doc/log123?routing=shard1
```

## 性能考虑

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

## 最佳实践

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