Spring Boot 3集成Apache Calcite实现多数据源联邦查询实战

多数据源查询这个坑，做后端的人基本都踩过。早期系统小，一个库走天下，后来业务一拆，订单在 MySQL、用户走 PostgreSQL、日志进了 ClickHouse，报表要同时捞三边数据，应用层就得写一堆循环调用、内存拼接的脏代码。我最早也用过 MyBatis 多数据源路由，后来试过 ShardingSphere，最后真正把问题解决掉的，是 Spring Boot 3 里集成 Apache Calcite，把多个异构数据源统一成一张逻辑表来查。这篇文章就把我落地这套方案的完整思路、源码级拆解和实操过程分享出来，给同样被多源查询折磨的人一个可以直接抄作业的参考。

先交代一下背景：我这边是一个中型电商后台，核心库是 MySQL，订单、商品、库存都在里面，但用户行为分析在 ClickHouse，一些供应链数据在 PostgreSQL，业务方经常要按订单维度关联用户行为和供应链状态出报表。以前的做法是应用层分段查询再合并，SQL 写不出来，索引优化也无从谈起，还容易因为跨服务调用导致接口超时。后来我决定用 Apache Calcite 做联邦查询层，对外暴露统一的 SQL 查询能力，对内通过 Calcite 的 Schema/Table 机制把 MySQL、ClickHouse、PostgreSQL 全部映射成标准表，让业务方直接写跨库 JOIN。这套方案跑通后，接口响应时间从原来最差 8 秒优化到平均 300 毫秒以内，代码量减少了一大半。

适合看这篇文章的人，是那些已经熟练使用 Spring Boot、开始接触多数据源聚合查询、但对 Calcite 还停留在“听说过”阶段的开发者。接下来我会从方案选型逻辑讲起，逐步深入到 Calcite 的 Schema 抽象、Table 接口实现、JDBC 适配写法，再结合 Spring Boot 3 的实际工程代码，完整演示如何把 Calcite 跑起来，最后附上源码阅读路径和常见坑位排查。

1. 为什么多数据源查询最终选了 Calcite：方案对比与决策逻辑

1.1 多数据源查询常见的三个真实困境

先别急着聊 Calcite 有多好，我先把多源查询的真实痛点列清楚。第一个困境是“单库 SQL 写不了关联”。当业务数据被拆到不同数据库后，JOIN 这个最基础的能力就没了，哪怕 MySQL 和 PostgreSQL 就在同一台机器上，也不可能在一条 SQL 里直接完成两个库的关联，只能靠应用层把 A 库数据查出后，再拿结果集去 B 库查，也就是 N+1 循环累加。

第二个困境是“数据格式不统一”。不同数据库的字段类型、命名规范、时间格式完全可能不一样。MySQL 里叫 create_time，ClickHouse 里叫 created_at，PostgreSQL 里是 timestamp with time zone，业务层拿到后还得做一套兼容转换，写出来的代码全是 if else 判断来源。

第三个困境是“连接管理混乱”。一个服务同时连五个数据库，每个库还要配连接池、事务边界、超时配置。数据源一多，连接数翻倍增长，数据库端连接数爆掉是早晚的事，而且排查问题的时候特别痛苦，不知道哪条查询走了哪个连接。

这三个问题本质上是同一个问题：缺少一层统一的数据访问抽象。应用层面对的不应该是五个数据源，而应该是一张张逻辑表。这也是我最终走向 Calcite 的根本原因。

1.2 常见多数据源方案的优缺点拆解

我在选型时对比过四条路线，每条我都实际试过，踩过坑，下面直接讲我自己的感受。

第一条是 Spring 自带的 AbstractRoutingDataSource 动态数据源路由。这个方案只解决“根据条件切换数据源”的问题，比如按租户 ID 路由到不同库，但它完全无法处理跨库 JOIN。因为路由发生在连接层面，一条 SQL 最终只会落到一个数据源执行，两个库的数据是无论如何合不到一起的。它适合的场景是分库分表后的单库路由，不是联邦查询。

第二条是基于 MyBatis 的多数据源插件，比如 popular 的 dynamic-datasource-spring-boot-starter。配置方便，切库注解也简单，但它同样是路由思想，SQL 还是落到单一数据源。想在一条 SQL 里同时查 MySQL 和 ClickHouse，它做不到，本质上它只是把连接管理做得更优雅了。

