上一篇【第45篇】Elasticsearch分布式检索原理——Query Then Fetch两阶段搜索下一篇【第47篇】Elasticsearch集群形成机制摘要Elasticsearch中的文档更新看似简单实际上在分布式环境下需要协调多个节点的精确同步。本文从局部更新partial update的完整流程入手追踪协调节点→主分片节点的每一步操作GET读取→merge合并→写入主分片→同步副本并与完整的index操作进行性能对比。接着深入并发环境下的挑战多个协调节点同时更新同一文档时的竞态条件如何产生。文章重点解析_seq_no序列号和_primary_term主任期号构成的乐观锁机制说明其如何替代传统版本号来保证更新的线性一致性以及retry_on_conflict自动重试的工作原理。关键词Elasticsearch分布式更新、partial update、并发控制、_seq_no、版本冲突。一、为什么需要局部更新Elasticsearch中的文档是不可变的——一次写入后它的底层Lucene数据结构不会被修改。那么更新操作是如何实现的答案是先删除旧文档再索引新文档。但Elasticsearch提供了两种实现这一逻辑的方式1.1 Index操作全文替换客户端获取完整文档、修改、再发送完整文档// 方式一先GET完整文档修改后PUT回去GET/shop/_doc/1// 返回完整_sourcePUT/shop/_doc/1// 发送完整的修改后文档{title:iPhone 14 Pro Max 256GB,description:Apple最新旗舰手机 iPhone 14 Pro Max 暗紫色,brand:Apple,price:8999,stock:50}1.2 Partial Update局部更新只发送需要修改的字段// 方式二直接发送需要修改的字段POST/shop/_update/1{doc:{stock:50,description:Apple最新旗舰手机 iPhone 14 Pro Max 暗紫色}}两种方式的最终效果相同但partial update在分布式环境下有明显的性能优势——减少了网络传输因为GET操作在主分片节点上就地完成不需要将完整文档回传给客户端。二、局部更新的完整流程2.1 流程图客户端 协调节点 主分片节点 副本分片节点 │ │ │ │ │ ① POST /_update/1 │ │ │ │ { doc: { │ │ │ │ stock: 50 }} │ │ │ │───────────────────│ │ │ │ │ │ │ │ │ ② 路由计算 │ │ │ │ 转发到主分片 │ │ │ │───────────────────│ │ │ │ │ │ │ │ │ ③ GET 当前文档 │ │ │ │ 读取_source字段 │ │ │ │ 获取 _seq_no │ │ │ │ 获取 _primary_term │ │ │ │ │ │ │ │ ④ Merge 合并字段 │ │ │ │ 将stock:50合并 │ │ │ │ 到_source对象中 │ │ │ │ │ │ │ │ ⑤ 乐观锁检查 │ │ │ │ if_seq_no? │ │ │ │ if_primary_term? │ │ │ │ │ │ │ │ ⑥ 写入主分片 │ │ │ │ (删除旧文档 │ │ │ │ 索引新文档) │ │ │ │ _seq_no 1 │ │ │ │ │ │ │ │ ⑦ 同步到副本分片 │ │ │ │───────────────────│ │ │ │ │ │ │ │ ⑧ 副本确认成功 │ │ │ │───────────────────│ │ │ │ │ │ │ ⑨ 主分片报告成功 │ │ │ │───────────────────│ │ │ │ │ │ │ ⑩ 返回更新结果 │ │ │ │───────────────────│ │ │2.2 关键步骤详解步骤③GET当前文档主分片本地操作这是partial update的核心优势所在。GET操作在主分片所在节点上就地完成不需要经过网络回传给客户端。读取内容包括_source文档的完整JSON内容_seq_no文档当前的序列号_primary_term当前主分片的任期号步骤④Merge合并字段Elasticsearch将用户提交的更新字段深度合并到_source中。如果用户同时提供了script则执行脚本处理// 使用Script进行局部更新POST/shop/_update/1{script:{source:ctx._source.stock params.quantity,params:{quantity:-1}}}// 执行结果stock 从50变为49步骤⑤乐观锁检查合并完成后在写入之前Elasticsearch执行乐观锁检查。如果文档在被读取之后、写入之前被其他操作修改过则返回版本冲突错误。2.3 Partial Update vs Index 对比对比维度Partial Update (_update)Index (PUT/POST)网络传输仅传输修改的字段几十字节传输完整文档可能数KBGET操作主分片节点本地完成客户端需要先GET再PUT2次网络往返并发安全性内置乐观锁检查需要手动传递version参数原子性GET→Merge→Index是原子操作客户端自行保证Script支持支持可直接在请求中嵌入不支持需要客户端计算性能高并发场景★★★★★★★★☆☆三、并发更新的挑战3.1 竞态条件场景在分布式环境下多个客户端可能同时尝试更新同一文档。考虑以下场景时间线两个用户同时修改商品库存 用户A: 读取stock50减少1 → 期望写入stock49 用户B: 读取stock50减少2 → 期望写入stock48 理想的最终结果stock 4750-1-247 但如果不做并发控制 时刻T1: 用户A GET文档 → _seq_no10, stock50 时刻T2: 用户B GET文档 → _seq_no10, stock50 时刻T3: 用户A Merge → stock49, 写入成功 → _seq_no11 时刻T4: 用户B Merge → stock48, 写入成功 → _seq_no12 结果stock48用户A的减少1丢失了❌ 错误这就是典型的Lost Update丢失更新问题。3.2 _seq_no _primary_termElasticsearch的乐观锁Elasticsearch使用_seq_no和_primary_term组合实现了乐观锁Optimistic Locking机制完全解决了并发更新的竞态问题。_seq_no序列号_seq_no是整个索引维度上递增的整数。每当发生一次写入包括create、update、delete_seq_no就递增1。它类似于数据库的auto-increment ID用于标识操作的发生顺序。_primary_term主任期号_primary_term用于标识当前的主分片是哪一任。当主分片发生切换如节点宕机后新主分片被选举_primary_term递增。这防止了旧主分片网络分区恢复后的幽灵写入。3.3 乐观锁的工作原理正确的并发更新流程带乐观锁 时刻T1: 用户A GET文档 → _seq_no10, _primary_term1, stock50 时刻T2: 用户B GET文档 → _seq_no10, _primary_term1, stock50 时刻T3: 用户A Merge → stock49 写入时检查: if_seq_no10, if_primary_term1 ✓ 写入成功 → 新_seq_no11 时刻T4: 用户B Merge → stock48 写入时检查: if_seq_no10, if_primary_term1 但是当前_seq_no已是11 ≠ 10 ✗ 返回版本冲突错误 VersionConflictEngineException 时刻T5: 用户B 重新GET文档 → _seq_no11, stock49 重新Merge → stock47 (49-2) 写入时检查: if_seq_no11, if_primary_term1 ✓ 写入成功 → 新_seq_no12 结果stock47 ✓ 正确3.4 API示例// 带乐观锁的更新POST/shop/_update/1?if_seq_no10if_primary_term1{doc:{stock:49}}// 如果_seq_no不匹配返回409错误{error:{type:version_conflict_engine_exception,reason:[1]: version conflict, required seqNo [10], primary term [1]. current document has seqNo [11] and primary term [1]},status:409}四、retry_on_conflict自动重试机制4.1 为什么需要自动重试在高并发场景下乐观锁冲突会频繁发生。如果每次冲突都需要客户端捕获异常、重新读取、重新计算不仅代码复杂而且容易在重试风暴中加剧系统压力。Elasticsearch提供了retry_on_conflict参数在主分片层面自动处理版本冲突重试。4.2 retry_on_conflict的工作原理retry_on_conflict3 的执行逻辑 第1次尝试 ① GET文档 → _seq_no10, stock50 ② Merge → stock49 ③ 写入检查当前_seq_no11 ≠ 10 → 冲突 ④ retry_on_conflict 0进行重试 第2次尝试自动 ① 重新GET文档 → _seq_no11, stock49 ② Merge → stock48 ③ 写入检查当前_seq_no12 ≠ 11 → 再次冲突 ④ retry_on_conflict 1继续重试 第3次尝试自动 ① 重新GET文档 → _seq_no12, stock48 ② Merge → stock47 ③ 写入检查当前_seq_no12 12 ✓ → 成功 ④ 返回成功 如果3次都冲突返回409错误给客户端。4.3 使用示例// 启用自动重试重试3次POST/shop/_update/1?retry_on_conflict3{script:{source:ctx._source.stock - params.quantity,params:{quantity:1}}}// retry_on_conflict建议值// 低并发场景 → 0或1// 中等并发场景 → 3// 高并发场景 → 5-10五、脚本更新的幂等性设计5.1 为什么需要幂等性当使用retry_on_conflict时Script可能会被多次执行。如果Script不是幂等的那么重试可能导致错误的计算结果。非幂等示例危险// ❌ 危险如果重试执行click_count会被多次1POST/shop/_update/1?retry_on_conflict3{script:{source:ctx._source.click_count 1}}// 场景业务上希望每次请求1但重试会导致1执行多次幂等设计安全// ✓ 安全使用参数传递最终值幂等POST/shop/_update/1?retry_on_conflict3{script:{source:if(ctx._source.click_countnull||ctx._source.click_countparams.target){ctx._source.click_countparams.target},params:{target:101// 客户端已知的正确值}}}// ✓ 安全使用doc而不是scriptdoc本身就是幂等的POST/shop/_update/1?retry_on_conflict3{doc:{stock:47,updated_at:2026-05-22T10:00:00Z}}5.2 幂等性设计原则原则说明示例使用绝对赋值避免相对计算1/-1使用最终值ctx._source.count params.value添加条件守卫在Script中检查当前值避免重复操作if ctx._source.count params.value优先使用docdoc字段是幂等的合并操作doc: {field: value}使用upsert处理文档可能不存在的情况upsert: {count: 0}5.3 Upsert处理文档不存在的情况// Upsert: 文档存在时更新不存在时插入POST/shop/_update/1?retry_on_conflict3{script:{source:ctx._source.views 1},upsert:{title:iPhone 14 Pro,views:1,created_at:2026-05-22}}六、总结与最佳实践核心要点回顾Partial Update在分布式环境下有独特优势GET操作在主分片节点本地完成避免了将完整文档回传客户端的网络开销。_seq_no _primary_term构成乐观锁替代旧版的_version字段实现更精准的并发控制。_seq_no跟踪操作顺序_primary_term防止幽灵写入。retry_on_conflict是自动化的冲突处理机制在文档被频繁并发更新的场景下无需客户端反复捕获异常重试但要注意Script的幂等性设计。Script编写的黄金法则使用绝对赋值而非相对计算添加条件守卫避免重复操作优先使用doc字段进行简单更新。最佳实践检查表实践建议详细说明简单字段更新优先用docdoc: {field: value}比script更简单、更安全Script加条件守卫使用if (value params.target)确保幂等性高并发更新设置retry_on_conflict根据并发度设置3-5次重试避免客户端处理冲突使用upsert处理插入或更新一条请求同时处理文档可能不存在的情况避免Script中的非幂等操作不使用、-等相对运算除非有严格的业务保证监控版本冲突率如果conflict率持续高于5%考虑业务拆分或降低并发度上一篇【第45篇】Elasticsearch分布式检索原理——Query Then Fetch两阶段搜索下一篇【第47篇】Elasticsearch集群形成机制
【Elasticsearch从入门到精通】第46篇：Elasticsearch分布式文档更新原理——局部更新与并发处理
上一篇【第45篇】Elasticsearch分布式检索原理——Query Then Fetch两阶段搜索下一篇【第47篇】Elasticsearch集群形成机制摘要Elasticsearch中的文档更新看似简单实际上在分布式环境下需要协调多个节点的精确同步。本文从局部更新partial update的完整流程入手追踪协调节点→主分片节点的每一步操作GET读取→merge合并→写入主分片→同步副本并与完整的index操作进行性能对比。接着深入并发环境下的挑战多个协调节点同时更新同一文档时的竞态条件如何产生。文章重点解析_seq_no序列号和_primary_term主任期号构成的乐观锁机制说明其如何替代传统版本号来保证更新的线性一致性以及retry_on_conflict自动重试的工作原理。关键词Elasticsearch分布式更新、partial update、并发控制、_seq_no、版本冲突。一、为什么需要局部更新Elasticsearch中的文档是不可变的——一次写入后它的底层Lucene数据结构不会被修改。那么更新操作是如何实现的答案是先删除旧文档再索引新文档。但Elasticsearch提供了两种实现这一逻辑的方式1.1 Index操作全文替换客户端获取完整文档、修改、再发送完整文档// 方式一先GET完整文档修改后PUT回去GET/shop/_doc/1// 返回完整_sourcePUT/shop/_doc/1// 发送完整的修改后文档{title:iPhone 14 Pro Max 256GB,description:Apple最新旗舰手机 iPhone 14 Pro Max 暗紫色,brand:Apple,price:8999,stock:50}1.2 Partial Update局部更新只发送需要修改的字段// 方式二直接发送需要修改的字段POST/shop/_update/1{doc:{stock:50,description:Apple最新旗舰手机 iPhone 14 Pro Max 暗紫色}}两种方式的最终效果相同但partial update在分布式环境下有明显的性能优势——减少了网络传输因为GET操作在主分片节点上就地完成不需要将完整文档回传给客户端。二、局部更新的完整流程2.1 流程图客户端 协调节点 主分片节点 副本分片节点 │ │ │ │ │ ① POST /_update/1 │ │ │ │ { doc: { │ │ │ │ stock: 50 }} │ │ │ │───────────────────│ │ │ │ │ │ │ │ │ ② 路由计算 │ │ │ │ 转发到主分片 │ │ │ │───────────────────│ │ │ │ │ │ │ │ │ ③ GET 当前文档 │ │ │ │ 读取_source字段 │ │ │ │ 获取 _seq_no │ │ │ │ 获取 _primary_term │ │ │ │ │ │ │ │ ④ Merge 合并字段 │ │ │ │ 将stock:50合并 │ │ │ │ 到_source对象中 │ │ │ │ │ │ │ │ ⑤ 乐观锁检查 │ │ │ │ if_seq_no? │ │ │ │ if_primary_term? │ │ │ │ │ │ │ │ ⑥ 写入主分片 │ │ │ │ (删除旧文档 │ │ │ │ 索引新文档) │ │ │ │ _seq_no 1 │ │ │ │ │ │ │ │ ⑦ 同步到副本分片 │ │ │ │───────────────────│ │ │ │ │ │ │ │ ⑧ 副本确认成功 │ │ │ │───────────────────│ │ │ │ │ │ │ ⑨ 主分片报告成功 │ │ │ │───────────────────│ │ │ │ │ │ │ ⑩ 返回更新结果 │ │ │ │───────────────────│ │ │2.2 关键步骤详解步骤③GET当前文档主分片本地操作这是partial update的核心优势所在。GET操作在主分片所在节点上就地完成不需要经过网络回传给客户端。读取内容包括_source文档的完整JSON内容_seq_no文档当前的序列号_primary_term当前主分片的任期号步骤④Merge合并字段Elasticsearch将用户提交的更新字段深度合并到_source中。如果用户同时提供了script则执行脚本处理// 使用Script进行局部更新POST/shop/_update/1{script:{source:ctx._source.stock params.quantity,params:{quantity:-1}}}// 执行结果stock 从50变为49步骤⑤乐观锁检查合并完成后在写入之前Elasticsearch执行乐观锁检查。如果文档在被读取之后、写入之前被其他操作修改过则返回版本冲突错误。2.3 Partial Update vs Index 对比对比维度Partial Update (_update)Index (PUT/POST)网络传输仅传输修改的字段几十字节传输完整文档可能数KBGET操作主分片节点本地完成客户端需要先GET再PUT2次网络往返并发安全性内置乐观锁检查需要手动传递version参数原子性GET→Merge→Index是原子操作客户端自行保证Script支持支持可直接在请求中嵌入不支持需要客户端计算性能高并发场景★★★★★★★★☆☆三、并发更新的挑战3.1 竞态条件场景在分布式环境下多个客户端可能同时尝试更新同一文档。考虑以下场景时间线两个用户同时修改商品库存 用户A: 读取stock50减少1 → 期望写入stock49 用户B: 读取stock50减少2 → 期望写入stock48 理想的最终结果stock 4750-1-247 但如果不做并发控制 时刻T1: 用户A GET文档 → _seq_no10, stock50 时刻T2: 用户B GET文档 → _seq_no10, stock50 时刻T3: 用户A Merge → stock49, 写入成功 → _seq_no11 时刻T4: 用户B Merge → stock48, 写入成功 → _seq_no12 结果stock48用户A的减少1丢失了❌ 错误这就是典型的Lost Update丢失更新问题。3.2 _seq_no _primary_termElasticsearch的乐观锁Elasticsearch使用_seq_no和_primary_term组合实现了乐观锁Optimistic Locking机制完全解决了并发更新的竞态问题。_seq_no序列号_seq_no是整个索引维度上递增的整数。每当发生一次写入包括create、update、delete_seq_no就递增1。它类似于数据库的auto-increment ID用于标识操作的发生顺序。_primary_term主任期号_primary_term用于标识当前的主分片是哪一任。当主分片发生切换如节点宕机后新主分片被选举_primary_term递增。这防止了旧主分片网络分区恢复后的幽灵写入。3.3 乐观锁的工作原理正确的并发更新流程带乐观锁 时刻T1: 用户A GET文档 → _seq_no10, _primary_term1, stock50 时刻T2: 用户B GET文档 → _seq_no10, _primary_term1, stock50 时刻T3: 用户A Merge → stock49 写入时检查: if_seq_no10, if_primary_term1 ✓ 写入成功 → 新_seq_no11 时刻T4: 用户B Merge → stock48 写入时检查: if_seq_no10, if_primary_term1 但是当前_seq_no已是11 ≠ 10 ✗ 返回版本冲突错误 VersionConflictEngineException 时刻T5: 用户B 重新GET文档 → _seq_no11, stock49 重新Merge → stock47 (49-2) 写入时检查: if_seq_no11, if_primary_term1 ✓ 写入成功 → 新_seq_no12 结果stock47 ✓ 正确3.4 API示例// 带乐观锁的更新POST/shop/_update/1?if_seq_no10if_primary_term1{doc:{stock:49}}// 如果_seq_no不匹配返回409错误{error:{type:version_conflict_engine_exception,reason:[1]: version conflict, required seqNo [10], primary term [1]. current document has seqNo [11] and primary term [1]},status:409}四、retry_on_conflict自动重试机制4.1 为什么需要自动重试在高并发场景下乐观锁冲突会频繁发生。如果每次冲突都需要客户端捕获异常、重新读取、重新计算不仅代码复杂而且容易在重试风暴中加剧系统压力。Elasticsearch提供了retry_on_conflict参数在主分片层面自动处理版本冲突重试。4.2 retry_on_conflict的工作原理retry_on_conflict3 的执行逻辑 第1次尝试 ① GET文档 → _seq_no10, stock50 ② Merge → stock49 ③ 写入检查当前_seq_no11 ≠ 10 → 冲突 ④ retry_on_conflict 0进行重试 第2次尝试自动 ① 重新GET文档 → _seq_no11, stock49 ② Merge → stock48 ③ 写入检查当前_seq_no12 ≠ 11 → 再次冲突 ④ retry_on_conflict 1继续重试 第3次尝试自动 ① 重新GET文档 → _seq_no12, stock48 ② Merge → stock47 ③ 写入检查当前_seq_no12 12 ✓ → 成功 ④ 返回成功 如果3次都冲突返回409错误给客户端。4.3 使用示例// 启用自动重试重试3次POST/shop/_update/1?retry_on_conflict3{script:{source:ctx._source.stock - params.quantity,params:{quantity:1}}}// retry_on_conflict建议值// 低并发场景 → 0或1// 中等并发场景 → 3// 高并发场景 → 5-10五、脚本更新的幂等性设计5.1 为什么需要幂等性当使用retry_on_conflict时Script可能会被多次执行。如果Script不是幂等的那么重试可能导致错误的计算结果。非幂等示例危险// ❌ 危险如果重试执行click_count会被多次1POST/shop/_update/1?retry_on_conflict3{script:{source:ctx._source.click_count 1}}// 场景业务上希望每次请求1但重试会导致1执行多次幂等设计安全// ✓ 安全使用参数传递最终值幂等POST/shop/_update/1?retry_on_conflict3{script:{source:if(ctx._source.click_countnull||ctx._source.click_countparams.target){ctx._source.click_countparams.target},params:{target:101// 客户端已知的正确值}}}// ✓ 安全使用doc而不是scriptdoc本身就是幂等的POST/shop/_update/1?retry_on_conflict3{doc:{stock:47,updated_at:2026-05-22T10:00:00Z}}5.2 幂等性设计原则原则说明示例使用绝对赋值避免相对计算1/-1使用最终值ctx._source.count params.value添加条件守卫在Script中检查当前值避免重复操作if ctx._source.count params.value优先使用docdoc字段是幂等的合并操作doc: {field: value}使用upsert处理文档可能不存在的情况upsert: {count: 0}5.3 Upsert处理文档不存在的情况// Upsert: 文档存在时更新不存在时插入POST/shop/_update/1?retry_on_conflict3{script:{source:ctx._source.views 1},upsert:{title:iPhone 14 Pro,views:1,created_at:2026-05-22}}六、总结与最佳实践核心要点回顾Partial Update在分布式环境下有独特优势GET操作在主分片节点本地完成避免了将完整文档回传客户端的网络开销。_seq_no _primary_term构成乐观锁替代旧版的_version字段实现更精准的并发控制。_seq_no跟踪操作顺序_primary_term防止幽灵写入。retry_on_conflict是自动化的冲突处理机制在文档被频繁并发更新的场景下无需客户端反复捕获异常重试但要注意Script的幂等性设计。Script编写的黄金法则使用绝对赋值而非相对计算添加条件守卫避免重复操作优先使用doc字段进行简单更新。最佳实践检查表实践建议详细说明简单字段更新优先用docdoc: {field: value}比script更简单、更安全Script加条件守卫使用if (value params.target)确保幂等性高并发更新设置retry_on_conflict根据并发度设置3-5次重试避免客户端处理冲突使用upsert处理插入或更新一条请求同时处理文档可能不存在的情况避免Script中的非幂等操作不使用、-等相对运算除非有严格的业务保证监控版本冲突率如果conflict率持续高于5%考虑业务拆分或降低并发度上一篇【第45篇】Elasticsearch分布式检索原理——Query Then Fetch两阶段搜索下一篇【第47篇】Elasticsearch集群形成机制
