扩展 Calcite 中的 SQL 解析语法

Calcite中 JavaCC 的使用方法

Calcite 默认采用 JavaCC 来生成词法分析器和语法分析器。

1）使用 JavaCC 解析器

Calcite中，JavaCC 的依赖已经被封装到 calcite-core 模块当中，如果使用 Maven 作为依赖管理工具，只需要添加对应的calcite-core模块坐标即可。

<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-core</artifactId>
    <version>1.26.0</version>
</dependency>

在代码中，可以直接使用 Calcite 的 SqlParser 接口调用对应的语法解析流程，对相关的 SQL 语句进行解析。

解析流程：

// SQL语句
String sql = "select * from t_user where id = 1";

// 解析配置
SqlParser.Config mysqlConfig = SqlParser.config().withLex(Lex.MYSQL);

// 创建解析器
SqlParser parser = SqlParser.create(sql, mysqlConfig);

// 解析SQL语句
SqlNode sqlNode = parser.parseQuery();

System.out.println(sqlNode.toString());

2）自定义语法

有时需要扩展一些新的语法操作，以数仓的操作——Load作为例子，介绍如何自定义语法。

Load操作时将数据从一种数据源导入另一种数据源中，Load操作采用的语法模板如下。

LOAD sourceType:obj TO targetType:obj 
(fromCol toCol (,fromCol toCol)*) 
[SEPARATOR '\t']

其中，sourceType 和 targetType 表示数据源类型，obj表示这些数据源的数据对象，(fromCol toCol)表示字段名映射，文件里面的第一行是表头，分隔符默认是制表符。

Load语句示例：

LOAD hdfs:'/data/user.txt' TO mysql:'db.t_user' (name name,age age) SEPARATOR ',';

在真正实现时，有两种选择。

一种是直接修改Calcite的源码，在其本身的模板文件（Parser.jj）内部添加对应的语法逻辑，然后重新编译。

但是这种方式的弊端非常明显，即对Calcite本身的源码侵入性太强。

另一种利用模板引擎来扩展语法文件，模板引擎可将扩展的语法提取到模板文件外面，以达到程序解耦的目的。

在实现层面，Calcite用到了FreeMarker，它是一个模板引擎，按照FreeMarker定义的模板语法，可以通过其提供的 Java API 设置值来替换模板中的占位符。

如下展示了 Calcite 通过模板引擎添加语法逻辑相关的文件结构，其源码将 Parser.jj 这个语法文件定义为模板，将 includes 目录下的.ftl文件作为扩展文件，最后统一通过config.fmpp来配置。

具体添加语法的操作可以分为3个步骤：

编写新的 JavaCC 语法文件；

修改config.fmpp文件，配置自定义语法；

编译模板文件和语法文件。

1.编写新的 JavaCC 语法文件

不需要修改Parser.jj文件，只需要修改includes目录下的.ftl文件，对于前文提出的Load操作，只需要在parserImpls.ftl文件里增加Load对应的语法。

在编写语法文件之前，先要从代码的角度，用面向对象的思想将最终结果定下来，也就是最后希望得到的一个SqlNode节点。

抽象Load语句内容并封装后，得到SqlLoad，继承SqlCall，表示一个操作，Load操作里的数据源和目标源是同样的结构，所以封装SqlLoadSource，而字段映射可以用一个列表来封装，SqlColMapping仅仅包含一堆列映射，SqlNodeList代表节点列表。

扩展SqlLoad的代码实现：

// 扩展SqlLoad的代码实现
public class SqlLoad extends SqlCall {
    // 来源信息
    private SqlLoadSource source;
    // 终点信息
    private SqlLoadSource target;
    // 列映射关系
    private SqlNodeList colMapping;
    // 分隔符
    private String separator;

    // 构造方法
    public SqlLoad(SqlParserPos pos) {
        super(pos);
    }
		
		// 扩展的构造方法
    public SqlLoad(SqlParserPos pos, 
                   SqlLoadSource source, 
                   SqlLoadSource target, 
                   SqlNodeList colMapping,
                   String separator) {
        super(pos);
        this.source = source;
        this.target = target;
        this.colMapping = colMapping;
        this.separator = separator;
    }
}

由于Load操作涉及两个数据源，因此也需要对数据源进行定义。

Load语句中数据源的定义类：

/**
 * 定义Load语句中的数据源信息
 */
@Data
@AllArgsConstructor
public class SqlLoadSource {
    private SqlIdentifier type;
    private String obj;
}

Load语句中出现的字段映射关系也需要定义。

对Load语句中的字段映射关系进行定义：

