企业官网建设流程全解析

1. 报表需求的真实体感：普通查询为什么扛不住

先说我遇到的实际场景。某个业务系统要出一张订单销售看板，表结构很简单：订单号、客户名称、商品类目、下单时间、金额、数量。一开始产品经理给的方案是“把明细全部查出来，丢到后端的框架里循环分组求和”。听起来没毛病，当时数据量也就几百万行。可等数据量爬到几千万级别，明细查询一次要拉几万条甚至几十万条记录，网络传输、内存分配、框架遍历全在拖后腿。最夸张的一次，接口平均耗时飙到三秒以上，还经常出现内存溢出。

这次经历让我下定决心把所有报表类查询全部改走 Elasticsearch（以下简称 ES）的聚合接口。普通 search 查询是“把符合条件的文档找出来返回给你”，聚合查询是“在文档之上做统计计算，只把结果返回给你”。前者适合捞明细、捞单条上下文，后者适合算总和、算均值、算分组排行这一类工况。报表场景几乎全是后者。

这篇内容就是在这次改造过程中沉淀下来的一个综合样例。我会从最基础的 terms 聚合讲起，逐步叠加求和、排序、合计行、分页、性能优化和踩坑反思，覆盖面比较广，适合正在用 ES 做运营报表、财务看板或数据大屏的开发者参考。就算你之前没用过聚合，照着后面的结构走一遍，也能拼出自己项目的报表接口。

2. 聚合的骨架：桶与指标如何组织一张报表

2.1 桶是横轴分组，指标是纵轴数值

ES 聚合里有两个核心概念，一个是桶（bucket），一个是指标（metric）。桶负责“按某个字段把数据分成若干堆”，比如按商品类目分桶、按客户分桶、按天分桶。每个桶里会包含一批文档，桶和桶之间互相独立。指标负责“对每个桶里的文档做数值计算”，比如求金额总和、求数量平均值、统计文档条数。

我习惯用二维表格来理解：桶决定这张报表有多少行，指标决定每一行里填什么数字。假如你要做一张“按商品类目统计订单总额”的报表，类目就是桶，订单总额就是指标。写出来的结构一定长这样：

{ "size": 0, "aggs": { "group_by_category": { "terms": { "field": "category.keyword", "size": 20 }, "aggs": { "total_amount": { "sum": { "field": "amount" } } } } } }

这里size: 0表示不返回明细文档，只返回聚合结果，这是报表接口的标准姿势。group_by_category是给这层聚合起的名字，完全自定义。terms在 category.keyword 字段上分组，默认只返回前 10 个桶，我写 20 是想让报表第一页出来 20 行。每个桶内部再挂一个total_amount，对桶内文档的 amount 字段求和。

明细里会看到buckets数组，每个桶都有 key、doc_count 和 total_amount 三个字段。doc_count是这个桶命中的文档数，对报表来说常常就是“有多少笔订单”，total_amount 则是这一类的销售额合计。

2.2 请求体里每个分块都在解决一个报表问题

我拆开讲一下上面这段 DSL 的每个分块，因为报表聚合本质上就是不断往这棵“聚合树”上挂新的分支：

• size: 0：正常搜索请求默认返回 10 条文档，报表不需要文档明细，置 0 省流量省内存。这个习惯必须养成。
• aggs：聚合树的入口，所有分组、指标都挂在下面。
• terms：最常用的分桶聚合。可以类比 SQL 的GROUP BY，但它有几个关键参数值得单独说，后面我会展开。
• sum：指标聚合的一种，对字段做求和。同类还有avg、max、min、cardinality（去重计数）、value_count（非空计数）。
• aggs嵌套：在terms下面再写一个aggs，就是在每个桶内继续做下一层分组或指标计算，聚合可以无限嵌套。比如先按类目分桶，再在类目桶里按日期分桶，就能得到“每个类目每一天的金额合计”，这在报表里非常常见。

嵌套逻辑是聚合最有威力的地方。要理解它，可以想象一棵倒挂的树：根是查询条件过滤后的全量文档，每套一层的聚合就是在上一层的每个桶里继续切分。最终报表的每一行数据，往往就是树梢某个节点上的指标值。

3. 从表达需求到可落地的聚合 DSL

3.1 分层分组的完整查询结构

业务方提了一个相对完整的报表需求：按商品类目分组统计近 30 天的销售额和订单量，按销售额降序排列，并且要能看到每个类目按天的走势。这个需求不仅包含单一分组，还涉及时间过滤、一层分组、一层子分组、多个指标、排序。

