Delete by Query #

Delete by Query 删除所有匹配查询条件的文档。适用于批量清理过期数据、删除特定条件的文档等场景。

内部流程：scroll 遍历匹配文档 → 逐批执行 bulk delete → 返回统计结果。

请求格式 #

POST /<index>/_delete_by_query

路径参数 #

参数	必需	说明
`<index>`	是	目标索引，支持逗号分隔多索引和通配符

查询参数 #

参数	类型	默认值	说明
`refresh`	boolean	`false`	操作完成后是否刷新受影响的分片
`timeout`	time	`1m`	超时时间
`wait_for_completion`	boolean	`true`	为 `true` 时同步等待；为 `false` 时立即返回 task ID
`wait_for_active_shards`	string	—	操作前需要的活跃分片数量
`requests_per_second`	float	无限制	每秒请求数限制。`-1` = 不限制
`slices`	int/string	`1`	并行切片数。`"auto"` = 按分片数自动拆分
`scroll`	time	—	scroll 上下文存活时间
`scroll_size`	int	`1000`	每批 scroll 获取的文档数
`conflicts`	string	`abort`	版本冲突处理：`abort` = 中止；`proceed` = 跳过继续
`max_docs`	int	全部	最多删除的文档数量
`search_timeout`	time	—	搜索阶段超时
`q`	string	—	简单查询字符串
`df`	string	—	`q` 参数的默认字段
`default_operator`	string	`OR`	`q` 参数的默认运算符
`analyzer`	string	—	`q` 参数使用的分析器
`analyze_wildcard`	boolean	`false`	是否分析通配符
`lenient`	boolean	—	宽松解析模式
`routing`	string	—	路由值
`preference`	string	—	查询偏好
`terminate_after`	int	`0`	每分片最多处理的文档数
`expand_wildcards`	string	`open`	通配符展开方式
`ignore_unavailable`	boolean	`false`	忽略不存在的索引
`allow_no_indices`	boolean	`true`	允许通配符不匹配任何索引

请求体 #

{
  "query": { ... },
  "max_docs": 1000,
  "conflicts": "proceed"
}

字段	类型	说明
`query`	object	筛选条件，语法同 Query DSL。必需
`max_docs`	int	最多删除的文档数
`conflicts`	string	冲突处理策略

示例 #

基本用法 #

删除所有 status 为 "expired" 的文档：

POST /website/_delete_by_query
{
  "query": {
    "term": { "status": "expired" }
  }
}

删除索引中的所有文档 #

POST /website/_delete_by_query
{
  "query": { "match_all": {} }
}

如果需要清空整个索引，删除并重建索引通常比 delete_by_query 更高效。

使用查询字符串 #

POST /website/_delete_by_query?q=status:expired

跳过版本冲突 #

并发场景下，其他进程可能同时修改了文档。设置 conflicts=proceed 跳过冲突继续删除：

POST /website/_delete_by_query?conflicts=proceed
{
  "query": {
    "range": {
      "date": { "lt": "2023-01-01" }
    }
  }
}

流量控制 #

限制每秒处理 200 条，降低集群负载：

POST /website/_delete_by_query?requests_per_second=200
{
  "query": {
    "term": { "status": "archived" }
  }
}

异步执行 #

POST /website/_delete_by_query?wait_for_completion=false
{
  "query": {
    "range": { "date": { "lt": "2022-01-01" } }
  }
}

响应返回 task ID：

{
  "task": "node_id:task_id"
}

查询进度：

GET /_tasks/node_id:task_id

并行切片 #

POST /website/_delete_by_query?slices=auto
{
  "query": {
    "term": { "status": "expired" }
  }
}

限制删除数量 #

最多删除 1000 条匹配文档：

POST /website/_delete_by_query
{
  "query": { "match_all": {} },
  "max_docs": 1000
}

响应字段 #

{
  "took":                 83,
  "timed_out":            false,
  "total":                100,
  "deleted":              100,
  "batches":              1,
  "version_conflicts":    0,
  "noops":                0,
  "retries": {
    "bulk":   0,
    "search": 0
  },
  "failures": []
}

字段	说明
`took`	操作耗时（毫秒）
`total`	匹配的文档总数
`deleted`	成功删除的文档数
`version_conflicts`	版本冲突次数
`noops`	无操作次数
`batches`	scroll 批次数
`retries.bulk`	bulk 重试次数
`retries.search`	search 重试次数
`failures`	失败详情数组

参考导航 #

需求	参见
单条文档删除	Delete API
按查询条件批量更新	Update by Query
跨索引迁移数据	Reindex
数据生命周期管理	数据生命周期与保留策略