第三条是 ShardingSphere。它确实能实现跨库查询，因为它内部有 SQL 解析和路由能力，也能做联邦查询。但问题是它太重了，引入后相当于给整个数据访问层上了一套中间件约束，已有的 MyBatis 映射、事务管理、分页插件都要重新适配。而且 ShardingSphere 的强项是分库分表，多数据源联邦查询只是它的一个边缘能力，文档和社区讨论都不够聚焦。

第四条就是 Apache Calcite。它本身不是一个数据库，而是一个 SQL 解析、校验、优化、执行的框架。你可以把它理解成“数据库的数据库”——它不存储数据，但它知道数据在哪里，长什么样，然后让你用标准 SQL 去查询。它天然支持异构数据源联邦查询，核心就是扩展 Schema 和 Table 接口，把任意数据源包装成“表”的形态，剩下的交给 Calcite 的优化器。

我最终选 Calcite，核心原因是它把“数据源差异”和“SQL 查询”彻底解耦了。接入一个新数据源只需要写一个 Table 适配器，业务查询层完全不用感知底层数据源的变化。

1.3 为什么 Spring Boot 3 时代这个选择更合理

Spring Boot 3 相比 2.x 有两大变化，一是全面拥抱 Jakarta EE 9+，所有 javax.* 包名换成 jakarta.*；二是对 GraalVM Native Image 的支持更成熟。这两个变化在集成 Calcite 时会带来几个隐性好处。

先说包名迁移。Calcite 本身依赖的很多 Java 标准库也跟随 Jakarta 规范做了升级，在 Spring Boot 3 项目中，依赖冲突的概率比 Spring Boot 2.x 低很多。以前在 Boot 2.x 里集成 Calcite 的时候，经常因为 javax.validation 或 javax.annotation 的版本不一致报一堆莫名其妙的错，Boot 3 里这类问题少了很多。

再说启动速度。Spring Boot 3 配合 GraalVM 可以把应用打成原生镜像，启动时间从秒级降到毫秒级。Calcite 的大部分能力都是纯内存计算和优化器逻辑，对反射依赖较少，在 Native Image 下的适配性好于很多重量级 ORM 框架。当然我目前生产环境还是跑的 JVM 模式，但原生镜像这条路已经验证过可行性。

最后是 Spring Boot 3 的自动配置机制更清爽。Calcite 集成时，我可以直接通过 @ConfigurationProperties 把多数据源配置绑定到一个 Properties 类里，然后在启动时注册成 Calcite Schema，配置即代码，代码即配置，整个链路非常清晰。而不用像 Boot 2.x 时代那样写一堆 XML 或 properties 解析逻辑。

2. Calcite 的核心机制：Schema、Table、Enumerable 与源码入口

2.1 从一条 SQL 到结果：Calcite 处理流水线

要理解 Calcite 怎么实现多源查询，得先知道一条 SQL 在它内部经历了什么。整个流程可以拆成四个阶段：Parse、Validate、Optimize、Execute。

Parse 阶段用的是 JavaCC 生成的 SQL 解析器，把“select a.name, b.amount from mysql_order a join ck_user b on a.user_id = b.id”这样的字符串解析成一颗抽象语法树，也就是 SqlNode。Validate 阶段会拿着这颗语法树去查 Calcite 的 Catalog 元数据，检查表是否存在、字段是否匹配、类型是否兼容。Optimize 阶段是灵魂，Calcite 会把 SqlNode 转换成关系表达式 RelNode，然后经过一系列规则优化，比如下推过滤条件、调整 Join 顺序、选执行路径。Execute 阶段才真正触发数据源连接，把优化后的执行计划跑起来。

这里面最关键的是 Optimize 阶段。因为多源查询的所有魔法都在这里，Calcite 会通过自定义的 TableScan 节点决定底层数据从哪个数据源拉取，通过 Join 节点的实现类不同，决定是整个数据源拉回内存再关联，还是把条件下推给底层数据源提前过滤。

对于初次接触 Calcite 的人来说，建议直接把注意力放在 Validate 和 Optimize 之间的那片区域，也就是 Schema 和 Table 的接入，因为那是我们做集成时唯一需要大量写代码的地方，其他的基本都是框架内部机制。

2.2 Schema 与 Table 接口：多数据源接入的关键抽象