先过滤近 30 天的数据是必然的，这一步用query完成。需要注意，聚合里的桶是基于过滤后的文档来做统计的，所以 query 写在最外层，聚合只统计命中的那部分数据。对于报表系统来说，几乎每个请求都要带时间范围，这也是 ES 比传统数据库更适合做时间线分析的关键原因。

然后按类目分组，类目字段在 ES 里通常有 text 和 keyword 两种形态。做分组必须用 keyword 字段，因为 text 字段写入时会经过分词器切词，分组得到的是碎片化的词项，而不是完整的类目名。这是我们项目里踩过的一个高频坑：报表上类目少了几种，后来才发现拿 text 字段做分组了。遇到这种情况，要么建索引时给字段加fields: { keyword: { type: keyword } }的子字段，要么查询时直接用.keyword后缀。

求和与均值同时计算，只要在桶下挂多个指标聚合即可。每个指标都是一个并列的分支，互不干扰。最后在桶级别设置 order，让结果按指标值排序：

{ "size": 0, "query": { "bool": { "filter": [ { "range": { "order_date": { "gte": "now-30d/d", "lte": "now/d" } } } ] } }, "aggs": { "by_category": { "terms": { "field": "category.keyword", "size": 50, "order": { "total_sales": "desc" } }, "aggs": { "total_sales": { "sum": { "field": "amount" } }, "total_orders": { "value_count": { "field": "order_id" } }, "daily_trend": { "date_histogram": { "field": "order_date", "calendar_interval": "day", "format": "yyyy-MM-dd" } } } } } }

这里面有个小细节很关键：order排序依据写的是total_sales，这是子聚合的名称。也就是说，排序是基于聚合计算结果来排的，不是基于文档字段排序。daily_trend是每个类目桶下的第三层聚合，用 date_histogram 按天生成子桶，这样每个类目下就会有 30 个日期桶。报表前端拿到这个嵌套结构后，展开就能画折线图。

3.2 排序、合计与分页：别再试图用 from 和 size

报表业务问的“排序”通常分两类：一类是桶之间的排序，比如按销售额降序出前 10 个类目；另一类是桶内明细的 Top N，比如每个类目下金额最高的前 5 笔订单。前者用上面写的 order 就能解决，后者需要用terms加top_hits聚合。

top_hits是很有特色的聚合，它能从每个桶中抽取出最符合条件的若干条文档。每个类目桶里放一个 top_hits，按金额倒序取前 5 条，就得到了“类目分组 + 组内明细 Top N”的结构。这是 SQL 中窗口函数常用招式 ROW_NUMBER 分区排序的聚合版。

先看这段按类目分组、组内取金额前 3 条明细的写法：

{ "size": 0, "aggs": { "by_category": { "terms": { "field": "category.keyword", "size": 10 }, "aggs": { "top_orders": { "top_hits": { "size": 3, "_source": { "includes": ["order_id", "customer_name", "amount"] }, "sort": [ { "amount": { "order": "desc" } } ] } } } } } }

这样返回的每个类目桶里，会带着一个 top_orders 字段，里面是该类目金额前三的订单明细。报表后端可以把这个结构直接序列化给前端，省去二次查询。

分页是报表里最容易被误导的地方。ES 搜索请求里的from和size只能对文档列表生效，对聚合桶数量完全无效。你写了"from": 20，期望跳过前 20 个类目桶，实际 ES 根本不会让你对聚合结果做偏移。网络上很多说法说“聚合分页用 bucket_sort”，这是不完全准确的。要理解 bucket_sort 的真实定位：它并不是做深分页，而是做桶级别的截取和排序。

用 bucket_sort 完成 Top N 分页，需要把排序放进管道聚合里，套在一个普通桶外。管道聚合的意思是它不直接计算文档字段，而是对已有桶的聚合结果再做操作。这样可以按上一个聚合的指标值排序，再保留前多少个桶。简单说，它做到的是“取前 20 个桶”这一页，而不是“跳到第 20 个桶之后”的翻页。

{ "size": 0, "aggs": { "temp_by_category": { "terms": { "field": "category.keyword", "size": 1000 }, "aggs": { "total_sales": { "sum": { "field": "amount" } }, "page": { "bucket_sort": { "sort": [ { "total_sales": { "order": "desc" } } ], "from": 0, "size": 20 } } } } } }

