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 示例先创建商品,再依次修改价格、覆盖整篇文档、通过脚本增加库存,最后读取文档。示例会删除同名测试索引,仅应在本地练习环境运行。
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"预期输出
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 请求,并学习逐项检查失败结果与控制批次大小。