Calcite 的 Schema 接口我理解成“数据库实例”的抽象。一个 Schema 下面可以有一堆 Table，也可以有子 Schema，对应到真实世界就是“一个数据库实例下有多个库，每个库下有多个表”。

实现多数据源查询时，我们通常会给每个数据源建一个独立 Schema，比如 mysql_schema、clickhouse_schema，然后把数据源里的表一个个注册成 Table。也可以建一个覆盖所有数据源的 RootSchema，把不同的子 Schema 挂进去，这样查询的时候就可以写 select * from mysql_schema.orders 或者 select * from clickhouse.user_events。

Table 接口是更底层的抽象，它定义了表的结构和如何获取数据。实现 Table 接口时，需要重写两个核心方法，一个是 getRowType(RelDataTypeFactory typeFactory)，它返回表结构，也就是有哪些字段、什么类型；另一个是 getScan(RelOptTable table)，它返回一个可执行的扫描器。

这里有个容易误解的点：Calcite 的 Table 本质上是一个“元数据 + 执行器”的组合体。它不存储任何数据，只描述数据从哪来、长什么样、怎么读。所以接入一个新数据源的过程，本质上就是回答三个问题：这张表有哪些字段？字段什么类型？查询时怎么从数据源把数据捞出来？

2.3 源码层面拆解：Calcite 如何“忽悠”优化器

我学习 Calcite 源码时花时间最多的是 TableScan 和 EnumerableTableScan 这两个类。其实 Calcite 有好几种 TableScan 变体，常见的有 EnumerableTableScan、BindableTableScan、JdbcTableScan。它们的区别在于底层数据访问机制。

EnumerableTableScan 走的是 Linq4j 的迭代器模型，它会把整个表的数据拉回内存，然后以内存流的方式做过滤、投影、Join。好处是能处理任何数据源，坏处是数据量一大内存就爆。JdbcTableScan 则聪明得多，它会尽量把 Filter 和 Project 条件下推给底层数据库，让 MySQL、PostgreSQL 自己先执行 WHERE 和 SELECT，只把过滤后的结果拉回内存。

源码里最值得读的一段是 EnumerableTableScan 的 implement 方法，它会生成一个 EnumerableTableScanImplementor，这个类负责把 Table 的 getScan 返回值包装成 Linq4j 的 Enumerable。如果你实现了自定义 Table，想要走内存扫描以外的路径，就要考虑实现 EnumerableTableScan 之外的扩展机制。

Calcite 源码里还有一张很关键的内部结构图：RelOptCluster 持有 Planner，Planner 持有 RelOptPlanner，RelOptPlanner 负责把逻辑计划转成物理计划。我们自定义 Table 后，Calcite 会自动把 TableScan 节点接入这个流程，只要 Table 元数据正确，优化器就能正常运转——它不需要知道底层是 MySQL 还是文件，它只管根据统计信息和规则做优化。

2.4 联邦查询的实现原理：跨库 JOIN 到底怎么跑

跨库 JOIN 是最吸引人的能力，也是实现后最让团队同事“哇”出来的功能。它的底层原理虽然在 Calcite 文档里没有直接说明，但源码揭示得很清楚。

当 SQL 里出现 select * from mysql_schema.users a join clickhouse_schema.events b on a.id = b.user_id 时，Calcite 的优化器会先根据统计信息估算两个表的行数。它有两种处理模式：如果某个表的过滤条件能下推，就让底层数据库先做过滤，减少拉回数据量，然后以另一个表为主表，把数据拉回 JVM 内存，在内存中做 HashJoin 或 NestedLoopJoin；如果两个表都支持 JDBC 下推，Calcite 甚至有机会把部分关联条件组合成一条 SQL 发给同一个数据源，但这种情况仅限两个表在同一个数据源。

具体执行时，Join 节点的实现会在驱动表上创建一个 Enumerable 迭代器，每取一条数据就去被驱动表里查匹配数据，这就是 NestedLoopJoin；如果 Calcite 决定走 HashJoin，它会把小表加载到内存构建哈希表，再遍历大表匹配。

实际上，跨库 JOIN 的性能瓶颈主要在数据拉取量。所以实际落地时，必须想办法把过滤条件下推到数据源。比如 WHERE 条件里带了 create_time > '2024-01-01'，这个条件就应该让 MySQL 自己执行；如果写表的时候过滤条件下推没做好，Calcite 会把整表拉回来再过滤，几百万行数据直接就 OOM 了。这块我在第四节会专门讲怎么优化。

