1. 为什么我要开一个 Calcite 解读专栏
第一次接触 Apache Calcite 是在做一个数据平台项目的时候。当时业务方提了一个需求：让分析师能用 SQL 直接查异构数据源，MySQL、Elasticsearch、CSV 文件甚至 REST 接口，最好还能做点简单的聚合和 join。我第一反应是这活儿得写多少适配代码，结果团队里一位老哥甩了一句“上 Calcite 啊”，然后我就掉进了这个坑，一掉就是好几年。
Calcite 是什么？一句话概括：它是一个动态数据管理框架，核心能力是把 SQL 解析成抽象语法树，经过一系列优化规则后，下推到任意数据源执行。它不存储数据，也不负责执行，它干的是“翻译”和“优化”的活。你可以把它理解成一个 SQL 语言的编译器前端加优化器，后端接什么完全由你决定。这玩意儿的价值在于，它让“给任何系统加一套 SQL 查询能力”这件事从几个月的工作量压缩到几周甚至几天。
这个专栏适合谁看？如果你正在做数据中间件、查询引擎、数据库内核、BI 工具后端，或者你单纯对“一条 SQL 从输入到执行到底经历了什么”感到好奇，那这里的内容应该对你有用。我会尽量少贴官方文档里能查到的东西，多讲我在实际项目里踩过的坑、调过的参数、读过的源码。专栏不会假设你已经是编译原理专家，但至少得写过 SQL、用过 Java，知道什么是 AST。
写这个前言的目的很简单：把后面要讲的东西先铺个底，让你知道 Calcite 在整个技术栈里处于什么位置，它的核心模块怎么划分，以及为什么很多看起来“反直觉”的设计其实是深思熟虑的结果。后面每一篇我会挑一个具体主题深入，比如 SQL 解析、RelNode 体系、优化器规则、适配器开发、成本模型等等。这一篇算是地图，先把地形画出来。
2. Calcite 的核心架构与设计哲学
2.1 一个“不执行 SQL”的 SQL 引擎
刚接触 Calcite 的人最容易困惑的一点是：它叫自己 SQL 引擎，但你把一条 SQL 丢给它，它并不会返回结果。它返回的是一棵 RelNode 树，也就是关系表达式树。这棵树描述了“要做什么”，但没描述“怎么做”和“在哪做”。
这个设计是 Calcite 最核心的哲学：关注点分离。SQL 的解析、校验、优化是通用能力，而数据的存储和计算是跟具体系统强相关的。Calcite 把前者做到极致，后者完全交给适配器（Adapter）去实现。所以你会看到 Calcite 支持 JDBC、文件、内存、Elasticsearch、Kafka、MongoDB 等各种数据源，但每一种的支持方式都是通过适配器把外部元数据和数据映射成 Calcite 能理解的 RelNode 和 Row 流。
这种设计带来的直接好处是：你不需要为了获得 SQL 能力而重写整个存储层。你只需要实现几个接口，告诉 Calcite“我有哪些表、哪些列、什么类型”，然后实现一个执行器把 Calcite 生成的物理计划跑起来就行。听起来简单，做起来有坑，后面会专门讲适配器开发。
2.2 四大核心模块：Parser、Validator、Optimizer、Adapter
Calcite 的代码库很大，但核心模块可以分成四块。第一块是 Parser，基于 JavaCC 生成的 SQL 解析器，把 SQL 文本变成 SqlNode 树。第二块是 Validator，负责语义校验，比如表是否存在、列名是否拼错、类型是否匹配，校验通过后 SqlNode 会转换成 RelNode。第三块是 Optimizer，这是 Calcite 最值钱的部分，它用一套基于规则（Rule-based）和基于成本（Cost-based）的优化框架，把逻辑计划变成更高效的逻辑计划，再变成物理计划。第四块是 Adapter，负责跟外部系统对接，包括元数据发现、数据读取、谓词下推等。
这四块里，Optimizer 是复杂度最高、也最值得深入研究的。Calcite 的优化器不是简单的“规则堆叠”，它有一个 Volcano 风格的 Planner，会在规则匹配和成本比较之间反复迭代，直到找到成本最低的计划。理解这个迭代过程，是理解 Calcite 优化行为的关键。
2.3 为什么选择 RelNode 而不是直接操作 AST
很多人会问：既然 SqlNode 已经是树了，为什么不直接在 SqlNode 上做优化？答案是：SqlNode 太“语法化”了。它保留了太多 SQL 表面的东西，比如子查询的写法、join 的顺序、括号的位置。这些东西对优化来说是噪音。RelNode 是关系代数层面的表达，它把 SQL 的语法糖都剥掉了，只留下集合操作、过滤、投影、聚合、join 这些本质操作。在 RelNode 层面做优化，规则写起来更干净，也更容易做等价变换。
举个例子，SELECT a FROM t WHERE b > 1 AND b > 1在 SqlNode 层面是两个条件，但在 RelNode 层面经过化简就变成一个条件。再比如子查询展开、谓词下推、列裁剪这些优化，在 RelNode 层面都有成熟的规则可以直接用。所以 Calcite 的设计是：Parser 负责“翻译”，Validator 负责“检查”，Optimizer 负责“改写”，Adapter 负责“执行”。每一层职责清晰，互不越界。
3. 从 SQL 文本到执行计划：一条查询的完整旅程
3.1 解析阶段：SqlNode 树的诞生
当你把一条 SQL 字符串传给 Calcite 的SqlParser，它首先会做词法分析和语法分析。Calcite 用的是 JavaCC 生成的解析器，支持标准 SQL 以及一些扩展语法。解析的结果是一棵 SqlNode 树，根节点通常是SqlSelect，下面挂着SqlFrom、SqlWhere、SqlGroupBy等子节点。
这个阶段有个容易忽略的细节：Calcite 支持多种 SQL 方言。你可以通过配置SqlParser.Config来指定大小写敏感、标识符引用字符、是否允许隐式类型转换等。我在项目里遇到过因为大小写敏感配置不一致导致表名匹配失败的问题，排查了半天才发现是 parser 配置的问题。所以如果你要做多数据源统一查询，方言配置一定要提前统一。
解析阶段还有一个重要产物是SqlNode的位置信息。Calcite 会记录每个节点在原始 SQL 中的位置，这对错误提示非常有用。当校验失败时，它能告诉你“第 3 行第 15 列附近的列名不存在”，而不是只给一个干巴巴的异常。
3.2 校验阶段：从 SqlNode 到 RelNode
校验阶段的核心工作是SqlValidator和SqlToRelConverter。Validator 会遍历 SqlNode 树，检查表是否存在、列是否合法、函数是否支持、类型是否兼容。这个过程会用到 Catalog 和 Schema 提供的元数据。Catalog 是 Calcite 对元数据的抽象，你可以把它理解成一个“数据库的数据库”，里面注册了所有的 Schema、Table、Function。
校验通过后，SqlToRelConverter会把 SqlNode 转成 RelNode。这个转换不是一对一的，比如一个SqlSelect可能会变成一个LogicalProject加一个LogicalFilter加一个LogicalTableScan。转换过程中还会做一些初步的化简，比如常量折叠、谓词合并。这一步的输出是逻辑计划，也就是RelNode树，但还没有经过优化。
这里有个经验：如果你发现 Calcite 报的错很奇怪，比如“Cannot convert SqlNode to RelNode”，大概率是 Validator 阶段漏掉了某些校验，导致 Converter 遇到了不认识的节点。这时候可以打开 Calcite 的 debug 日志，看看是哪个 SqlNode 卡住了。
3.3 优化阶段：规则匹配与成本比较的舞蹈
优化阶段是 Calcite 最复杂也最精彩的部分。Calcite 的优化器基于 Volcano 模型，核心是一个Planner和一组RelOptRule。Planner 会维护一个“等价计划集合”（RelSet），每个 RelSet 里包含多个逻辑等价的 RelNode。规则会尝试匹配 RelSet 中的节点，如果匹配成功就生成新的节点，加入 RelSet。然后 Planner 会用成本模型比较各个计划的成本，选出最优的。
这个过程会反复迭代，直到没有规则可以应用，或者达到预设的迭代上限。Calcite 内置了大量规则，比如FilterPushDown、ProjectMerge、JoinReorder、AggregateRemove等等。你也可以自定义规则，只要实现RelOptRule接口就行。
成本模型是另一个关键。Calcite 默认的成本模型基于行数和 CPU/IO 代价，但你可以通过RelMetadataProvider提供自己的统计信息。在实际项目里，统计信息的准确性直接决定了优化效果。如果统计信息缺失，Calcite 会退化成基于规则的优化，效果会打折扣。
3.4 执行阶段：适配器接管
优化完成后，Calcite 会生成一个物理计划，通常是一棵PhysicalRel树。然后适配器就登场了。适配器需要把物理计划转换成对底层系统的实际调用。比如 JDBC 适配器会把JdbcTableScan转换成一条 SQL 发给数据库，Elasticsearch 适配器会把ElasticsearchTableScan转换成 ES 查询 DSL。
这个阶段的关键是“下推”。Calcite 会尽量把过滤、投影、聚合等操作下推到数据源，减少数据传输量。但下推不是无条件的，它取决于适配器是否声明支持某个操作。如果适配器不支持，Calcite 会在本地用Enumerable执行器跑。所以适配器的能力声明很重要，声明错了要么下推失败，要么下推了但结果不对。
4. 适配器开发：把 Calcite 接到你的数据源上
4.1 适配器的基本结构
开发一个 Calcite 适配器，核心是实现几个接口。首先是SchemaFactory，负责创建Schema。Schema里包含Table和Function的定义。Table需要提供getRowType方法返回表结构，以及getStatistic方法返回统计信息。然后是TableScan，负责实际读取数据。最后是RelOptTable和RelOptRule，负责把逻辑计划转换成物理计划。
听起来接口不多，但每个接口都有不少细节。比如getRowType返回的RelDataType要跟实际数据匹配，类型不匹配会导致运行时异常。getStatistic返回的行数如果偏差太大，优化器会选错 join 顺序。这些坑我在项目里都踩过，后面会专门写一篇讲适配器开发的注意事项。
4.2 谓词下推的实现要点
谓词下推是适配器开发里最容易出问题的部分。Calcite 会把LogicalFilter里的条件表达式传给你的适配器，你需要判断哪些条件下推、哪些不下推。下推的条件要转换成底层系统能理解的格式，比如 SQL WHERE 子句或者 ES 的 query DSL。
这里有个关键点：不是所有条件都能下推。比如底层系统不支持某个函数，你就不能下推。再比如条件里包含 Calcite 特有的表达式，你也得在本地处理。我的经验是，先实现一个保守的下推策略，只下推简单比较和 AND 组合，等稳定了再逐步扩展。否则很容易出现“下推了但结果不对”的问题，而且这种问题很难排查，因为 SQL 看起来没问题，但结果就是错的。
4.3 元数据与统计信息的获取
元数据是适配器的另一个重点。Calcite 需要知道表有哪些列、列的类型是什么、表有多大、列的选择性如何。这些信息越准确，优化器做出的决策越好。但很多外部系统并不提供这些信息，比如 CSV 文件没有统计信息，REST 接口可能连 schema 都不固定。
这时候你有两个选择：一是手动配置元数据，比如在 Schema 定义里写死列类型和行数；二是实现一个采样机制，先读一部分数据估算统计信息。前者简单但不够灵活，后者复杂但更准确。我在项目里通常先用手动配置跑通流程，再逐步加入采样逻辑。统计信息这块，宁可给一个粗略的估计，也不要给默认值，因为默认值往往会导致优化器做出离谱的决策。
5. 常见问题与排查技巧实录
5.1 解析失败：SQL 方言不匹配
最常见的报错是解析失败，比如Encountered "xxx" at line 1, column 1。这通常是因为 SQL 方言配置不对。Calcite 默认的方言是Lex.MYSQL还是Lex.ORACLE取决于版本，如果你用的 SQL 语法跟默认方言不一致，就会解析失败。解决办法是显式配置SqlParser.Config，指定Lex和大小写敏感策略。
另一个常见原因是标识符引用。比如你用反引号引用表名，但方言配置的是双引号，就会报错。这种问题在跨数据库查询时特别常见，因为不同数据库的引用字符不一样。我的建议是统一用双引号，并在 parser 配置里把quoting设成QuoteStyle.ANSI。
5.2 校验失败：元数据缺失或类型不匹配
校验阶段的报错通常比较明确，比如Table 'xxx' not found或者Column 'yyy' not found。这类问题一般是 Catalog 配置不对，或者 Schema 里没有注册对应的表。检查方法是打印 Catalog 的内容，看看表是否真的注册进去了。
类型不匹配的报错稍微隐蔽一些，比如Cannot apply '>' to arguments of type 'VARCHAR' and 'INTEGER'。这通常是因为列类型定义错了，或者 SQL 里做了隐式类型转换但 Calcite 不支持。解决办法是在 Schema 里把类型定义准确，或者在 SQL 里显式转换。
5.3 优化结果不符合预期：统计信息与规则配置
优化结果不符合预期是最难排查的一类问题。比如你期望 join 顺序是 A join B，但 Calcite 选了 B join A，导致性能很差。这通常是因为统计信息不准确，优化器基于错误的行数估计做出了错误决策。排查方法是打开 Calcite 的 trace 日志，看看优化器在每一步的决策依据是什么。
另一个原因是规则配置。Calcite 默认启用了一大批规则，但有些规则可能不适合你的场景。比如JoinReorder在表很多的时候会消耗大量时间，如果你的查询涉及十几张表，可以考虑关掉这个规则，手动指定 join 顺序。规则配置可以通过RelOptPlanner的addRule和removeRule方法调整。
5.4 运行时异常：适配器实现问题
运行时异常通常出在适配器实现上。比如NullPointerException可能是因为getRowType返回了 null，或者TableScan没有正确处理空结果集。ClassCastException可能是因为类型转换没做检查。这类问题的排查方法是加日志，把适配器接收到的 RelNode 和返回的结果都打出来，看看在哪一步跟预期不一致。
还有一个常见问题是资源泄漏。Calcite 的Enumerable执行器会用到迭代器，如果适配器没有正确关闭连接或释放资源，长时间运行后会出现连接池耗尽的问题。解决办法是在TableScan的implement方法里用 try-with-resources 确保资源释放。
6. 这个专栏后续会讲什么
前面把 Calcite 的整体架构和核心流程过了一遍，后面我会按主题深入。大概的规划是：先讲 SQL 解析和校验的细节，包括如何自定义 SQL 方言、如何处理复杂表达式；然后讲 RelNode 体系和优化器规则，包括如何写自定义规则、如何调试优化过程；接着讲适配器开发，包括 JDBC 适配器、Elasticsearch 适配器、自定义适配器的完整实现；最后讲成本模型和统计信息，包括如何收集统计信息、如何调整成本参数。
每一篇我都会尽量配可运行的代码示例和实际的排查案例。Calcite 的官方文档偏理论，很多实际开发中的坑不会提到，我希望这个专栏能补上这块。如果你在跟着做的时候遇到问题，欢迎把报错和上下文发出来，我会尽量帮忙分析。这个专栏不是教程，更像是一个同行之间的经验分享，我踩过的坑你可以绕过去，我没踩过的坑欢迎你补充。
最后说一句：Calcite 的学习曲线确实陡，但一旦理解了它的设计思路，你会发现很多看似复杂的问题其实有很优雅的解法。我在实际项目中的体会是，不要试图一次性搞懂所有模块，先跑通一条最简单的查询，然后逐步往里加东西，遇到问题再深入源码。这样学起来不会太痛苦，而且每一步都有正反馈。
