Bulk API #

在单个请求中执行多个 index、create、update、delete 操作。是高吞吐写入的核心能力。

请求格式 #

POST /_bulk
POST /<index>/_bulk

路径参数 #

参数	必需	说明
`<index>`	否	默认索引。指定后操作行中可省略 `_index`

查询参数 #

参数	类型	默认值	说明
`routing`	string	—	默认路由值
`pipeline`	string	—	默认 Ingest Pipeline
`refresh`	string	`false`	所有操作完成后的刷新策略
`timeout`	time	`1m`	超时时间
`wait_for_active_shards`	string	—	活跃分片数量
`require_alias`	boolean	—	要求目标必须是别名
`_source`	string/boolean	—	默认 `_source` 过滤
`_source_includes`	string	—	默认包含字段
`_source_excludes`	string	—	默认排除字段

请求体格式（NDJSON） #

请求体是逐行 JSON（Newline Delimited JSON）格式，每行一个 JSON 对象：

{ "action": { "metadata" } }\n
{ "request_body" }\n

格式要求：

每行必须以换行符 \n 结尾，包括最后一行
行内不能包含未转义的换行符
不能使用 pretty 格式
Content-Type 应为 application/x-ndjson

操作类型 #

操作	说明	需要请求体行
`index`	写入文档，已存在则覆盖	是
`create`	仅创建，已存在则报 409	是
`update`	部分更新文档	是（`doc` 或 `script`）
`delete`	删除文档	否

操作行元数据 #

字段	说明
`_index`	目标索引（URL 已指定时可省略）
`_id`	文档 ID（`index` 和 `create` 可省略以自动生成）
`routing`	路由值
`pipeline`	Ingest Pipeline
`require_alias`	要求目标是别名
`_retry_on_conflict`	`update` 操作的冲突重试次数

示例 #

POST /_bulk
{ "delete": { "_index": "website", "_id": "123" } }
{ "create": { "_index": "website", "_id": "123" } }
{ "title": "My first blog post" }
{ "index":  { "_index": "website" } }
{ "title": "My second blog post" }
{ "update": { "_index": "website", "_id": "123", "_retry_on_conflict": 3 } }
{ "doc": { "title": "My updated blog post" } }

指定默认索引 #

POST /website/_bulk
{ "index": {} }
{ "title": "Event logged in" }
{ "index": {} }
{ "title": "Another event" }

响应 #

{
  "took":   4,
  "errors": false,
  "items": [
    { "delete": { "_index": "website", "_id": "123", "_version": 2, "status": 200, "result": "deleted" } },
    { "create": { "_index": "website", "_id": "123", "_version": 3, "status": 201, "result": "created" } },
    { "create": { "_index": "website", "_id": "EiwfApScQiiy7TIKFxRCTw", "_version": 1, "status": 201, "result": "created" } },
    { "update": { "_index": "website", "_id": "123", "_version": 4, "status": 200, "result": "updated" } }
  ]
}

errors: false：所有子操作均成功
errors: true：至少有一条失败，需逐条检查 items 中的 status 与 error

部分失败示例 #

{
  "took": 3,
  "errors": true,
  "items": [
    {
      "create": {
        "_index": "website", "_id": "123",
        "status": 409,
        "error": { "type": "version_conflict_engine_exception", "reason": "..." }
      }
    },
    {
      "index": {
        "_index": "website", "_id": "124",
        "_version": 1, "status": 201, "result": "created"
      }
    }
  ]
}

Bulk 不是事务。每条子操作独立执行、独立成功或失败。调用方需逐条检查结果并决定是否重试。

批次大小建议 #

没有固定最佳值，取决于硬件配置、文档大小、集群负载。推荐：

从 1,000–5,000 条文档 / 每批 5–15 MB 开始
逐步增大，观察节点 CPU/内存/IO/延迟
当吞吐量不再上升或开始下降时，即为当前环境的上限

Bulk 请求在协调节点一次性驻留内存，过大的批次会占用过多内存并影响 GC。

参考导航 #

需求	参见
单条写入	Index API
批量检索	Multi Get API
写入链路预处理	摄取管道
分布式写入过程	分布式写入过程