// 对Load语句中的字段映射关系进行定义
public class SqlColMapping extends SqlCall {
    // 操作类型
    protected static final SqlOperator OPERATOR =
            new SqlSpecialOperator("SqlColMapping", SqlKind.OTHER);
    private SqlIdentifier fromCol;
    private SqlIdentifier toCol;
    
    public SqlColMapping(SqlParserPos pos) {
        super(pos);
		}
		
    // 构造方法
    public SqlColMapping(SqlParserPos pos, 
                         SqlIdentifier fromCol, 
                         SqlIdentifier toCol) {
        super(pos);
        this.fromCol = fromCol;
        this.toCol = toCol;
    }
}

为了输出SQL语句，还需要重写unparse方法。

unparse方法定义：

/**
 * 定义unparse方法
 */
@Override
public void unparse(SqlWriter writer, int leftPrec, int rightPrec) {
    writer.keyword("LOAD");
		source.getType().unparse(writer, leftPrec, rightPrec);
		
    writer.keyword(":");
    writer.print("'" + source.getObj() + "' ");
    writer.keyword("TO");
    target.getType().unparse(writer, leftPrec, rightPrec);
    
    writer.keyword(":");
    writer.print("'" + target.getObj() + "' ");
    
    final SqlWriter.Frame frame = writer.startList("(", ")");
    for (SqlNode n : colMapping.getList()) {
        writer.newlineAndIndent();
        writer.sep(",", false);
        n.unparse(writer, leftPrec, rightPrec);
    }
    
    writer.endList(frame);
    writer.keyword("SEPARATOR");
    writer.print("'" + separator + "'");
}

当需要的 SqlNode 节点类定义好后，就可以开始编写语法文件了，Load语法没有多余分支结构，只有列映射用到了循环，可能有多个列。

parserImpls.ftl文件中添加语法逻辑的代码示例：

// 节点定义，返回我们定义的节点
SqlNode SqlLoad() :
{
    SqlParserPos pos; // 解析定位
    SqlIdentifier sourceType; // 源类型用一个标识符节点表示
    String sourceObj; // 源路径表示为一个字符串，比如“/path/xxx”
    SqlIdentifier targetType;
    String targetObj;
    SqlParserPos mapPos;
    SqlNodeList colMapping;
    SqlColMapping colMap;
    String separator = "\t";
}
{
// LOAD语法没有多余分支结构，“一条线下去”，获取相应位置的内容并保存到变量中
<LOAD>
    {
        pos = getPos();
    }
    
sourceType = CompoundIdentifier()

<COLON> // 冒号和圆括号在Calcite原生的解析文件里已经定义，我们也能使用
    sourceObj = StringLiteralValue()
<TO>
    targetType = CompoundIdentifier()
<COLON>
    targetObj = StringLiteralValue()
    {
        mapPos = getPos();
    }
<LPAREN>
    {
        colMapping = new SqlNodeList(mapPos);
        colMapping.add(readOneColMapping());
    }
    (
<COMMA>
        {
            colMapping.add(readOneColMapping());
        }
    )*
    
<RPAREN>
[<SEPARATOR> separator=StringLiteralValue()]

// 最后构造SqlLoad对象并返回
    {
        return new SqlLoad(pos, new SqlLoadSource(sourceType, sourceObj),
               new SqlLoadSource(targetType, targetObj), colMapping, separator);
    }
}

// 提取出字符串节点的内容函数
JAVACODE String StringLiteralValue() {
    SqlNode sqlNode = StringLiteral();
    return ((NlsString) SqlLiteral.value(sqlNode)).getValue();
}

SqlNode readOneColMapping():
{
    SqlIdentifier fromCol;
    SqlIdentifier toCol;
    SqlParserPos pos;
}
{
    { pos = getPos();}
    fromCol = SimpleIdentifier()
		toCol = SimpleIdentifier()
    {
        return new SqlColMapping(pos, fromCol, toCol);
    }
}

2.修改config.fmpp文件，配置自定义语法

需要将 Calcite 源码中的 config.fmpp 文件复制到项目的 src/main/codegen 目录下，然后修改里面的内容，来声明扩展的部分。

config.fmpp文件的定义示例：

data: {
    parser: {
        # 生成的解析器包路径
        package: "cn.com.ptpress.cdm.parser.extend",
        # 解析器名称
        class: "CdmSqlParserImpl",
				# 引入的依赖类
        imports: [
            "cn.com.ptpress.cdm.parser.load.SqlLoad",
            "cn.com.ptpress.cdm.parser.load.SqlLoadSource"
            "cn.com.ptpress.cdm.parser.load.SqlColMapping"
        ]
        # 新的关键字
        keywords: [
            "LOAD",
            "SEPARATOR"
        ]
        # 新增的语法解析方法
        statementParserMethods: [
            "SqlLoad()"
        ]
        # 包含的扩展语法文件
        implementationFiles: [
            "parserImpls.ftl"
        ]
    }
}
# 扩展文件的目录
freemarkerLinks: {
    includes: includes/
}

