NoSQL 与搜索 / 系统课时

批量写入 Bulk API

批量写入 Bulk API

本课把多次单文档请求合并为一个 Bulk API 调用,重点解决 NDJSON 行式格式、四类操作的配对规则、局部失败检查和批次大小控制。完成后,你可以构造可执行的批量请求,并只重试真正失败的条目。

学习目标

  • 正确编写 Bulk API 的 NDJSON 请求体
  • 根据 errors、items 和单项状态码定位失败操作
  • 依据请求体积、耗时和拒绝率调整批次大小与并发度

Bulk 请求为什么采用行式格式

Bulk API 支持 create、index、update 和 delete。请求体不是普通 JSON 数组,而是 NDJSON:每一行都是独立 JSON,操作元数据行后是否需要数据行由操作类型决定。

操作 下一行内容 关键行为
create 完整文档 ID 已存在时失败
index 完整文档 不存在则创建,存在则覆盖
update doc、script 或 upsert 配置 局部或脚本更新
delete 无 只写操作元数据行

文件最后必须保留换行,JSON 也不能格式化成多行。使用 cURL 从文件提交时要用 --data-binary,否则换行可能被改变。

Bulk API 请求与逐项结果检查流程

构造并执行一个完整批次

下面示例先准备两条已有文档,再批量执行重复创建、写入、局部更新和删除。第一项会故意触发冲突,用于观察 Bulk API 的局部失败行为。示例会删除测试索引,只应在本地练习环境运行。

bash
curl -s -X DELETE "http://localhost:9200/products" > /dev/null

curl -s -X PUT "http://localhost:9200/products/_doc/sku-100?refresh=wait_for" \
  -H "Content-Type: application/json" \
  -d '{"name":"机械键盘","price":399,"stock":10}' > /dev/null

curl -s -X PUT "http://localhost:9200/products/_doc/sku-300?refresh=wait_for" \
  -H "Content-Type: application/json" \
  -d '{"name":"旧款鼠标","price":99}' > /dev/null

cat > bulk.ndjson <<'NDJSON'
{"create":{"_index":"products","_id":"sku-100"}}
{"name":"重复商品","price":1}
{"index":{"_index":"products","_id":"sku-200"}}
{"name":"人体工学鼠标","price":259,"stock":20}
{"update":{"_index":"products","_id":"sku-100"}}
{"doc":{"price":369}}
{"delete":{"_index":"products","_id":"sku-300"}}
NDJSON

curl -s -w '\nHTTP_STATUS:%{http_code}\n' \
  -X POST "http://localhost:9200/_bulk?refresh=wait_for" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary "@bulk.ndjson"

预期输出

json
{
  "took": <MILLISECONDS>,
  "errors": true,
  "items": [
    {
      "create": {
        "_index": "products",
        "_id": "sku-100",
        "status": 409,
        "error": {
          "type": "version_conflict_engine_exception",
          "reason": "<REASON>"
        }
      }
    },
    {
      "index": {
        "_index": "products",
        "_id": "sku-200",
        "status": 201,
        "result": "created"
      }
    },
    {
      "update": {
        "_index": "products",
        "_id": "sku-100",
        "status": 200,
        "result": "updated"
      }
    },
    {
      "delete": {
        "_index": "products",
        "_id": "sku-300",
        "status": 200,
        "result": "deleted"
      }
    }
  ]
}
HTTP_STATUS:200

响应中的版本号、分片信息等字段可能因版本和集群配置而额外出现。took 与错误原因是动态值,因此使用占位符表示。最重要的现象是:整体 HTTP 状态为 200,但顶层 errors 为 true,同时其余三项仍然成功。

正确检查并重试失败项

不能只检查 Bulk 请求的 HTTP 状态码。先判断顶层 errors,再按请求顺序遍历 items;单项 status 为 2xx 才算成功,存在 error 时应记录对应操作、文档 ID、错误类型和原因。

重试时只重新组装失败项,不要重复整个批次。重复提交成功过的 index 可能再次覆盖文档,重复执行非幂等脚本可能造成计数翻倍。对 429 或临时节点异常可采用指数退避;对 400 映射错误、409 创建冲突等确定性问题,应修复数据或操作语义后再提交。

生产程序还应保存“请求条目与响应条目”的位置对应关系。Bulk 响应会按提交顺序返回结果,这使程序可以从原批次中精确提取失败操作并进入重试队列。

控制批次大小与吞吐

Bulk 没有适用于所有场景的固定条数。文档大小差异很大,因此应同时观察请求字节数、单批耗时、节点堆内存、写入线程池拒绝和 429 比例,而不是只设置“每批 1000 条”。

从较小批次开始压测,逐步增加体积,吞吐不再提升或拒绝率上升时回退。单个 HTTP 请求不能超过集群的 http.max_content_length,默认上限通常为 100 MB;实际批次应明显低于上限,为请求头、并发波动和异常文档留出余量。

并发批次数也要独立控制。单批过大增加内存峰值和失败重试成本,并发过高则可能压满写入线程池。稳定方案通常是“有界队列、有限并发、失败项退避重试、持续记录批次指标”。

本课总结

  • Bulk 请求使用 NDJSON,操作元数据行与数据行必须按类型正确配对,文件末尾保留换行
  • HTTP 200 不代表全部成功,必须检查 errors 并逐项读取 items
  • 批次大小和并发度应通过压测确定,失败时只重试对应条目

下一课预告

下一课将继续学习索引管理操作,把文档写入流程与索引别名、生命周期或重建策略连接起来。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

批量写入 Bulk API

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通