3. Spring Boot 3 集成实操：从依赖到可运行的联邦查询

3.1 工程准备与依赖引入

我用的工程结构是一个标准的 Spring Boot 3.2 项目，Java 版本 17，构建工具 Maven。Calcite 的版本我选用 1.36.0，这个版本在 JDK 17 下编译运行没有兼容性问题，而且对 Spring Boot 3 的依赖冲突处理得比较好。

Maven 依赖里，核心是 calcite-core 和 calcite-linq4j。注意 Calcite 是模块化设计的，如果你只跑本地文件数据源或 JDBC 数据源，不需要引入 calcite-server 和 calcite-csv 这些扩展模块。但为了方便测试，我还是会顺手加了 calcite-csv，因为 Calcite 官方自带的 CSV 示例非常适合做单元测试验证，先把链路打通再换成真实的 JDBC 数据源会顺畅很多。

xml复制<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-core</artifactId>
    <version>1.36.0</version>
</dependency>
<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-linq4j</artifactId>
    <version>1.36.0</version>
</dependency>
<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-csv</artifactId>
    <version>1.36.0</version>
    <scope>test</scope>
</dependency>

还有一个容易被忽略的依赖是 avatica-core，它是 Calcite 的 JDBC 驱动和远程连接框架。如果想让 Calcite 暴露 JDBC 接口，就必须加上它；如果只用内部 API 封装成 REST 接口，可以不加。我的方案里是 REST 接口，但为了调试方便还是在本地通过 JDBC 连了一次，所以加了 avatica-core。

Spring Boot 3 的自动配置我选择自己写一个 CalciteAutoConfiguration，放到 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件里，这样项目启动时 Spring Boot 会自动加载。这样的好处是后续如果做成 starter 给团队复用，完全不需要额外的手动配置。

3.2 自定义 SchemaFactory：把数据源配置转成 Calcite Schema

接入 Calcite 的第一步是创建一个 SchemaFactory。Calcite 提供了一套模型驱动机制，可以用 JSON 描述 Schema，然后通过 SchemaFactory 创建 Schema，但我不太推荐在 Spring Boot 项目里走 JSON 模型，因为会导致配置离散化，不好跟 Spring 的配置体系结合。

更优雅的方式是直接用代码注册 Schema。我写了一个 DynamicSchemaFactory 类，它实现了 org.apache.calcite.schema.SchemaFactory，构造时接收一个 DataSourceRegistry，这个 Registry 类管理所有已注册的数据源。

核心逻辑是把每个数据源的配置信息包装成一个 CalciteSchema，里面的表都是自定义的 JdbcQueryTable。我这样设计之后，SchemaFactory 就变成了一个薄薄的适配层，它只负责把 Spring 上下文里的 DataSource 对象转换成 Calcite 的 Schema，表注册细节全部委托给每个数据源自己的注册器处理。

java复制public class DynamicSchemaFactory implements SchemaFactory {
    private final Map<String, DataSourceWrapper> dataSourceMap;

    public DynamicSchemaFactory(Map<String, DataSourceWrapper> dataSourceMap) {
        this.dataSourceMap = dataSourceMap;
    }

    @Override
    public Schema create(SchemaPlus parentSchema, String name,
                         Map<String, Object> operand) {
        SchemaPlus schema = parentSchema;
        for (Map.Entry<String, DataSourceWrapper> entry : dataSourceMap.entrySet()) {
            SchemaPlus subSchema = schema.add(entry.getKey(),
                    new AbstractSchema() {
                        @Override
                        protected Map<String, Table> getTableMap() {
                            return entry.getValue().getTableMap();
                        }
                    });
            entry.getValue().getTableMap().forEach(subSchema::add);
        }
        return schema;
    }
}

这里的 DataSourceWrapper 是一个自定义的数据源包装类，内部持有 DataSource、数据库类型、表名集合。每次构建 Schema 的时候，我会通过数据库的元数据接口把当前数据源里的所有表名查出来，然后为每个表创建一个 JdbcQueryTable。

3.3 实现自定义 Table：把 JDBC 数据源变成逻辑表

