NoSQL 与搜索 / 系统课时
创建索引与写入文档
创建索引与写入文档
本课通过一组可直接在 Kibana Dev Tools 中执行的请求,完成索引创建、指定 ID 写入和自动 ID 写入,并学会从响应字段判断文档是新建、覆盖还是写入失败。
学习目标
- 能创建带基础字段映射的 Elasticsearch 索引
- 能分别使用指定 ID 和自动 ID 写入 JSON 文档
- 能读懂
_id、result、_version与分片执行结果
创建索引
索引是文档写入的目标容器。下面创建 products-demo 索引,并明确商品名称、价格、库存状态和创建时间的字段类型。显式映射可以避免日期或数值被错误识别。
PUT /products-demo
{
"mappings": {
"properties": {
"name": {
"type": "text"
},
"price": {
"type": "double"
},
"in_stock": {
"type": "boolean"
},
"created_at": {
"type": "date"
}
}
}
}预期结果
{
"acknowledged": true,
"shards_acknowledged": true,
"index": "products-demo"
}acknowledged 表示集群已接受索引创建操作,shards_acknowledged 表示所需分片已在超时前启动。重复执行同一创建请求会得到资源已存在错误,此时不应继续盲目重试。
使用指定 ID 写入文档
指定 ID 适合业务系统已经拥有稳定主键的场景,例如商品编号或订单编号。请求路径中的 1001 会成为文档的 _id。
PUT /products-demo/_doc/1001
{
"name": "机械键盘",
"price": 399.0,
"in_stock": true,
"created_at": "2026-08-03T09:00:00+08:00"
}预期结果(仅列关键字段)
{
"_index": "products-demo",
"_id": "1001",
"_version": 1,
"result": "created"
}首次写入时,HTTP 状态通常为 201 Created,result 为 created。再次使用相同路径写入时,索引接口会以新内容替换该 ID 对应的文档,响应中的 result 会变为 updated,版本号也会增加。
如果业务要求“ID 已存在就拒绝写入”,应使用 PUT /products-demo/_create/1001,或为索引请求设置 op_type=create,避免无意覆盖已有文档。
使用自动 ID 写入文档
没有可复用业务主键时,可以省略路径中的 ID,并使用 POST 让 Elasticsearch 生成唯一 _id。
POST /products-demo/_doc
{
"name": "无线鼠标",
"price": 129.0,
"in_stock": true,
"created_at": "2026-08-03T09:05:00+08:00"
}预期结果(自动 ID 与序列号会因环境不同而变化)
HTTP 201 Created
_index = products-demo
_id = <ID>
result = created
_version = 1自动 ID 适合日志、埋点等不依赖业务主键的数据。应用必须保存响应中的 _id,否则后续无法通过文档接口精确读取、更新或删除该记录。
理解写入响应
_index 表示实际写入的索引,_id 是文档标识,result 表示本次操作结果。_version 会随同一文档的写操作增加;_seq_no 与 _primary_term 可用于乐观并发控制,防止旧请求覆盖新数据。
响应中的 _shards 记录本次操作涉及的分片数量及成功、失败情况。日常验证至少应检查 HTTP 状态、result 和 _shards.failed,不能只看到返回 JSON 就认定写入成功。
验证指定 ID 文档
写入完成后,可以按索引名和 ID 直接读取文档,确认 _source 与提交内容一致。
GET /products-demo/_doc/1001预期结果(省略版本与序列号字段)
{
"_index": "products-demo",
"_id": "1001",
"found": true,
"_source": {
"name": "机械键盘",
"price": 399.0,
"in_stock": true,
"created_at": "2026-08-03T09:00:00+08:00"
}
}如果返回 found: true 且 _source 内容正确,说明索引创建、字段解析和指定 ID 写入均已完成。自动 ID 文档也可使用其响应中的 <ID> 按相同方式验证。
本课总结
- 创建索引时显式定义关键字段类型,可以降低动态映射带来的数据类型风险
- 指定 ID 便于业务关联,但重复写入可能覆盖原文档;自动 ID 必须由应用保存
- 写入后应联合检查 HTTP 状态、
result、_id和分片失败数
下一课预告
下一课将使用文档接口读取和删除数据,并重点区分文档不存在、索引不存在以及删除成功后的不同响应。