很多刚开始接触 Calcite 源码的人，看到AggregateStarTableRule这类类名时，第一反应往往是"哦，又一个看不懂的优化规则"。但实际上，如果你搞懂了这条规则，基本就摸清了 Calcite 物化视图匹配和星型模型加速的底层玩法。这个规则藏在org.apache.calcite.plan包附近，平时用 Calcite 做数仓、BI 查询加速的同学，都会在高并发报表调优时碰到它。本文就带着大家从头梳理：它到底解决什么问题、匹配逻辑怎么写、命中后如何改写 RelNode 树，以及在真实接入时需要注意哪些细节。
1. AggregateStarTableRule 在优化器里的角色：它到底在撮合什么
1.1 从一个查询优化问题说起
假设你有一张销售事实表sales(store_id, product_id, amount)，一张门店维度表store(store_id, region, city)，一张商品维度表product(product_id, category)。业务上经常想按region和category分组看销售额，于是 SQL 大概是：
SELECT s.region, p.category, SUM(s.amount) FROM sales s JOIN store st ON s.store_id = st.store_id JOIN product p ON s.product_id = p.product_id GROUP BY s.region, p.category;如果数据量很大，GROUP BY加多张大表关联，在 Parser 生成的逻辑计划阶段往往是一棵深树。Calcite 的优化器（HepPlanner或VolcanoPlanner）会应用一堆规则去改变这棵树：先下推过滤、再结合投影裁剪、再尝试把Aggregate下推到某个子查询里。
但问题来了：如果事先在离线层把sales、store、product三张表按region、category维度加总好，形成一张预聚合的汇总表（也叫汇总表、物化视图或 StarTable 的聚合节点），那么这条 SQL 是不是可以直接查这张汇总表，而不用现场去GROUP BY几亿行数据？
AggregateStarTableRule干的就是这件事：它尝试识别查询里的Aggregate是否恰好匹配一个已经构建好的星型表中的聚合节点，如果匹配，就把这次昂贵的聚合计算替换成直接读取预先计算好的结果。换句话说，它是 Calcite 里"查询改写命中物化视图"的核心规则之一。
1.2 StarTable 和 Lattice 的关系
继续往深处挖，AggregateStarTableRule涉及的核心概念是StarTable。StarTable是 Calcite 中Lattice（多维数据立方体格）的产物。Lattice 描述了一张事实表与若干维度表之间的外键关系，像雪花形状一样展开。Calcite 可以通过 Lattice 感知表之间的关联关系，并基于这个 "星型结构" 生成"虚拟表"：StarTable。
StarTable内部往往维护了几个Table节点，例如事实表和维度表的扫描节点。而针对这个 StarTable 的查询，如果在某组维度（分组列）上做了聚合，并且有对应的物化视图/汇总表，Calcite 就把这个查询翻译成直接访问更小粒度的汇总表。AggregateStarTableRule就是负责"识别并验证"这种查询模式的关键规则。
可以这么理解：StarTable 是维度建模在优化器里的抽象，AggregateStarTableRule是把抽象查询落到物理预聚合结果的桥梁。
2. 规则源码切入：匹配模式、校验条件与核心调度点
很多人在看 Calcite 规则源码的时候，总觉得matches和onMatch很虚，不太清楚每个方法的调用时机。我直接用源码层面来拆解。
2.1 类结构概览
AggregateStarTableRule在 Calcite 中的定义大致长这样（不同版本略有差异，核心逻辑不变）：
public class AggregateStarTableRule extends RelOptRule { public static final AggregateStarTableRule INSTANCE = new AggregateStarTableRule(operand(Aggregate.class, operand(Project.class, operand(RelOptTableScan.class, none()))), "AggregateStarTableRule"); public AggregateStarTableRule(RelOptRuleOperand operand, String description) { super(operand, description); } @Override public boolean matches(RelOptRuleCall call) { // 输出匹配条件 } @Override public void onMatch(RelOptRuleCall call) { // 核心处理 } }注意这里有个陷阱：很多同学以为这个规则的匹配模式只有Aggregate -> Project -> TableScan，但实际它的operand写法在不同 Calcite 版本里可能不一样，有的版本还会包一层Filter。所以复现时最好先打开自己使用的 Calcite 版本的源码确认一下。
2.2 matches 阶段到底校验了什么
规则触发后，matches方法先做快速过滤。主要做三件事：
- 检查最底层的
TableScan对应的表是否是StarTable。 - 检查
Project（如果有）是否是简单的映射/别名，不包含复杂的表达式。 - 检查
Aggregate的分组列是否匹配目标StarTable中的可用维度组合。
这就像去店里买套餐：matches是"看这个订单是不是选中了套餐"，如果菜品结构完全不是套餐，就直接返回 false，不会进入后续复杂的匹配逻辑，节省优化器的时间。
以下是一段示意代码，帮助理解：
@Override public boolean matches(RelOptRuleCall call) { final Aggregate aggregate = call.rel(0); final Project project = call.rel(1); final RelOptTableScan scan = call.rel(2); final RelOptTable table = scan.getTable(); if (!(table.unwrap(StarTable.class) instanceof StarTable)) { return false; } final StarTable starTable = table.unwrap(StarTable.class); // 检查 aggregate 的分组列是否在 starTable 中已定义 return starTable.isValidAggregate(aggregate); }（这不是全量源码，核心是表达思路。）实际源码里还要求aggregate.getGroupSet()不能为空，而且aggregate的 agg 调用必须是可在预聚合中计算的。另外，如果分组列和度量的组合要求无法从StarTable的某个预聚合结果中得到，matches也会返回 false。
2.3 onMatch 阶段：改写规则的两条路径
一旦matches通过，onMatch会做最终的重写。这里有一个很重要的分支：这张StarTable后面对应的是原始的星型结构（即直接扫原始表），还是对应到已经物化的表？
StarTable里通常会有若干个RelNode候选，每个候选对应一组"预聚合结果"。常见的有两种情况：
- 如果查询的
GROUP BY列正好命中预聚合结果的分组维度，那么直接把Aggregate替换成对预聚合表的扫描。 - 如果查询比预聚合结果的粒度更粗（例如：预聚合结果按
region, category分组，查询想按region分组），那么仍可以基于预聚合结果再做一次聚合，即"从粗粒度结果进一步聚合"。
onMatch里的逻辑大致如下：
@Override public void onMatch(RelOptRuleCall call) { final Aggregate aggregate = call.rel(0); final Project project = call.rel(1); final RelOptTableScan scan = call.rel(2); final StarTable starTable = scan.getTable().unwrap(StarTable.class); final RelOptTable starRelOptTable = starTable.toRel(context -> ...); final RelNode substituted = starRelOptTable.toRel(scan.getCluster()); // 可能还需要换算列映射、应用 aggregate 到 substituted RelNode newAgg = aggregate.copy(aggregate.getTraitSet(), substitute(...)); call.transformTo(newAgg); }这里有两个实现细节值得关注：
- 列映射：
StarTable内部维护了从原始查询列到预聚合表列的映射。在改写时，RexBuilder通过RexInputRef将新旧节点连起来，把原先分组列的下标换算成新表的下标。这一步很容易出错，一不留神就会导致字段错位。 - 聚合函数的可下推性：不是所有聚合函数都能从预聚合结果再次聚合得到，例如
COUNT(DISTINCT x)在低层预聚合时如果没精确去重，上层就不能随意复用结果。onMatch内部会检查aggregate调用中的 AggCall 是否被starTable支持，否则放弃改写。
2.4 触发时机：HepPlanner 和 VolcanoPlanner 的差异
AggregateStarTableRule既可以被注册到HepPlanner（启发式优化器），也可以注册到VolcanoPlanner（基于代价的优化器）。但实际生产中，绝大多数用于 Lattice 物化视图匹配的工程实现，会把它放到HepPlanner里跑，并且严格按照"先 expand star table，再 aggregate replace"的顺序。
原因很简单：VolcanoPlanner 需要计算代价，而 StarTable 匹配是逻辑改写，并不需要物理属性。如果塞进 Volcano，可能会被其他规则反复触发，导致优化过程不可控。所以当你准备在自己的项目里引入这套机制时，建议用HepProgramBuilder明确指定规则顺序：
HepProgramBuilder builder = new HepProgramBuilder(); builder.addRuleInstance(AggregateStarTableRule.INSTANCE); // 其他规则... HepPlanner planner = new HepPlanner(builder.build());这里还有个小技巧：先创建一个Lattice，调用addStarTable，再注册这个规则，才能让 Calcite 知道这个星型结构。
3. 规则的实际驱动场景：Lattice 物化视图如何与 AggregateStarTableRule 协同
3.1 搭建一个 StarTable 需要什么
在真实项目里，你不大可能直接 newStarTable，而是先定义Lattice。看一段典型代码：
LatticeRootNode rootNode = new LatticeRootNode(factTable); rootNode.addChild(ArrayTable.create(...), "store", "store_id", "store_id"); rootNode.addChild(ArrayTable.create(...), "product", "product_id", "product_id"); Lattice lattice = new Lattice.Builder(rootNode) .addMeasure("sum_amount", "sales", "amount", "SUM") .addMeasure("count_sales", "sales", "sales_id", "COUNT") .build();Lattice构建好之后，可以借助CalciteSchema的add("star", starTable)把StarTable放到 schema 中。此后用户如果执行一个"从 star 表查询 + 分组"的 SQL，优化器就会看到这个StarTable，并尝试用AggregateStarTableRule改写。
这里有一点特别容易混淆：Lattice里的StarTable并不是一张真实存在的物理表，它更像一个"虚拟 SQL 模子"。真正可以被查询改写命中的，是StarTable中挂载的若干物化视图/汇总表（Calcite 中表现为RelOptMaterialization或PolymorphicTable）。AggregateStarTableRule负责判定"这个 SQL 的聚合是否碰巧和某个物化视图生成的聚合结果一致"。如果一致，就把它替换成物化视图的表扫描。
3.2 从原始查询到预聚合表：一个完整映射过程
说一个我在实际项目里跑通过的最小示例。假设我创建了sales_star这个 StarTable，其中有三个可用的聚合节点：
| 节点编号 | 维度组合 | 度量 |
|---|---|---|
| A | (region, category) | sum(amount) |
| B | (region) | sum(amount) |
| C | (store_id, product_id) | sum(amount) |
当用户查询SELECT region, category, SUM(amount) FROM sales_star GROUP BY region, category时，AggregateStarTableRule看到分组列恰好是(region, category)，就直接将原先的Aggregate节点替换为对A对应物理表的扫描。
如果用户查询SELECT region, SUM(amount) FROM sales_star GROUP BY region，理论上可以用 B 直接命中。但如果我只物化了 A（更细粒度），那么AggregateStarTableRule会怎么处理？它不会直接使用 A，而会尝试在 A 的结果上再做一次GROUP BY region的聚合，即"二次聚合"。这种情况下，生成的计划是：Aggregate(region) <- Aggregate(region, category) <- TableScan(A)。不过，这个二次聚合是否能自动生成，取决于 Calcite 内部实现版本以及是否配置了aggregate的AggCall可重复聚合（例如SUM是可重复聚合的，AVG有时必须改为SUM/COUNT）。
3.3 为什么说这条规则是物化视图匹配的"安全门"
物化视图改写最怕什么？怕"基于不正确的预聚合数据得到错误结果"。比如物化视图里已经按region过滤了一部分数据，但查询需要全量region数据，一旦错误匹配就会出错。AggregateStarTableRule至少做了三层防御：
- 最底层判断：只有
StarTable上的扫描才能匹配，不要试图去匹配任意普通表。 - 分组列验证：
Aggregate的分组列集合必须是StarTable所定义的某条维度路径的超集或子集；完全无关的分组列会被拒绝。 - 聚合函数验证：相关 AggCall 必须能在预聚合上通过"上卷"算子得到，比如
SUM可以，COUNT可以，AVG需要转换，COUNT(DISTINCT)默认不可直接上卷。
正是这些防御，让AggregateStarTableRule在 Calcite 优化器里扮演着"物化视图安全门"的角色。理解这一点之后，你在排查"为什么我的物化视图没生效"时，就会先去检查这三点，而不是一上来就怀疑规则没注册。
4. 手写复现：一个最小可运行的 AggregateStarTableRule 示例
既然我们要深入理解，就不能只看源码，得动手搭一个能跑起来的最小环境。这里我用一个简化示例，展示如何在项目里注册规则并触发改写。
4.1 依赖与模型定义
假设你已经在 pom.xml 里引入了org.apache.calcite:calcite-core和org.apache.calcite:calcite-lattice（部分版本把 Lattice 移到 core 或单独的模块里，请注意版本对应关系）。然后定义 Schema：
SchemaPlus rootSchema = Frameworks.createRootSchema(true); // 创建事实表和维度表 rootSchema.add("sales", new AbstractTable() { @Override public RelDataType getRowType(RelDataTypeFactory typeFactory) { return typeFactory.builder() .add("store_id", SqlTypeName.INTEGER) .add("product_id", SqlTypeName.INTEGER) .add("amount", SqlTypeName.DECIMAL) .build(); } }); // ... 其他表接着创建 Lattice，并把 StarTable 注册为star_sales。这个过程会涉及一些内部 API，实际项目中建议封装成工具类。
4.2 配置优化器并触发规则
为了验证，我们可以直接构造一个逻辑计划，或者用 SQL 解析生成：
FrameworkConfig config = Frameworks.newConfigBuilder() .defaultSchema(rootSchema) .build(); Planner planner = Frameworks.getPlanner(config); // 假设 SQL： select region, category, sum(amount) from star_sales group by region, category但注意：很多版本的 Calcite 并不会自动加载 Lattice 相关的规则，需要在Planner的Program中显式注册AggregateStarTableRule.INSTANCE。例如：
Program program = Programs.of(RuleSet.of( AggregateStarTableRule.INSTANCE, // 其他需要的规则如 FilterProjectTransposeRule 等 ));然后在优化时调用program.run(...)。如果看到RelNode的逻辑计划从原来的Aggregate+TableScan(sales)变成了TableScan(aggregated_table)，就说明规则成功执行了。
4.3 常见不生效原因对照表
我把平时排查过的问题整理成一张表，供参考：
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 规则没触发 | StarTable 未正确注册到 Schema | 检查 Lattice 的addStarTable和 Schema Path |
| 规则触发了，但转换后报列错误 | 列映射未处理 | 检查 StarTable 的 column mapping 实现 |
| 分组列对不上 | 查询分组列与物化结果维度不一致 | 确保 Lattice 中 measure 和维度定义覆盖查询列 |
| 聚合结果偏大/未下推 | AggCall 无法上卷 | 确认物化表中保存的是SUM/COUNT，必要时改查询为SUM(amount)而不是AVG(amount) |
| 匹配了但代价反而高 | 物化表行数仍很大 | 增加预聚合结果的粒度，或者考虑让规则仅在低基数字段命中 |
这些坑我都实际踩过，特别是第一类：StarTable注册好但没有设置Lattice，导致AggregateStarTableRule的matches永远进不去。
5. 工程实战中的改造与调优心得体会
光看源码、跑 Demo 还不够，真正在业务里要稳定使用，还需要根据数据特点做一些定制。
5.1 自定义聚合规则，处理复杂维度层级
AggregateStarTableRule默认只处理简单的SUM/COUNT上卷。如果你的业务里有大量AVG、PERCENTILE等复杂聚合，建议不要直接改这条规则，那样容易破坏 Calcite 内部的匹配语义。更稳妥的方式是实现一个自定义的RelOptRule，参考它的matches/onMatch写法，把AggCall转换成内部可恢复的表示。比如对AVG，可以先在预聚合层保存SUM和COUNT，再在规则里把AVG展开为SUM / COUNT：
if (aggCall.getAggregation() == SqlStdOperatorTable.AVG) { // 创建 sum + count 重新组合 }这类似 Calcite 中已有的AggregateExpandDistinctAggregatesRule的做法，但使用场景不同。这里要强调的是，重写AggCall之后，一定要重新检查新生成的Aggregate的分组列顺序，否则下游优化器会拿到不一致的RexInputRef。
5.2 在规则前先做投影和过滤的规范化
AggregateStarTableRule的匹配条件相对严格，通常会限制Project是简单的RexInputRef列表。如果查询里有大量表达式，例如SELECT region || '-' || category, SUM(amount) ...，那么在调用AggregateStarTableRule之前，最好先跑ProjectToWindowRule、ReduceExpressionsRule或者FilterProjectTransposeRule，把投影规范化后再交给这个规则。
我见过一个线上案例：一条 SQL 明明可以用物化表，但因为查询里把store_id包装成了CAST(store_id AS BIGINT)，导致Project不满足规则要求，物化匹配始终失败。后来通过在 Program 里增加一个"投影简化"规则解决了问题。
这个案例说明，使用AggregateStarTableRule不是孤军奋战，它需要和其他规则形成组合。建议的调用顺序是：
- 先将
Filter下推，Project裁剪。 - 简化表达式。
- 再应用
AggregateStarTableRule。 - 最后再做列裁剪和物理优化。
5.3 注意版本差异，升级时一定要回归
Calcite 社区的迭代不算慢，AggregateStarTableRule在 1.20 版本前后有过行为调整。比如早期版本要求Aggregate的 groupSet 必须完全等于 StarTable 的维度集合，后来放宽为可以是 StarTable 维度集合的子集（允许更高层聚合）。这些变化直接决定了你的物化表是否命中。
我的建议是：在升级 Calcite 版本时，专门为物化视图改写场景写一组集成测试。每次升级至少跑一遍以下三类 SQL：
- 分组列与物化表完全一致。
- 分组列比物化表维度更粗。
- 分组列与物化表维度顺序不同，但语义相同。
通过这三类用例，基本能覆盖AggregateStarTableRule的核心匹配逻辑，防止升级带来的隐性行为变化。
5.4 与成本模型的取舍
最后说一点更深层的体会。AggregateStarTableRule是逻辑改写规则，执行后并不保证物理执行计划一定变快。例如，物化表的维度组合与查询的分组列维度很接近，但是物化表本身数据量仍然很大，并且物化表没有针对分组列的索引或排序，那么直接扫描原始事实表，利用列存和谓词下推可能更快。
VolcanoPlanner 下，这个规则产出的新节点会和原始节点一起参与代价计算，最终选最优；但如果是 HepPlanner 场景，你需要非常小心，因为一旦调用transformTo，它可能会立即替换掉原来的节点，没有代价比较。所以，如果你的查询模式比较复杂，建议在 Hep 阶段先不急于做 StarTable 替换，而是用AbstractConverter或自定义代价函数控制。
我在生产环境中的做法是：将AggregateStarTableRule注册到 VolcanoPlanner，并给预聚合表设置准确的rowCount和cpu代价，这样优化器才能做出正确取舍。如果拿不到统计信息，宁可不启用这条规则，也不要盲目匹配。
写在最后
AggregateStarTableRule是 Calcite 优化器里把"维度建模"和"逻辑改写"连接起来的关键节点。它看似只是一个小规则，背后却牵扯到 Lattice、StarTable、物化视图、聚合上卷等多个机制。如果你正在做基于 Calcite 的查询加速引擎，我强烈建议你从Lattice开始，逐步把事实表、维度表、预聚合表串起来，再回头阅读这个规则的源码，你会发现很多之前觉得晦涩的接口突然就通了。
我个人在实际项目里体会最深的一点是：规则代码本身不难，难的是配套的元数据管理和代价校准。先把维度层级定义清楚，把预聚合表的统计信息喂准，AggregateStarTableRule才能真正发挥出它"一个规则盘活一座星型模型"的价值。如果你只是浅尝辄止跑个 Demo，可能会觉得它没什么用；但如果你把它放进一个真实的高并发报表系统里，并被它优化过几次"秒级出结果"的查询，你一定会忍不住吹爆它。