JdbcQueryTable 是整套方案里最核心的类，它需要实现 org.apache.calcite.schema.Table 接口，或者直接继承 AbstractTable 简化开发。我选择实现 TranslatableTable 接口，因为它能支持查询计划的重写，为后续下推优化留好口子。

这个类的核心方法有两个。第一个是 getRowType，它需要根据数据库元数据动态生成 RowType。比如查询 MySQL 的 information_schema 拿到表的字段名和类型，然后映射成 Calcite 的 RelDataType。注意类型映射这里容易出问题，MySQL 的 DATETIME 对应 Calcite 的 TIMESTAMP，ClickHouse 的 DateTime64 要提前确定精度，否则查询时会出现类型转换异常。

java复制@Override
public RelDataType getRowType(RelDataTypeFactory typeFactory) {
    RelDataTypeFactory.FieldInfoBuilder builder = typeFactory.builder();
    for (ColumnMetaData column : columnMetaDataList) {
        builder.add(column.getColumnName(), toCalciteType(typeFactory, column.getSqlType()));
    }
    return builder.build();
}

第二个核心方法是 toRel，它告诉 Calcite 这个表是如何被扫描的。最简单的实现是返回一个 EnumerableTableScan，它会走内存拉取逻辑。更好的实现是返回 JdbcTableScan 或自定义的 FilterableTable，这样 WHERE 条件下推就有机会生效。

java复制@Override
public RelNode toRel(RelOptTable.ToRelContext context, RelOptTable relOptTable) {
    if (dataSourceWrapper.isJdbcCompatible()) {
        return new JdbcTableScan(context.getCluster(), relOptTable, jdbcImplementor);
    }
    return new EnumerableTableScan(context.getCluster(), relOptTable, this);
}

之前我为了快速跑通，直接返回 EnumerableTableScan，结果三个表 JOIN 的时候数据量一大 JVM 就 GC 频繁，后来改成 JDBC 兼容模式，关键查询的耗时才降下来。这里我的体会是：能走 JDBC 下推就一定走 JDBC 下推，不要贪图 Enumerable 的简单。

3.4 通过 REST 接口暴露联邦查询能力

为了让业务方用得舒服，我把 Calcite 查询封装成 REST 接口，对外提供 POST /api/query，请求体是一个 JSON，里面包含 SQL 语句。内部走 Calcite 的 Connection 创建 Statement，最后把结果集渲染成 JSON 返回。

实现时最关键的是创建 Connection。Calcite 的 Connection 是通过 DriverManager.getConnection("jdbc:calcite:", props) 创建的，其中 props 里必须包含 lex、parserFactory、schemaFactory 等参数。如果用代码创建，可以这样写：

java复制Properties info = new Properties();
info.setProperty("lex", "JAVA");
info.setProperty("schemaFactory", DynamicSchemaFactory.class.getName());
info.setProperty("dataSourceMap", objectMapper.writeValueAsString(dataSourceMap));
Connection connection = DriverManager.getConnection("jdbc:calcite:", info);

但上面这种方式需要序列化 dataSourceMap，比较麻烦。我更推荐直接使用 Calcite 的 CalciteConnection 实例，它可以通过 ConnectionConfig 和 CalciteSchema 直接构建，代码更清晰可控。

java复制CalciteConnection connection = DriverManager.getConnection("jdbc:calcite:", properties)
        .unwrap(CalciteConnection.class);
CalciteSchema rootSchema = CalciteSchema.createRootSchema(false, false);
DynamicSchemaFactory factory = new DynamicSchemaFactory(dataSourceRegistry.getAll());
factory.create(rootSchema.plus(), "multi", null);
connection.setRootSchema(rootSchema);

运行查询时，直接用 JDBC 标准接口：

java复制try (Statement statement = connection.createStatement();
     ResultSet rs = statement.executeQuery(sql)) {
    List<Map<String, Object>> rows = new ArrayList<>();
    ResultSetMetaData metaData = rs.getMetaData();
    int columnCount = metaData.getColumnCount();
    while (rs.next()) {
        Map<String, Object> row = new LinkedHashMap<>();
        for (int i = 1; i <= columnCount; i++) {
            row.put(metaData.getColumnLabel(i), rs.getObject(i));
        }
        rows.add(row);
    }
    return rows;
}

