---
title: "创建文档（指定ID）"
date: 2026-01-13
lastmod: 2026-01-13
description: "使用指定ID创建新文档，如果文档已存在则失败"
tags: ["文档操作", "创建操作", "数据写入"]
summary: "使用指定的文档 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 数据："
---


使用指定的文档 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 数据：

```json
{
  "field1": "value1",
  "field2": "value2",
  ...
}
```

## 示例

### 基本创建

```bash
PUT /my_index/_create/1
{
  "user": "kimchy",
  "message": "Hello World"
}
```

**响应示例：**

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

### 文档已存在（失败）

```bash
PUT /my_index/_create/1
{
  "user": "kimchy",
  "message": "Duplicate"
}
```

**响应示例：**

```json
{
  "error": {
    "type": "version_conflict_engine_exception",
    "reason": "[1]: version conflict, document already exists (current version [1])"
  },
  "status": 409
}
```

### 使用路由

```bash
POST /my_index/_create/user123?routing=user1
{
  "name": "John",
  "email": "john@example.com"
}
```

### 使用摄取管道

```bash
POST /my_index/_create/1?pipeline=timestamp_pipeline
{
  "message": "Hello"
}
```

### 立即刷新

```bash
PUT /my_index/_create/1?refresh=true
{
  "user": "kimchy"
}
```

### 等待刷新完成

```bash
PUT /my_index/_create/1?refresh=wait_for
{
  "user": "kimchy"
}
```

### 使用版本控制

```bash
PUT /my_index/_create/1?version=1&version_type=external
{
  "user": "kimchy"
}
```

### 条件创建

```bash
PUT /my_index/_create/1?if_seq_no=0&if_primary_term=1
{
  "user": "kimchy"
}
```

### 等待所有分片活跃

```bash
PUT /my_index/_create/1?wait_for_active_shards=all
{
  "user": "kimchy"
}
```

### 设置超时

```bash
PUT /my_index/_create/1?timeout=5m
{
  "user": "kimchy"
}
```

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

```bash
PUT /my_index/_doc/1/_create
{
  "user": "kimchy"
}
```

> **注意**：类型参数已弃用，推荐使用 `/_create/{id}`。

## 响应字段说明

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

## 错误处理

### 版本冲突（文档已存在）

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

### 索引不存在

```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
}
```

## 使用场景

### 场景 1：使用业务 ID

```bash
PUT /products/_create/PROD-001
{
  "name": "Product 1",
  "price": 99.99,
  "category": "electronics"
}
```

### 场景 2：确保不覆盖

```bash
# 第一次创建成功
PUT /users/_create/user123
{
  "name": "John",
  "email": "john@example.com"
}

# 第二次失败（不会覆盖）
PUT /users/_create/user123
{
  "name": "Jane",
  "email": "jane@example.com"
}
# 返回 409 错误
```

### 场景 3：条件创建

```bash
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` | 等待刷新完成 |

## 注意事项

1. **类型已弃用**：URL 中的类型参数已被弃用
2. **幂等性保证**：确保不会意外覆盖现有文档
3. **ID 必需**：必须提供文档 ID
4. **409 错误**：文档已存在时返回 HTTP 409
5. **与 PUT /{index}/_doc/{id} 的区别**：后者会覆盖已存在的文档