---
title: "删除文档"
date: 2026-03-30
lastmod: 2026-03-30
description: "从索引中删除指定ID的文档"
tags: ["文档操作", "删除操作", "数据管理"]
summary: "从索引中删除指定 ID 的文档。
API #  DELETE /{index}/_doc/{id} DELETE /{index}/{type}/_doc/{id} API 的作用 #  该 API 用于从索引中删除指定 ID 的文档。
API 变体 #     API 描述     DELETE /{index}/_doc/{id} 删除文档（推荐，无类型）   DELETE /{index}/{type}/_doc/{id} 删除文档（已弃用，有类型）    删除特点 #     特性 描述     即时删除 文档立即被标记为删除   延迟清理 实际数据在段合并时清理   版本控制 支持并发删除控制   不可逆 删除操作无法撤销    API 的参数 #  路由参数 #     参数 类型 是否必填 描述     {index} 字符串 必需 索引名称   {id} 字符串 必需 文档 ID   {type} 字符串 否 文档类型（已弃用）    Query String 参数 #     参数 类型 是否必填 默认值 描述     routing 字符串 否 - 路由值，控制文档分片位置   timeout 时间值 否 1m 操作超时时间   refresh 枚举值 否 false 刷新策略   version 整数 否 - 文档版本号，用于并发控制   version_type 枚举值 否 internal 版本类型   if_seq_no 整数 否 - 序列号条件   if_primary_term 整数 否 - 主版本条件   wait_for_active_shards 字符串 否 1 等待活跃分片数量    刷新策略（refresh） #     值 描述     true 立即刷新受影响的分片   false 不刷新（默认）   wait_for 等待刷新使操作对搜索可见    版本类型（version_type） #     值 描述     internal 使用内部版本号（默认）   external 使用外部版本号   external_gte 使用外部版本号（大于等于）   force 强制执行，忽略版本冲突    示例 #  基本删除 #  DELETE /my_index/_doc/1 响应示例："
---


从索引中删除指定 ID 的文档。

## API

```
DELETE /{index}/_doc/{id}
DELETE /{index}/{type}/_doc/{id}
```

## API 的作用

该 API 用于从索引中删除指定 ID 的文档。

### API 变体

| API | 描述 |
|-----|------|
| `DELETE /{index}/_doc/{id}` | 删除文档（推荐，无类型） |
| `DELETE /{index}/{type}/_doc/{id}` | 删除文档（已弃用，有类型） |

### 删除特点

| 特性 | 描述 |
|------|------|
| **即时删除** | 文档立即被标记为删除 |
| **延迟清理** | 实际数据在段合并时清理 |
| **版本控制** | 支持并发删除控制 |
| **不可逆** | 删除操作无法撤销 |

## API 的参数

### 路由参数

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

### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `routing` | 字符串 | 否 | - | 路由值，控制文档分片位置 |
| `timeout` | 时间值 | 否 | 1m | 操作超时时间 |
| `refresh` | 枚举值 | 否 | false | 刷新策略 |
| `version` | 整数 | 否 | - | 文档版本号，用于并发控制 |
| `version_type` | 枚举值 | 否 | internal | 版本类型 |
| `if_seq_no` | 整数 | 否 | - | 序列号条件 |
| `if_primary_term` | 整数 | 否 | - | 主版本条件 |
| `wait_for_active_shards` | 字符串 | 否 | 1 | 等待活跃分片数量 |

### 刷新策略（refresh）

| 值 | 描述 |
|----|------|
| `true` | 立即刷新受影响的分片 |
| `false` | 不刷新（默认） |
| `wait_for` | 等待刷新使操作对搜索可见 |

### 版本类型（version_type）

| 值 | 描述 |
|----|------|
| `internal` | 使用内部版本号（默认） |
| `external` | 使用外部版本号 |
| `external_gte` | 使用外部版本号（大于等于） |
| `force` | 强制执行，忽略版本冲突 |

## 示例

### 基本删除

```bash
DELETE /my_index/_doc/1
```

**响应示例：**

```json
{
  "_index": "my_index",
  "_type": "_doc",
  "_id": "1",
  "_version": 2,
  "result": "deleted",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 1,
  "_primary_term": 1
}
```

### 使用路由

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

### 立即刷新

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

### 等待刷新完成

```bash
DELETE /my_index/_doc/1?refresh=wait_for
```

### 使用版本控制

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

### 条件删除

```bash
DELETE /my_index/_doc/1?if_seq_no=1&if_primary_term=1
```

### 等待所有分片活跃

```bash
DELETE /my_index/_doc/1?wait_for_active_shards=all
```

### 设置超时

```bash
DELETE /my_index/_doc/1?timeout=5m
```

### 使用已弃用的类型参数

```bash
DELETE /my_index/_doc/1/_doc
```

> **注意**：类型参数已弃用，推荐使用无类型 API。

## 响应字段说明

| 字段 | 描述 |
|------|------|
| `_index` | 文档所在的索引 |
| `_type` | 文档类型（固定为 `_doc`） |
| `_id` | 文档 ID |
| `_version` | 文档版本号（删除后递增） |
| `result` | 操作结果：`deleted` |
| `_shards` | 分片信息 |
| `_seq_no` | 序列号 |
| `_primary_term` | 主版本号 |

## 错误处理

### 文档不存在

```json
{
  "error": {
    "type": "document_missing_exception",
    "reason": "document [1] missing"
  },
  "status": 404
}
```

### 索引不存在

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

### 版本冲突

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

### 条件不满足

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

## 并发控制

### 使用 if_seq_no 和 if_primary_term

```bash
DELETE /my_index/_doc/1?if_seq_no=5&if_primary_term=1
```

只有在文档的序列号为 5 且主版本为 1 时才会执行删除。

### 使用版本号

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

只有当文档版本为 2 时才会执行删除。

## 使用场景

### 场景 1：删除用户数据

```bash
DELETE /users/_doc/user123
```

### 场景 2：条件删除

```bash
# 先获取文档，获取 seq_no 和 primary_term
GET /orders/_doc/1

# 使用获取的信息进行条件删除
DELETE /orders/_doc/1?if_seq_no=10&if_primary_term=2
```

### 场景 3：批量删除

```bash
# 使用 delete_by_query 批量删除
POST /my_index/_delete_by_query
{
  "query": {
    "range": {
      "created_at": {
        "lt": "now-90d"
      }
    }
  }
}
```

### 场景 4：使用路由删除

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

## 删除行为

### 删除过程

```
1. 文档被标记为已删除
2. 文档不再可搜索
3. 文档的存储空间在段合并时释放
```

### 段合并的影响

- **立即效果**：文档无法被搜索到
- **延迟效果**：磁盘空间在段合并时释放
- **性能影响**：大量删除会增加段合并的开销

## 最佳实践

1. **使用批量删除**：删除大量文档使用 `_delete_by_query`
2. **条件删除**：使用 `if_seq_no` 和 `if_primary_term` 进行并发控制
3. **刷新策略**：删除后需要立即搜索时使用 `refresh=true`
4. **归档替代**：对于历史数据，考虑关闭索引而非删除
5. **定期清理**：定期使用 `_forcemerge` 清理已删除文档

## 注意事项

1. **不可逆操作**：删除无法撤销，请谨慎操作
2. **类型已弃用**：有类型的 API 已被弃用
3. **延迟清理**：磁盘空间不会立即释放
4. **版本号**：删除操作会增加文档的版本号
5. **路由要求**：如果索引时使用了路由，删除时也需要指定