REST 接口我放在了 FederationQueryController 里，用 Spring MVC 实现，查询超时控制在 10 秒，避免慢 SQL 把线程池打满。这里要注意，Calcite 的 Statement.executeQuery 是同步阻塞的，建议用 TaskExecutor 包一层，给每个查询设置超时中断。

3.5 多数据源按需注册与切换

我的需求里有一个比较动态的场景：业务方会临时接入新的分析库，不想改代码重启服务。所以我在 DataSourceRegistry 里提供了运行时注册数据源的方法。

java复制public void registerDataSource(String schemaName, DataSource dataSource,
                               String databaseType, List<String> tableNames) {
    DataSourceWrapper wrapper = new DataSourceWrapper(schemaName, dataSource,
            databaseType, tableNames);
    dataSourceMap.put(schemaName, wrapper);
    rebuildSchema();
}

rebuildSchema 方法会重新构建 RootSchema，并且更新 CalciteConnection 的 RootSchema。注意这里的坑：Calcite 的 Schema 在第一次被优化器访问后可能有缓存，直接修改 map 不能保证下一次查询能感知到，所以需要重新设置 RootSchema 或者让旧 Connection 失效。

我在生产环境采用的是“重建连接池 + 重建 Schema 引用”的策略：每个数据源注册进来后，生成一个独立的 CalciteConnection，放进一个 ConcurrentHashMap 作为缓存；业务查询时按 schemaName 路由到对应的 Connection 上。这样做的好处是数据源之间完全隔离，一个数据源的连接池异常不会拖垮其他数据源。

4. 动态数据源切换、缓存优化与跨库 Join 的边界

4.1 动态数据源注册的工程化设计

动态注册听起来很爽，工程化落地时要想清楚几个问题。第一个问题是连接池生命周期管理。比如某个数据源被移除后，底层的 HikariCP 连接池如果不关闭，连接数就会一直占着。我写了一个 DataSourceLifecycleManager，专门负责跟踪每个数据源的使用状态，在调用 remove 方法时先关闭连接池，再从注册表删除。

第二个问题是配置来源。我把数据源配置放在 application.yml 里，用 @ConfigurationProperties 绑定到一个列表，启动时全部注册；同时也开放一个 REST 接口 POST /api/datasources 让运维可以临时注册新库。注册接口内部会校验 JDBC URL 是否能连通，避免脏配置进入运行态。

第三个问题是表结构变更。如果某个源表加了字段，Calcite 侧的 RowType 不会自动感知。我在注册器里维护了一张 tableMetaDataCache 表，用 schemaName + tableName 作为 key，缓存表的字段结构和类型；同时提供刷新接口，业务方可以在变更后手动调用刷新。如果想让刷新全自动，可以用定时任务每 10 分钟拉取一次元数据，但那样的压力比较大，我的生产环境是手动刷新 + 关键表主动刷新结合。

java复制@Scheduled(fixedDelay = 600_000)
public void refreshTableMetaData() {
    dataSourceMap.values().forEach(wrapper -> wrapper.refreshAllTableMetaData());
}

不过定时刷新有个风险：如果你的查询和刷新发生竞争，可能出现 RowType 和底层表结构不一致导致查询失败。所以刷新时我用的是 CopyOnWriteArrayList 的写时复制思路，生成新 Table 列表一次性替换旧列表，查询线程拿到的始终是完整版本。

4.2 Calcite 连接管理与复用

直接每次查询都创建新的 CalciteConnection 是不行的，因为 Schema 里的 Table 元数据要被反复加载，连接创建的开销虽然不大，但累积起来也客观。我实现了一个 CalciteConnectionPool，本质上是个简单的工厂：每个 schemaName 对应一个连接实例，连接实例内部持有一个 Schema 快照。

考虑到线程安全，我用了 ThreadLocal<CalciteConnection> 来保存每个线程的连接引用，避免多个线程并发使用同一个 Statement 导致的异常。Calcite 的 Connection 和 Statement 不是线程安全的，这一条你一定要记住，很多并发错误都源于复用同一个 Statement。

连接池的大小不需要很大，因为 Calcite 本身不是连接数据库的连接池，它是一个“解析和优化引擎容器”，真正的数据库连接由底层的 HikariCP 管理。Calcite 层面的连接只是逻辑概念，每创建一个连接主要是初始化 Schema 和优化器，开销在毫秒级，反而频繁重建连接更浪费时间。

