1. 为什么我要专门开一个专栏聊 Calcite第一次接触 Calcite 是在做一个数据报表平台的时候。当时的需求听起来特别朴素业务方希望能用 SQL 查询底层好几种不同的数据源有 MySQL 里的订单表有 Hive 里的日志宽表还有一份存在 CSV 文件里的配置数据。我一开始的想法很简单写几个 if-else 分支根据表名路由到不同的查询引擎把结果拼起来返回。结果做到第三天就发现不对劲了——业务方要 join要 group by要窗口函数还要自定义函数。这时候我才意识到我需要的不是一个简单的路由层而是一个真正的 SQL 解析、校验、优化、执行的完整链路。Calcite 就是在这个背景下进入我的视野的。它的定位非常特殊它不是一个数据库而是一个SQL 处理框架。你可以把它理解成一套乐高积木它提供了 SQL 解析器、校验器、逻辑计划、优化器规则、执行适配层这些零件但具体连什么数据源、怎么执行由你自己决定。这个定位决定了它的学习曲线和普通数据库完全不一样——你不是在学怎么用 Calcite而是在学怎么把 Calcite 嵌进你自己的系统里。这个专栏我打算写成一个系列把我这几年在 Calcite 上踩过的坑、读过的源码、做过的适配系统地整理出来。适合的读者是那些已经有一定 Java 基础、做过数据处理相关的工作、准备在自己的项目里引入 Calcite 或者正在被 Calcite 的某个环节卡住的人。如果你只是想找一个能直接跑 SQL 的数据库那 Calcite 可能不是你要的东西但如果你需要一套可定制的 SQL 能力那它几乎是 Java 生态里绕不开的选择。2. Calcite 到底解决了什么问题又故意不解决什么2.1 它把 SQL 处理拆成了可替换的流水线很多人第一次看 Calcite 的文档会懵因为官方一直在强调optional这个词。解析器是可选的优化器是可选的连执行引擎都是可选的。这不是在故弄玄虚而是 Calcite 的核心设计哲学SQL 处理的每个阶段都应该是一个独立的、可替换的组件。一条 SQL 从字符串到结果在 Calcite 的世界里会经过这么几个阶段。首先是解析把 SQL 文本变成抽象语法树这一步由 SqlParser 完成。然后是校验检查表是否存在、字段类型是否匹配、函数签名对不对这一步由 SqlValidator 完成。接着是转换把语法树变成关系代数表达式也就是 RelNode 树。再然后是优化用一系列规则对 RelNode 树做等价变换比如谓词下推、列裁剪、join 重排序。最后是执行把优化后的 RelNode 树交给具体的执行引擎去跑。关键在于这五个阶段里Calcite 只强制要求你用它定义好的接口具体每个阶段用什么实现你完全可以换。比如你可以只用它的解析器和校验器优化和执行自己写也可以用它全套的优化器但执行层对接自己的计算引擎。这种灵活性是 Calcite 最大的价值也是它最大的学习成本来源——因为选择太多新手往往不知道该从哪里下手。2.2 它不碰存储也不碰执行Calcite 有一个非常明确的边界它不负责数据存储也不负责实际的计算执行。它做的事情是理解 SQL 并告诉你怎么算而不是帮你把数据算出来。这个边界带来的直接后果是你没法像用 MySQL 那样装好就能连上跑查询。你必须自己实现一个 Adapter告诉 Calcite 你的数据长什么样、表结构怎么定义、数据怎么读取。Calcite 提供了一些现成的 Adapter比如 CSV Adapter、JDBC Adapter、MongoDB Adapter但这些 Adapter 更多是作为示例存在的真正在生产环境用的时候你大概率需要自己写一个。我见过不少人在这一步放弃因为他们期待的是引入一个 jar 包就能用 SQL 查数据而 Calcite 给的是引入一个 jar 包然后你自己写代码告诉它怎么查数据。这个预期差是导致很多人觉得 Calcite 难用的根本原因。但换个角度想正是因为它不碰存储和执行它才能适配几乎任何数据源和任何计算引擎这个通用性是用易用性换来的。2.3 它的优化器是真正可以独立使用的Calcite 的优化器是我个人认为它最有价值的部分。它基于 Volcano 模型实现核心思想是把优化规则和优化引擎分离。你定义一堆 RelOptRule每条规则描述一种等价变换比如把 Filter 推到 Join 下面然后优化器会自动地、反复地应用这些规则直到找到一个成本最低的执行计划。这套优化器的好处是它是通用的。不管你底层是关系数据库、NoSQL、还是流处理引擎只要你能把查询表达成 RelNode 树就能用这套优化器来优化。而且它的规则是可插拔的你可以写自己的规则来处理特定数据源的特性。比如你的数据源对某些函数有原生支持你就可以写一条规则把 Calcite 的函数调用转换成数据源的原生函数调用从而利用数据源的优化能力。我后面会专门用几篇文章来讲优化器包括规则怎么写、成本模型怎么定、怎么调试优化过程。这部分是 Calcite 最硬核也最有意思的地方值得花时间啃。3. 这个专栏的写作思路和内容规划3.1 从能跑起来到能跑得好这个专栏的内容安排会遵循一条主线先让你能把 Calcite 跑起来再让你理解它为什么这么设计最后让你能根据自己的场景做定制。开篇的几篇会聚焦在最小可运行示例上。我会带你写一个最简单的 Adapter定义一张表跑通一条 select 语句。这个过程中会涉及 Schema 的定义、Table 接口的实现、RelNode 的转换这些基础概念。目标不是让你理解所有细节而是让你先有一个能调试的环境后面遇到问题可以随时改代码验证。中间的部分会深入到各个核心模块。解析器部分会讲 SqlParser 的配置、自定义语法扩展、常见解析错误的排查。校验器部分会讲类型系统、函数注册、命名空间解析。优化器部分会讲规则编写、成本计算、优化日志的解读。执行部分会讲 Enumerable 约定、代码生成、以及与外部引擎的对接方式。最后的部分会讲一些实战中才会遇到的问题。比如怎么处理多层嵌套的 join、怎么支持自定义聚合函数、怎么做跨数据源的查询下推、怎么调试优化器选了一个很差的计划。这些问题在官方文档里往往一笔带过但在实际项目里几乎一定会遇到。3.2 每篇都会配可运行的代码我不想把这个专栏写成纯理论的东西。Calcite 的很多概念光看文字是理解不了的必须动手跑一遍才能明白。所以每篇文章我都会配一个最小可运行的示例代码会尽量精简只保留和主题相关的部分。这些示例我会尽量用同一套基础代码演进这样你在读不同文章的时候不需要重新理解上下文。比如第一篇文章里定义的那张表后面的文章里会一直用只是逐步给它加上更多的能力。这种方式的好处是你能看到一个小系统是怎么一步步长出来的而不是每篇文章都面对一个全新的代码库。代码的依赖我会控制在最少。Calcite 本身的依赖不算多但如果你要用它的 JDBC Adapter 或者 CSV Adapter会引入一些额外的库。我会尽量用最核心的模块来演示避免让你在环境配置上浪费时间。3.3 会重点讲为什么而不是是什么Calcite 的官方文档和 Javadoc 其实挺全的每个类和接口都有说明。但文档的问题是它只告诉你这个方法是干什么的不告诉你为什么要这么设计、什么场景下该用哪个、用错了会怎样。这个专栏会重点补上这部分。比如 RelNode 有很多子类TableScan、Project、Filter、Join、Aggregate文档会告诉你每个类代表什么操作但不会告诉你为什么 Calcite 要把它们设计成独立的类而不是一个通用的节点。我会解释这背后的原因——因为优化规则需要针对特定类型的节点做匹配如果所有操作都混在一个节点里规则就没法精确地表达我只想匹配 Filter 在 Join 上面的情况。再比如 Calcite 的 Convention 机制文档会告诉你 EnumerableConvention 和 BindableConvention 的区别但不会告诉你为什么需要 Convention 这个东西。我会从物理执行计划的表示这个角度来解释让你理解 Convention 本质上是在标记这棵 RelNode 树打算用什么方式执行。4. 开始之前你需要准备什么4.1 知识储备上的准备读这个专栏之前有几块基础知识是需要的。Java 是必须的因为 Calcite 是 Java 写的所有的扩展点都是 Java 接口。如果你对 Java 的泛型、反射、注解这些特性不熟悉读源码的时候会比较吃力。SQL 的基础也要有。你不需要是 SQL 专家但至少要理解 select、from、where、group by、join 这些基本操作的含义以及什么是关系代数。Calcite 的核心就是把 SQL 转换成关系代数如果你对关系代数完全没概念理解 RelNode 树会比较困难。另外如果你对编译原理有一点点了解会很有帮助。Calcite 的解析器是用 JavaCC 生成的优化器用到了很多术语重写和模式匹配的思想这些和编译原理里的概念是相通的。当然这不是必须的我会在涉及的时候做解释。4.2 开发环境的准备环境方面你需要 JDK 8 或以上Maven 或 Gradle 来管理依赖。IDE 我推荐用 IntelliJ IDEA因为它对 Java 的调试支持比较好而调试 Calcite 的优化过程非常依赖断点。依赖方面最核心的是 calcite-core 这个包。如果你要用它的 JDBC 适配能力还需要 calcite-linq4j。测试的时候可以用 JUnitCalcite 自己的测试用例也是用 JUnit 写的你可以参考它的测试代码来理解各种 API 的用法。我建议你在开始之前先把 Calcite 的源码 clone 到本地。不是为了读全部源码而是为了在遇到不理解的类时能直接跳进去看实现。Calcite 的源码注释写得还算清楚很多设计意图在注释里都有说明。提示Calcite 的版本迭代比较快不同版本之间的 API 可能有变化。这个专栏的代码会基于一个相对稳定的版本你在实际使用的时候注意核对版本号遇到 API 对不上的情况先检查版本。4.3 心态上的准备最后说一点心态上的准备。Calcite 的学习曲线确实比较陡这不是你的问题是它的设计决定的。它为了通用性牺牲了很多易用性很多在其他框架里一行代码搞定的事情在 Calcite 里需要你写一个类来实现。我的建议是不要试图一次性理解所有东西。先跑通一个最小示例然后遇到问题再针对性地深入。Calcite 的很多设计只有在你真正需要某个功能的时候才能体会到它的好处。比如 Convention 机制如果你只是跑一个简单的查询会觉得它完全是多余的但当你需要同时支持多种执行引擎的时候就会发现这个设计有多巧妙。这个专栏会尽量把学习路径铺得平缓一些但有些坎是绕不过去的比如 RelNode 的转换、优化规则的理解。遇到这些地方的时候建议你多跑代码、多打日志用实际运行结果来验证你的理解。5. 我在 Calcite 上踩过的几个典型坑5.1 把 Calcite 当成数据库来用这是我最开始犯的错误。我以为引入 Calcite 之后就可以像用普通数据库一样建个连接、发 SQL、拿结果。结果发现完全不是这么回事——Calcite 根本没有连接这个概念它有的是 Schema、Table、RelNode 这些抽象。这个坑的本质是没理解 Calcite 的定位。它是一个框架不是一个服务。你需要自己实现数据读取的逻辑自己决定怎么执行查询。Calcite 提供的是 SQL 处理的能力不是数据存储和计算的能力。理解这一点之后很多设计就说得通了。5.2 忽略 Convention 导致计划无法执行有一次我写了一个自定义的 RelNode兴冲冲地把它放进优化器里结果运行的时候报错说找不到合适的执行方式。查了半天才发现是 Convention 的问题——我的 RelNode 没有标记 Convention优化器不知道该怎么把它转换成可执行的计划。Convention 这个概念在文档里讲得比较抽象我当时的理解是它就是个标记没什么用。但实际上它决定了优化器在转换计划时的行为。不同的 Convention 代表不同的执行方式优化器会在转换过程中插入 Convention 转换节点把一种执行方式转换成另一种。如果你的 RelNode 没有正确的 Convention优化器就没法把它接入到整个转换流程里。5.3 优化规则写得太宽泛导致性能问题还有一次我写了一条优化规则想把所有的 Filter 都下推到 TableScan 下面。规则写得很简单匹配 Filter 然后把它推到子节点。结果跑起来发现优化过程特别慢因为这条规则会反复应用每次应用都产生一个新的 RelNode优化器需要不断比较成本。后来我加了更精确的匹配条件只对特定模式的 Filter 应用规则问题才解决。这个坑让我理解了优化规则的设计原则规则要尽量精确匹配范围越小越好。宽泛的规则会导致优化器做很多无用功甚至可能陷入无限循环。5.4 对成本模型的误解Calcite 的优化器是基于成本的它会计算每个候选计划的成本然后选成本最低的。我一开始以为成本就是执行时间后来发现不是——成本是一个抽象的概念由你定义的 Cost 类来决定。默认的成本模型可能不适合你的场景你需要根据自己的数据源特性来调整。比如对于内存中的小数据集网络传输成本可以忽略CPU 成本是主要的但对于分布式数据源网络传输成本可能占主导。如果你不调整成本模型优化器可能会选出一个在你的场景下很差的计划。这个坑的教训是不要假设默认的成本模型适合你要根据实际情况调整。6. 这个系列后续会覆盖的内容6.1 核心模块的深度拆解后续的文章会按照 Calcite 的处理流程逐个模块深入。解析器部分会讲怎么扩展 SQL 语法、怎么处理自定义的方言差异。校验器部分会讲类型推导的规则、怎么注册自定义函数、怎么处理命名空间和 schema 的解析。优化器部分会讲规则的匹配机制、成本的计算方式、怎么用 HepPlanner 和 VolcanoPlanner 做不同的优化策略。执行部分会讲 Enumerable 的执行流程、怎么用代码生成来提升性能、怎么对接外部的计算引擎。每个模块我都会从它解决什么问题开始讲然后讲它是怎么解决的最后讲你在使用的时候要注意什么。这种结构能帮你建立完整的认知而不是零散地记一些 API 用法。6.2 实战场景的完整案例除了模块拆解我还会写一些完整的实战案例。比如怎么用 Calcite 做一个跨数据源的查询引擎怎么把 Calcite 集成到 Flink 或 Spark 这样的计算框架里怎么用 Calcite 做 SQL 的血缘分析。这些案例会涉及多个模块的配合能帮你理解各个部分是怎么协同工作的。案例的代码会尽量完整你可以直接拿来改造成自己的项目。当然实际生产环境要考虑的东西比示例多得多比如并发、容错、监控这些我会在案例里提到但不会展开因为那属于工程实践的范畴不是 Calcite 本身的内容。6.3 常见问题的排查手册最后会有一部分内容专门讲排查问题。Calcite 的报错信息有时候比较晦涩比如Unable to implement plan这种光看错误信息很难定位问题。我会整理一些常见错误和对应的排查思路包括怎么读优化日志、怎么用断点跟踪 RelNode 的转换过程、怎么判断问题是出在规则还是出在成本模型上。这部分内容会随着专栏的更新不断补充因为我自己也在不断遇到新的问题。如果你在使用的过程中遇到了这个专栏没覆盖的问题也欢迎交流我会把典型的案例整理进来。写这个专栏的初衷很简单Calcite 的中文资料太少了而它的设计又足够复杂导致很多人卡在入门阶段就放弃了。我希望这个专栏能成为一座桥帮你跨过最初的那道坎看到 Calcite 真正有价值的地方。它不是一个容易上手的工具但一旦你理解了它的设计思路就会发现它提供的灵活性是其他方案很难替代的。
)
