Elasticsearch upsert搭配乐观锁触发校验报错问题咨询

Elasticsearch 原生硬限制不允许 upsert（含doc_as_upsert=true场景）和基于if_seq_no+if_primary_term的乐观锁同时使用，这个规则写在UpdateRequest的校验逻辑中，没有配置项可以关闭。
这个限制的逻辑很明确：if_seq_no和if_primary_term是已存在文档的版本标记，仅对更新场景生效；而upsert的语义是“文档不存在则插入，存在则更新”，插入分支根本没有可对比的seq_no/primary_term值，两种分支的校验逻辑无法统一，ES直接从接口层拦截了这种歧义调用。

• 在开启withDocAsUpsert(true)的更新请求上直接叠加withIfSeqNo、withIfPrimaryTerm参数，直接触发了ES的请求校验规则，这是报错的直接原因
• 试图用单条请求同时覆盖“新建文档”和“带锁更新文档”两个逻辑，没有匹配ES的接口设计约束

不要尝试绕过ES的原生校验，拆分场景处理即可实现带乐观锁的upsert效果：

• 操作前先判断目标ID的文档是否存在
• 文档不存在时：开启docAsUpsert，不传递seq_no、primary_term参数，直接执行插入逻辑
• 文档存在时：关闭docAsUpsert，携带读取到的最新seq_no、primary_term参数执行乐观锁更新
• 捕获版本冲突异常，搭配有限次数的重试逻辑解决并发下的竞态问题

参考实现代码（基于Spring Data ElasticsearchTemplate）：

private UpdateResponse doAction(UUID esId, List<Comment> comments, dSeqNoPrimaryTerm seqPrimNo, String indexName) {
    Map<String, Object> params = new HashMap<>();
    params.put("comments", comments);
    IndexCoordinates index = IndexCoordinates.of(indexName);
    String docId = esId.toString();
    boolean docExists = elasticsearchTemplate.exists(docId, index);

    UpdateQuery.Builder builder = UpdateQuery
            .builder(docId)
            .withDocument(Document.from(params))
            .withRefresh(Refresh.True);

    if (docExists) {
        builder.withDocAsUpsert(false);
        // 注意seqPrimNo必须是本次请求前读取到的最新值，不能用历史缓存值
        if (seqPrimNo != null) {
            builder.withIfSeqNo((int) seqPrimNo.getSequenceNumber());
            builder.withIfPrimaryTerm((int) seqPrimNo.getPrimaryTerm());
        }
    } else {
        builder.withDocAsUpsert(true);
    }

    try {
        return elasticsearchTemplate.update(builder.build(), index);
    } catch (ElasticsearchStatusException e) {
        if (e.status() == RestStatus.CONFLICT) {
            // 此处添加有限次重试逻辑：重新拉取最新文档的seqNo、primaryTerm后再次调用
            throw new RuntimeException("文档版本冲突，操作失败", e);
        }
        throw e;
    }
}

补充说明：如果不想做两次请求判断存在性，也可以用脚本更新方式，在脚本中自定义业务版本字段的校验逻辑，绕开ES原生的seq_no校验限制，但脚本更新性能低于原生更新，高并发场景谨慎使用。重试逻辑必须设置最大次数阈值，避免无限重试导致服务压力过载。

内容的提问来源于stack exchange，提问作者Dan