4.3 跨库 Join 的边界与性能瓶颈

跨库 JOIN 能实现，但不代表能无脑 JOIN。要想跑得稳，必须把握住几个边界条件。

第一，参与 JOIN 的表最好都是“可以下推过滤条件”的表。比如 JOIN 之前先用 WHERE 把时间范围收窄到一天，那底层查询就只拉一天的数据，内存压力小很多。如果业务方喜欢写不带 WHERE 的全表 JOIN，神仙也救不了。

第二，JOIN 的键最好有索引。但注意这里的索引不是 Calcite 层的索引，而是底层数据源的索引。比如用 MySQL 的用户 ID 去 JOIN ClickHouse 的事件表，ClickHouse 这边user_id 如果是低基数字段且有索引，性能会好很多；如果 Join 键没有索引，Calcite 只能在内存里做全量哈希匹配。

第三，要注意结果集的扇出。如果两个表是 1:N 关系，JOIN 后返回的行数可能远超预期。比如用户表和订单表 JOIN，一个用户有 1 万条订单，返回结果就是用户行复制 1 万次。所以在使用时要提前评估返回行数，设置查询最大返回行数限制，防止响应体过大把网卡打爆。

我加的一道保护是查询结果行数限制开关，默认上限 5 万行。一旦超过直接抛异常，让调用方加过滤条件。这个看似简单的限制，实际生产里帮我挡住过至少三次因为业务误操作导致的查询风暴。

4.4 缓存策略：在数据新鲜度与性能之间找平衡

有时业务场景根本不需要实时查询，比如报表数据，30 分钟内的数据变化完全可以接受。这种情况下，我给 Calcite 查询层加了一层缓存，把 SQL 的哈希值作为 key，结果集作为 value，TTL 可配置。

缓存实现我用了 Caffeine，因为它是进程内缓存，性能极高。配置方式很简单：

java复制Cache<String, List<Map<String, Object>>> queryCache = Caffeine.newBuilder()
        .maximumSize(10_000)
        .expireAfterWrite(Duration.ofMinutes(30))
        .build();

缓存命中时直接返回结果；未命中时才走 Calcite 查询链路。注意缓存 key 不能只用 SQL 字符串，还应该包含参与表的元数据版本号。否则表结构变更了，缓存里还是旧结构的数据，业务拿到后反而出错。我在 key 拼接时把 tableMetaVersion 也放进去，表结构刷新后版本号变化，旧缓存自动失效。

实时查询和缓存查询我做了两个接口分开：/api/query/realtime 永远不带缓存；/api/query/cached 走缓存。这样既满足实时监管场景，也让报表查询压力低很多。

4.5 常见问题速查表

我整理了一份我在实际集成时遇到最多的问题，直接做成表格，方便排查。

5. 源码视角：Planner 如何影响你的查询计划

5.1 HepPlanner 与 VolcanoPlanner 的区别

Calcite 的优化器有两种主要实现：HepPlanner 和 VolcanoPlanner。我在初期调试查询计划不顺的时候，总以为是 SQL 写错了，后来冷静下来看了源码，才发现很多怪现象其实是 Planner 机制导致的，搞清楚它俩的区别非常必要。

HepPlanner 是一个基于启发式规则的优化器，它的特点是“按照固定顺序不停地应用规则”。比如它会先做 FilterPushDown，再做 ProjectMerge，规则之间不比较代价，只要满足条件就应用。它不讲求最优计划，但执行速度快，适合规则明确、希望结果可预测的场景。VolcanoPlanner 则是基于代价的优化器，它会生成多种执行计划，然后用代价模型评估，选代价最低的。它的好处是能根据表行数统计和实际数据分布选更合适的 Join 顺序，坏处是优化耗时更长，而且如果规则没写好，可能陷入搜索空间爆炸。

在 Calcite 默认配置下，用户查询走的是 VolcanoPlanner。这意味着，我们注册的 Table 如果实现了 TranslatableTable，它会尝试把 TableScan 转成各种物理执行节点，然后挑代价最小的。如果我们的 Table 实现没有提供准确的元数据行数，优化器就会按默认值估算，导致选出来的执行计划不是最优的。

所以源码阅读建议是：先不要硬啃 VolcanoPlanner 的代价模型，我们先搞清楚 HepPlanner 的规则执行顺序，再看 VolcanoPlanner，会容易理解很多。因为 HepPlanner 的规则顺序就是 Calcite 优化时“展开优化选项”的起点。