注意这里有几个陷阱。terms的 size 不是最终结果数量，而是候选桶数量。为了最终取到第 20 名之后的桶，你必须先把桶多取一些，再靠 bucket_sort 截取。比如报表每页 20 行，想看第 3 页，那就要让 terms 至少收集 60 个桶，然后 bucket_sort 设置"from": 40, "size": 20。但如果数据量大、类目多，terms 直接把 size 设成上万是极伤性能的做法。所以最稳妥的方案是“足够用的 size + bucket_sort”，而不是无脑放大 size。

还有一点，如果业务真的需要从第 1000 页往后翻，就不该用 terms 了。ES 提供了composite聚合来支持真正的深分页，它与 terms 最大的不同是，它把分页游标切进机制里，每次请求只需携带上一次返回的 after_key，就能稳定地拿到下一批桶，无需在内存里保留全量候选桶。代价是复合聚合无法直接排序，它的桶顺序由分组字段决定。所以采用这种方案时，报表的分页逻辑通常是：先按复合聚合遍历分组，拿到每个组的相关指标数据后，指标排序再由后端处理。

3.3 合计行的三种常见实现方案

报表底部通常要有一行总计，比如所有类目的总销售额、总订单量、总客户数。搞清每种方案的场景，才能根据自己报表的数据量和坑位选择合理的实现。

第一种方案最简单，直接再加一个全局聚合。全局聚合global会忽略所有查询条件，在所有文档上做统计。但这种方案适合报表的“全局是全部数据”，而很多报表实际只是过滤后的汇总，所以这里用过滤聚合更贴合。过滤聚合可以带一个和主查询完全一致的条件，让合计与分组统计看到同一份数据。这段写法类似filter聚合套 sum，核心是保证合计口径与明细口径一致。

第二种方案不做额外查询，而是把现有查询返回的桶结果在应用层累加。这个方案优点是不增加 ES 的压力，但缺点也很明显：当使用terms聚合设置size只取前 20 个桶时，应用层拿到的是截断后的桶，累加出的总和少了后面那些类目的销售额，合计算出来是错的。想用这种方案，前提是terms聚合把size设得足够大，覆盖所有类目，但这又和性能相矛盾。所以它只适合类目数量可控、不超过几百个的场景。

第三种方案是直接在原有查询上增加子聚合完成合计。这个方案对我来说是最优解，既不会增加应用层计算，又保证了聚合引擎里的准确度。要实现它，需要在根级aggs增加一个名为total_summary的sum聚合。它作用于“经过 query 过滤后的全部文档”，等价于所有分组的总体合计。我一般会在三个位置各放一个：最外层的总聚合、分组聚合下的指标、额外一个全局汇总：

{ "size": 0, "query": { "bool": { "filter": [{ "term": { "status": "paid" } }] } }, "aggs": { "total_sales_all": { "sum": { "field": "amount" } }, "total_orders_all": { "value_count": { "field": "order_id" } }, "by_category": { "terms": { "field": "category.keyword", "size": 20, "order": { "total_sales": "desc" } }, "aggs": { "total_sales": { "sum": { "field": "amount" } }, "total_orders": { "value_count": { "field": "order_id" } } } } } }

这里total_sales_all与total_orders_all就是报表最底部的合计行数据，它的统计范围是经过 status 过滤后的全部订单，与分组查询共用了同一个命中文档集。注意此时的“合计”是查询条件下的合计，而不是全表合计，所以和业务方沟通口径时要明确这一点。

3.4 报表接口返回结构长什么样，前端怎么消费

聚合结果的结构是一棵嵌套的 JSON 树。拿前面的例子来说，顶层会有aggregations字段，里面是total_sales_all、total_orders_all、by_category。by_category内部有buckets数组，每个元素包含 category 名称、doc_count、total_sales、total_orders，如果想继续向下钻取，还会有 daily_trend 之类的嵌套桶。

我的团队在前端对接时约定了一个通用格式：总合计算计放在 aggregates 顶层，分组列表统一放 rows，前端拿到的数据模型直接对应表格的行列。为此后端需要对返回的 JSON 做一次轻量的“拍平”。值得注意的是，ES 字段中的 doc_count 和 sum 值都可能是浮点或 long 类型，前端展示前最好统一转换成保留小数位的字符串，防止精度显示问题。

