使用指定的文档 ID 创建新文档。如果文档已存在，操作将失败。
API #
POST /{index}/_create/{id}
PUT /{index}/_create/{id}
POST /{index}/{type}/{id}/_create
PUT /{index}/{type}/{id}/_create
API 的作用 #
该 API 用于使用指定的 ID 创建新文档。与 /_doc API 不同，此 API 确保不会意外覆盖已存在的文档。
操作特点 #
| 特性 | 描述 |
|---|---|
| 幂等性 | 如果文档已存在，返回错误（HTTP 409） |
| ID 指定 | 必须提供文档 ID |
| 创建专用 | 只能创建新文档，不能更新 |
与其他 API 的区别 #
| API | 文档不存在 | 文档已存在 |
|---|---|---|
/_create/{id} | 创建新文档 | 失败（409） |
/_doc/{id} | 创建新文档 | 覆盖更新 |
/_doc | 自动生成 ID | - |
API 的参数 #
路由参数 #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
{index} | 字符串 | 必需 | 索引名称 |
{id} | 字符串 | 必需 | 文档 ID |
{type} | 字符串 | 否 | 文档类型（已弃用） |
Query String 参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
routing | 字符串 | 否 | - | 路由值，控制文档分片位置 |
pipeline | 字符串 | 否 | - | 处理管道名称 |
refresh | 字符串 | 否 | false | 刷新策略：true、false、wait_for |
timeout | 时间值 | 否 | 1m | 操作超时时间 |
version | 整数 | 否 | - | 文档版本号 |
version_type | 字符串 | 否 | internal | 版本类型：internal、external、external_gte |
if_seq_no | 整数 | 否 | - | 序列号条件 |
if_primary_term | 整数 | 否 | - | 主版本条件 |
require_alias | 布尔值 | 否 | false | 是否要求索引必须是别名 |
wait_for_active_shards | 字符串 | 否 | 1 | 等待活跃分片数：1、all、具体数字 |
请求体参数 #
请求体必须包含文档的 JSON 数据：
{
"field1": "value1",
"field2": "value2",
...
}
示例 #
基本创建 #
PUT /my_index/_create/1
{
"user": "kimchy",
"message": "Hello World"
}
响应示例：
{
"_index": "my_index",
"_type": "_doc",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1
}
文档已存在（失败） #
PUT /my_index/_create/1
{
"user": "kimchy",
"message": "Duplicate"
}
响应示例：
{
"error": {
"type": "version_conflict_engine_exception",
"reason": "[1]: version conflict, document already exists (current version [1])"
},
"status": 409
}
使用路由 #
POST /my_index/_create/user123?routing=user1
{
"name": "John",
"email": "john@example.com"
}
使用摄取管道 #
POST /my_index/_create/1?pipeline=timestamp_pipeline
{
"message": "Hello"
}
立即刷新 #
PUT /my_index/_create/1?refresh=true
{
"user": "kimchy"
}
等待刷新完成 #
PUT /my_index/_create/1?refresh=wait_for
{
"user": "kimchy"
}
使用版本控制 #
PUT /my_index/_create/1?version=1&version_type=external
{
"user": "kimchy"
}
条件创建 #
PUT /my_index/_create/1?if_seq_no=0&if_primary_term=1
{
"user": "kimchy"
}
等待所有分片活跃 #
PUT /my_index/_create/1?wait_for_active_shards=all
{
"user": "kimchy"
}
设置超时 #
PUT /my_index/_create/1?timeout=5m
{
"user": "kimchy"
}
使用已弃用的类型参数 #
PUT /my_index/_doc/1/_create
{
"user": "kimchy"
}
注意：类型参数已弃用，推荐使用
/_create/{id}。
响应字段说明 #
| 字段 | 描述 |
|---|---|
_index | 文档所在的索引 |
_type | 文档类型（固定为 _doc） |
_id | 文档 ID |
_version | 文档版本号 |
result | 操作结果：created |
_shards | 分片信息 |
_seq_no | 序列号 |
_primary_term | 主版本号 |
错误处理 #
版本冲突（文档已存在） #
{
"error": {
"type": "version_conflict_engine_exception",
"reason": "[1]: version conflict, document already exists"
},
"status": 409
}
索引不存在 #
{
"error": {
"type": "index_not_found_exception",
"reason": "no such index [my_index]"
},
"status": 404
}
条件不满足 #
{
"error": {
"type": "version_conflict_engine_exception",
"reason": "[1]: version conflict"
},
"status": 409
}
使用场景 #
场景 1：使用业务 ID #
PUT /products/_create/PROD-001
{
"name": "Product 1",
"price": 99.99,
"category": "electronics"
}
场景 2：确保不覆盖 #
# 第一次创建成功
PUT /users/_create/user123
{
"name": "John",
"email": "john@example.com"
}
# 第二次失败（不会覆盖）
PUT /users/_create/user123
{
"name": "Jane",
"email": "jane@example.com"
}
# 返回 409 错误
场景 3：条件创建 #
PUT /orders/_create/1?if_seq_no=0&if_primary_term=1
{
"customer": "user123",
"total": 99.99
}
版本控制（version_type） #
| 类型 | 描述 |
|---|---|
internal | 内部版本控制（默认） |
external | 外部版本控制，版本号必须大于当前版本 |
external_gte | 外部版本大于等于 |
刷新策略（refresh） #
| 值 | 描述 |
|---|---|
true | 立即刷新 |
false | 不刷新（默认） |
wait_for | 等待刷新完成 |
注意事项 #
- 类型已弃用：URL 中的类型参数已被弃用
- 幂等性保证：确保不会意外覆盖现有文档
- ID 必需：必须提供文档 ID
- 409 错误：文档已存在时返回 HTTP 409
- 与 PUT /{index}/_doc/{id} 的区别：后者会覆盖已存在的文档