5.2 源码阅读路径推荐

我刚开始读 Calcite 源码时，有点像没头苍蝇，后来摸索出一条比较顺的路径。

第一步，先读 org.apache.calcite.sql.parser.SqlParser，了解 SQL 解析入口。它是 JavaCC 生成的，不要硬啃生成代码，重点是看 SqlNode 的各类实现，比如 SqlSelect、SqlJoin、SqlIdentifier。

第二步，读 org.apache.calcite.rel.RelNode 及其实现类，理解逻辑计划和物理计划的差异。重点是 LogicalProject、LogicalFilter、LogicalJoin 这几个节点。

第三步，读 org.apache.calcite.plan.RelOptPlanner，看它如何把逻辑计划转成物理计划。这里有一个非常关键的方法叫 setRoot，它接收一个逻辑根节点，经过规则匹配后生成物理计划树。

第四步，回到 org.apache.calcite.adapter.enumerable.EnumerableRules，看 Calcite 如何把每种物理节点转成可执行的 Java 代码。这里比较抽象，因为涉及到代码生成，但如果你只想集成数据源，不用深入到代码生成，理解到物理计划这一步就够了。

读完这四步，你再回来看我们的自定义表实现，思路就会清晰很多。你会明白 toRel 方法返回的 JdbcTableScan 其实是作为一个物理计划节点直接挂到了计划树上，Calcite 的优化器后续会基于它继续做规则匹配和下推。

5.3 学习 Calcite 源码时最容易卡住的三个点

第一个卡点是代码生成。Calcite 使用 Janino 在运行时动态编译 Java 代码，把执行计划“编译”成一个可执行的 Enumerable 类。想深入理解这部分非常难，因为涉及到语法树遍历、表达式生成和字节码编译的衔接。我建议对大多数使用者来说，不需要深入，只需要知道计划最终被编译成 Java 代码执行即可。

第二个卡点是测试套件的结构。Calcite 自带大量测试，测试资源文件非常多，经常让人不知道从哪看起。建议直接搜 RelBuilderTest 和 TableScanTest 这两个测试类，因为它们覆盖了最基础的表扫描和查询计划生成场景，理解起来最快。

第三个卡点是日志和调试。Calcite 的查询计划输出在 debug 日志里，但它有多个 logger，需要把 org.apache.calcite.plan 这个 logger 的日志级别调到 DEBUG，才能看到优化前的逻辑计划和优化后的物理计划。否则你看不到任何计划信息，很难定位问题。

我实际调试时，最喜欢的方式是在代码里调用 RelOptPlanner 的 dump() 方法，把当前计划树打印出来。但要注意这个方法的返回内容是格式化过的树结构，阅读时需要一点耐心，特别是 Join 层级多时，嵌套会非常深。

6. 个人经验与后续扩展方向

这套 Spring Boot 3 + Calcite 的联邦查询方案，我已经在测试环境跑了将近两个月，生产环境也有多个核心报表开始接入。最直观的收益是团队里写报表的人不需要再关心数据从哪个库来，SQL 写起来跟单库查询一样，只是表名加了 schema 前缀。我自己的体会是，Calcite 的学习曲线确实陡，但一旦把 Schema 和 Table 这套抽象理解透，它就是最值得投入的中间件之一。

有一个小经验想分享：在集成初期，一定要先做通一个最小案例，不要一上来就接三个真实数据源。我用 calcite-csv 做了几个本地 CSV 文件，模拟两张表做 JOIN 查询，把 SQL 解析、校验、优化、执行的链路完全跑通之后，才切换到 JDBC 数据源。少了这一步，后面排查问题时非常容易混淆“是 Calcite 配置问题”还是“是数据源连接问题”。

后面我打算在这个基础上做三件事：第一是支持更多数据源类型，比如 MongoDB 和 Elasticsearch，通过 Calcite 官方已有的适配器做二次封装；第二是接入查询审计组件，把每条 SQL 的下推情况和耗时记录到日志系统，方便性能分析；第三是把数据源注册能力做成可视化界面，让业务方自己维护表映射关系，减少开发介入。Calcite 这个框架扩展性极强，我目前用到的能力可能还不到三分之一，后续还有很大的挖掘空间。