NoSQL 与搜索 / 系统课时

创建索引与写入文档

创建索引与写入文档

本课通过一组可直接在 Kibana Dev Tools 中执行的请求,完成索引创建、指定 ID 写入和自动 ID 写入,并学会从响应字段判断文档是新建、覆盖还是写入失败。

学习目标

  • 能创建带基础字段映射的 Elasticsearch 索引
  • 能分别使用指定 ID 和自动 ID 写入 JSON 文档
  • 能读懂 _id、result、_version 与分片执行结果

创建索引

索引是文档写入的目标容器。下面创建 products-demo 索引,并明确商品名称、价格、库存状态和创建时间的字段类型。显式映射可以避免日期或数值被错误识别。

http
PUT /products-demo
{
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "price": {
        "type": "double"
      },
      "in_stock": {
        "type": "boolean"
      },
      "created_at": {
        "type": "date"
      }
    }
  }
}

预期结果

json
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "products-demo"
}

acknowledged 表示集群已接受索引创建操作,shards_acknowledged 表示所需分片已在超时前启动。重复执行同一创建请求会得到资源已存在错误,此时不应继续盲目重试。

使用指定 ID 写入文档

指定 ID 适合业务系统已经拥有稳定主键的场景,例如商品编号或订单编号。请求路径中的 1001 会成为文档的 _id。

http
PUT /products-demo/_doc/1001
{
  "name": "机械键盘",
  "price": 399.0,
  "in_stock": true,
  "created_at": "2026-08-03T09:00:00+08:00"
}

预期结果(仅列关键字段)

json
{
  "_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。

http
POST /products-demo/_doc
{
  "name": "无线鼠标",
  "price": 129.0,
  "in_stock": true,
  "created_at": "2026-08-03T09:05:00+08:00"
}

预期结果(自动 ID 与序列号会因环境不同而变化)

text
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 与提交内容一致。

http
GET /products-demo/_doc/1001

预期结果(省略版本与序列号字段)

json
{
  "_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 和分片失败数

下一课预告

下一课将使用文档接口读取和删除数据,并重点区分文档不存在、索引不存在以及删除成功后的不同响应。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建索引与写入文档

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

登录哪都通