Elasticsearch 7.17.29 中如何迁移 terms 子聚合？

2026-11-06数据小陈

结论

移除 RestHighLevelClient 并改用 co.elastic.clients:elasticsearch-java 后，应使用 Aggregation 表达聚合，再通过 .aggregations(...) 添加子聚合。原代码中的 subAggregation(...) 属于旧版 High Level REST Client API；新客户端通过父级 Aggregation 添加子聚合。

改写示例

import co.elastic.clients.elasticsearch._types.aggregations.Aggregation;

Aggregation statusAgg = Aggregation.of(a -> a
    .terms(t -> t
        .field(STATUS_KEYWORD)
        .size(60)
    )
    .aggregations(SUM_QTY, sub -> sub
        .sum(sum -> sum.field(QTY))
    )
);

Aggregation feeCommReconAgg = Aggregation.of(a -> a
    .terms(t -> t
        .field(FEE_COMM_RECON_KEYWORD)
        .size(60)
    )
    .aggregations(SUM_QTY, sub -> sub
        .sum(sum -> sum.field(QTY))
    )
);

在 SearchRequest 中，使用 BY_STATUS 和 BY_FEE_COMM_RECON 作为顶层聚合名称：

SearchRequest request = SearchRequest.of(s -> s
    .aggregations(BY_STATUS, statusAgg)
    .aggregations(BY_FEE_COMM_RECON, feeCommReconAgg)
);

SUM_QTY 是子聚合名称。每个 terms 桶下都会有一个名为 SUM_QTY 的 sum 指标，汇总字段 QTY。BY_STATUS、STATUS_KEYWORD 等常量沿用项目中的定义即可。官方 7.17 Java API Client Javadoc 将 Aggregation.Builder.aggregations(...) 定义为 bucket aggregation 的子聚合入口，详见 Aggregation.Builder 文档。

检查客户端类型

如果代码仍从 org.elasticsearch.search.aggregations.* 导入 TermsAggregationBuilder 和 AggregationBuilders，使用的仍是旧版 REST High Level Client API。该 API 的 7.17 文档仍展示了 aggregation.subAggregation(...) 的用法，详见 7.17 Search API 文档。检查 import 和 Maven/Gradle 依赖，确认调用代码使用的是哪套客户端。新旧客户端的聚合类型不能直接混用。

注意事项

size(60) 仍表示 terms 聚合返回的桶数量上限。示例沿用了原有字段和聚合名称；如果 QTY 是数值字段，sum 才能按预期汇总数值。依赖版本应与项目实际使用的 Elasticsearch Java API Client 版本一致。