这个“拍平”工作并不需要复杂工具，Java 侧用普通 ArrayList 和 HashMap 组装即可。ES 返回的嵌套结构大多数时候我们只需要保留两层：一层表示分组信息，一层表示指标信息。报表类接口的核心是“要快、要稳、字段别对不上”，不要在前端逻辑里放太多 STL 式深层解析。

4. 报表数据质量与性能平衡的几个核心点

4.1 size 与 shard_size：桶统计误差到底是怎么来的

使用terms做报表分组时，很多人误以为每个分片都会把所有桶都统计完整再合并，实际上并不是这样。ES 在每个分片上会独立计算聚合，然后合并结果。为了控制内存和响应时间，每个分片只返回桶的“提交数量”给协调节点。这个数量由shard_size控制，默认值约等于size * 1.5 + 10。

问题就出在这里：如果一个分片上有你需要的桶，但它在该分片的排名不够靠前，它就会被裁剪掉，最终合并后你的报表就少了某个分组，或者某个分组的数值偏小。这恰恰是我们之前遇到的“聚合结果怎么少了几条数据”的根本原因。

解决办法有几个层级：

• 把shard_size调大，比如size是 20 时，shard_size设为 200 或更大。
• 使用composite聚合，因为它的遍历是精准的，不会出现分片提前截断。
• 使用search_type: query_then_fetch加pre_filter_shard_size调优（8.0 以后的版本已有相关优化）。
• 报表数据对准确性要求极高时，可以把size直接设成一个接近分组总量的值，但这只适合分组基数小的场景。

我见过不少系统直接把shard_size设为 10 万来换取准确性，但内存开销也随之拉满。更合理的做法是，在数据写入时增加一层字段预汇总，让聚合的数据量大幅降低。这也是很多 BI 系统采用的做法。

4.2 min_doc_count 要理解，别让它吃掉报表行

terms 聚合返回的是文档中实际出现的词项桶。如果某个类目只有一笔订单，它的 doc_count 只有 1，这没问题。但是日期类分组里，data_histogram 默认只生成有文档的日期桶，没有订单的日期就完全不会出现在结果中。这会让前端折线图出现断点。

解决方法是给 date_histogram 加上min_doc_count: 0，这样即使某天没有订单，也能生成该日期桶。很多报表只想看“有数据的日期”，这时默认值的断点行为反而合适；但想画连续曲线的人，容易在这里被坑一下。我自己在使用时会把min_doc_count: 0和extended_bounds一起使用，确保返回的时间桶范围严格对齐业务期望，不至于因数据稀疏而在图表上缺段。

4.3 用 doc-values 与索引建模来支撑快报表

ES 聚合快不快，很大程度上取决于字段是否开启了 doc_values。doc_values 是列式存储，适合排序和聚合；text 类型的字段默认没有 doc_values，keyword 数字类型默认开启。报表字段如果用了动态模板，可能字段映射到了 text，聚合时 ES 只能现场解析，性能直接崩掉。所以建索引时，对需要聚合的字段明确声明类型，不让映射被自动推断“脏”了：

{ "mappings": { "properties": { "order_date": { "type": "date" }, "amount": { "type": "double" }, "category": { "type": "text", "fields": { "keyword": { "type": "keyword", "ignore_above": 64 } } }, "order_id": { "type": "keyword" } } } }

ignore_above也很重要。超过 64 个字符的类目名不会写入 keyword，避免内存里的 term 字典膨胀。报表字段越“瘦”，聚合速度越快。这里建议：所有参与聚合的 keyword 字段都设置ignore_above，所有参与聚合的数值字段都避免使用text映射；建立索引模版后，即使后续新增报表字段，也自动套用这套规则。

4.4 宽表与窄表：报表专用索引长什么样

如果业务系统里既有明细查询，又有大量报表聚合，建议直接为报表模块单独建立一张宽表索引。比如订单明细根本没有必要把“客户地址、商品详情、优惠券信息”全部塞进报表索引里，它只需要业务方报表看的字段：订单号、类目、商品名、日期、金额、状态。宽表索引通过生产环境同步数据，去掉不必要的 join 和字段，聚合查询负担会小很多。

我们项目里把宽表索引的副本数量设成 0，只保留主分片，报表查询直接读主分片，省去副本同步的网络开销。因为有固定的“昨日全量 + 今日增量”更新机制，数据重建很快，不需要担心副本丢失的问题。这种方式带来的收益非常明显，同样的聚合查询，在宽表索引上耗时只有明细表的三分之一左右。

