NoSQL 与搜索 / 系统课时

更新文档

更新文档

本课用同一条商品文档演示局部字段更新、整篇覆盖与脚本更新。完成后,你能根据“保留未提交字段、完全替换内容、基于旧值计算”三类需求选择正确接口,并通过查询结果确认修改是否生效。

学习目标

  • 区分 _update 局部更新与 Index API 整篇覆盖的行为
  • 使用 Painless 脚本基于文档原值完成原子化计算
  • 识别字段丢失、空操作和版本冲突等关键边界

三种更新方式如何选择

Elasticsearch 中的“更新”最终都会生成新的文档版本,但提交方式不同。局部更新通过 POST /<index>/_update/<id> 传入 doc,只合并指定字段;整篇覆盖通过 PUT /<index>/_doc/<id> 重新索引完整 _source;脚本更新则在分片侧读取旧值并执行计算。

需求 推荐方式 未提交字段 典型用途
修改少量已知字段 doc 局部更新 保留 改价格、状态、标签
以当前对象为准重写文档 Index API 覆盖 删除 同步完整业务快照
根据旧值计算新值 script 脚本更新 保留 库存增减、计数累加

局部更新依赖 _source。如果同时提交 doc 和 script,Elasticsearch 会执行脚本并忽略 doc,因此不要把两种逻辑混在一次请求中。

完整演示:合并、覆盖与脚本计算

下面的 Bash 示例先创建商品,再依次修改价格、覆盖整篇文档、通过脚本增加库存,最后读取文档。示例会删除同名测试索引,仅应在本地练习环境运行。

bash
curl -s -X DELETE "http://localhost:9200/products" > /dev/null

curl -s -o /dev/null -w "create:%{http_code}\n" \
  -X PUT "http://localhost:9200/products/_doc/sku-100?refresh=wait_for" \
  -H "Content-Type: application/json" \
  -d '{"name":"机械键盘","price":399,"stock":10,"tags":["keyboard","wireless"]}'

curl -s -o /dev/null -w "partial:%{http_code}\n" \
  -X POST "http://localhost:9200/products/_update/sku-100?refresh=wait_for" \
  -H "Content-Type: application/json" \
  -d '{"doc":{"price":369}}'

curl -s -o /dev/null -w "replace:%{http_code}\n" \
  -X PUT "http://localhost:9200/products/_doc/sku-100?refresh=wait_for" \
  -H "Content-Type: application/json" \
  -d '{"name":"机械键盘 Pro","price":499,"stock":8}'

curl -s -o /dev/null -w "script:%{http_code}\n" \
  -X POST "http://localhost:9200/products/_update/sku-100?refresh=wait_for" \
  -H "Content-Type: application/json" \
  -d '{"script":{"lang":"painless","source":"ctx._source.stock += params.delta","params":{"delta":2}}}'

curl -s "http://localhost:9200/products/_doc/sku-100"

预期输出

text
create:201
partial:200
replace:200
script:200
{"_index":"products","_id":"sku-100","_version":4,"_seq_no":<SEQ_NO>,"_primary_term":<PRIMARY_TERM>,"found":true,"_source":{"name":"机械键盘 Pro","price":499,"stock":10}}

tags 在最终结果中消失,是因为整篇覆盖请求没有提交该字段。stock 从 8 增加到 10,说明脚本读取了覆盖后的当前值。_seq_no 与 _primary_term 由集群生成,实际值可能不同。

局部更新的边界

默认情况下,局部更新发现字段值没有变化时会返回 result: "noop",避免无意义重写。若文档可能不存在,可使用 doc_as_upsert: true,让同一份 doc 在不存在时负责创建、存在时负责合并。

并发写入时,更新请求可能遇到版本冲突。简单、可重复执行的更新可谨慎设置 retry_on_conflict;涉及余额、库存下限等强约束时,应先读取 _seq_no 与 _primary_term,再通过 if_seq_no 和 if_primary_term 做乐观并发控制,冲突后重新读取业务状态。

脚本必须显式处理字段缺失和类型不匹配。例如库存字段可能不存在时,应先初始化再累加;不要直接执行 ctx._source.stock += params.delta 并假设所有历史文档结构一致。

验证修改是否正确

更新接口返回 200 只表示请求成功执行,业务字段是否符合预期仍需读取文档或执行搜索验证。练习环境可使用 refresh=wait_for 等待变更可搜索;高吞吐生产写入不应为每次请求强制刷新,否则会增加刷新开销。

验收时重点检查 _source 是否保留了应保留字段、覆盖后是否清除了旧字段,以及脚本结果是否满足边界条件。若接口返回 409,应按并发冲突处理,而不是盲目重复提交不可幂等的脚本。

本课总结

  • doc 适合合并少量字段,Index API 适合以完整对象覆盖文档
  • 脚本更新适合基于旧值计算,但必须处理字段缺失、类型和幂等性
  • 更新成功后仍要读取结果,并根据业务风险选择重试或乐观并发控制

下一课预告

下一课将把多条 create、index、update 和 delete 操作组织成 Bulk API 请求,并学习逐项检查失败结果与控制批次大小。

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

目录与阅读设置

阅读设置

17

记录一个想法

更新文档

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

登录哪都通