3.编译模板文件和语法文件

在这个过程当中，需要将模板Parser.jj文件编译成真正的Parser.jj文件，然后根据Parser.jj文件生成语法解析代码。

利用Maven插件来完成这个任务，具体操作可以分为2个阶段：初始化和编译。

初始化阶段通过resources插件将codegen目录加入编译资源，然后通过dependency插件把calcite-core包里的Parser.jj文件提取到构建目录中。

编译所需插件的配置方式：

<plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
		<execution>
            <phase>initialize</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
        </execution>
    </executions>
    
    <configuration>
        <outputDirectory>${basedir}/target/codegen</outputDirectory>
        <resources>
            <resource>
                <directory>src/main/codegen</directory>
                <filtering>false</filtering>
            </resource>
        </resources>
    </configuration>
</plugin>

<plugin>
    <!--从calcite-core.jar提取解析器语法模板，并放入FreeMarker模板所在的目录-->
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
		<version>2.8</version>
    <executions>
        <execution>
            <id>unpack-parser-template</id>
            <phase>initialize</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>org.apache.calcite</groupId>
                        <artifactId>calcite-core</artifactId>
                        <version>1.26.0</version>
                        <type>jar</type>
                        <overWrite>true</overWrite>
                        <outputDirectory>${project.build.directory}/</outputDirectory>
                        <includes>**/Parser.jj</includes>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
			</executions>
</plugin>

这2个插件可以通过“mvn initialize”命令进行测试。

运行成功后可以看到target目录下有了codegen目录，并且多了本没有编写的Parser.jj文件。

然后就是编译阶段，利用FreeMarker模板提供的插件，根据config.fmpp编译Parser.jj模板，声明config.fmpp文件路径模板和输出目录，在Maven的generate-resources阶段运行该插件。

FreeMarker在pom.xml文件中的配置方式：

<plugin>
    <configuration>
        <cfgFile>${project.build.directory}/codegen/config.fmpp</cfgFile>
        <outputDirectory>target/generated-sources</outputDirectory>
        <templateDirectory>
            ${project.build.directory}/codegen/templates
        </templateDirectory>
    </configuration>
    <groupId>com.googlecode.fmpp-maven-plugin</groupId>
    <artifactId>fmpp-maven-plugin</artifactId>
    <version>1.0</version>
    <dependencies>
        <dependency>
            <groupId>org.freemarker</groupId>
            <artifactId>freemarker</artifactId>
            <version>2.3.28</version>
        </dependency>
    </dependencies>
    <executions>
				<execution>
            <id>generate-fmpp-sources</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

运行“mvn generate-resources”命令就可以生成真正的Parser.jj文件。

最后一步就是编译语法文件，使用JavaCC插件即可完成。

JavaCC插件配置方式：

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>javacc-maven-plugin</artifactId>
    <version>2.6</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <id>javacc</id>
            <goals>
                <goal>javacc</goal>
            </goals>
            <configuration>
                <sourceDirectory>
                    ${basedir}/target/generated-sources/
                </sourceDirectory>
                <includes>
                    <include>**/Parser.jj</include>
								</includes>
                <lookAhead>2</lookAhead>
                <isStatic>false</isStatic>
                <outputDirectory>${basedir}/src/main/java</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

注意这里的I/O目录，直接将生成的代码放在了项目里。

看起来上面每个阶段用了好几个命令，其实只需要一个Maven命令即可完成所有步骤，即“mvn generate-resources”，该命令包含以上2个操作，4个插件都会被执行。

完成编译后，就可以测试新语法，在测试代码里配置生成的解析器类，然后写一条简单的Load语句。

4.测试Load语句的示例代码

String sql = "LOAD hdfs:'/data/user.txt' TO mysql:'db.t_user' (c1 c2,c3 c4) SEPARATOR ','";

// 解析配置
SqlParser.Config mysqlConfig = SqlParser.config()
        // 使用解析器类
        .withParserFactory(CdmSqlParserImpl.FACTORY)
        .withLex(Lex.MYSQL);

SqlParser parser = SqlParser.create(sql, mysqlConfig);

SqlNode sqlNode = parser.parseQuery();

System.out.println(sqlNode.toString());

输出的结果正是重写的unparse方法所输出的。

通过unparse方法输出的结果：

LOAD 'hdfs': '/data/user.txt' TO 'mysql': 'db.t_user' 
('c1' 'c2', 'c3' 'c4') 
SEPARATOR ','