5. 报表聚合的实操踩坑与排查思路

5.1 明明有 200 个类目，聚合结果只剩 10 个

某个报表上线后运营同学反馈：后台明明能看到 200 多个类目，但报表里只有 10 个类目。所有人第一反应都是“数据没传完”，排查完日记流水后秒打脸，数据都是全的。

其实 ES 的 terms 聚合默认 size 就是 10。不写 size，它只会返回 group by 之后的前 10 个桶。解决很简单：按报表行数设置 size，并配套合理的 shard_size。但更值得留意的是，如果业务方说“我要所有类目的合计”，此时你要狠心拒绝“全给你”的做法：先确认业务方是否需要看到完整的几百行，如果只需要 Top N 和合计，就把 size 调小，用全局合计承担总数，才不会有性能隐患。

5.2 聚合结果里的 doc_count 明显小于明细查询命中数

这种情况通常是因为 query 过滤条件只设置在主查询，没有同步设置到聚合，或者是 shard-size 截断导致丢桶。如果只关注总命中量，收敛 query 必现少数据。更好的排查方法是：打开profile: true观察聚合阶段耗时和桶数变化，并用_count接口核对过滤后的文档总数，比对聚合里的全局指标值。

如果确认指标总和不一致，可能就是有文档里金额字段的值是 null。sum 只统计非 null 值，value_count 统计所有非 null 的文档。对于空值，可以给字段设定null_value，或者在聚合前加 filter 判断字段存在。这三种写的属性很容易被忽略，但报表数字总是对不上，八成是这里。

5.3 报表查询内存开销大、节点 GC 频繁

聚合本身吃内存，最典型的场景是“对高基数字段做 terms 聚合”。客户名称、订单号、user_id 这类字段值成百上千万，直接 terms 分桶会占据大量堆内存。遇到必须对高基数分组的场景，我采用两条策略：

• 先做前置过滤，让分桶基数从“千万”缩小到“几千”。比如先按时间过滤近期数据，再按维度分桶，除非业务要求全量历史分桶。
• 用sampler聚合抽样统计，适合对准确度要求不高的预估报表。抽样后需要再套一层significant_terms或普通指标聚合，预估整体走势。
• 如果这一类报表很多，考虑提前做“预聚合”：写入时就把类目、日期、金额汇总成一条数据，报表接口直接对预统计索引做轻量聚合，速度会有一个量级提升。

在写聚合 DSL 时不要忘记一个细节：无论是否显式声明，ES 聚合默认都会对_source做相关处理。需要返回文档的 top_hits 才必须带_source；纯指标聚合不要设置"size": 10这种未过滤的返回，既有文档明细又包含聚合，会成倍放大返回体的体积。我一般直接把size置 0，让响应体只带aggregations。

5.4 报表接口的缓存策略和滚动翻页实践

报表数据往往有固定时间段缓存需求。ES 本身支持request_cache: true，但只对size: 0的查询生效，这正好契合我们的聚合报表查询。开启请求缓存后，相同 DSL 在缓存过期时间内的第二次查询会直接走缓存，耗时可以从几十毫秒降到几毫秒。不过要注意，请求缓存是分片级的，有新增文档写入的情况下，部分缓存可能会失效。

深翻页方面我再来一个总结：报表分页不像列表那么频繁，普通报表用 bucket_sort 截取 Top N 完全够用。如果要访问后面的页次，可以这么想：不必每次都从第一页聚合起，用 composite 的 after_key 直接携带上次位置，翻页逻辑就从“跳过大几十个桶”变成了“从上一次最后一个分组往后继续”。这个方案对类目和 SKU 这种中低基数分组尤其稳定，几乎没有内存峰值风险。

我自己的经验是：报表接口不要直接拿 open source 的前端表格组件默认行为去翻 ES 的聚合结果。设计接口时明确“报表分页页容量上限”，通常 50 到 100 行一页已经非常够用。超过这个上限，建议直接要求业务方缩小时间范围或增加筛选条件，而不是硬翻几千行分组。这样既省 ES 内存，也降低了产品侧对性能的困惑。

最后说一个无关技术但很有用的经验：报表需求确认时，一定要和业务方把“合计行口径”对齐。口径不一样，你聚合写得再正确，业务方也照样说报表是坏的。而只要这次把分桶、指标、排序、合计、分页这套 DSL 结构吃透了，剩下的无非是往“聚合树”上继续挂节点的问题。