【Apache Doris】自定义函数之 JAVA UDF 详解

一、背景说明

UDF 主要适用于，用户需要的分析能力 Doris 并不具备的场景。用户可以自行根据自己的需求，实现自定义的函数，并且通过 UDF 框架注册到 Doris 中，来扩展 Doris 的能力，并解决用户分析需求。

UDF 能满足的分析需求主要分为两种（本文中的 UDF 指的是二者的统称）：

• UDF（User Defined Function）: 用户自定义函数，这种函数会对单行进行操作，并且输出单行结果。当用户在查询时使用 UDF ，每行数据最终都会出现在结果集中。典型的 UDF 比如字符串操作 concat() 等。
• UDAF（User-Defined Aggregate Functions）: 用户自定义的聚合函数，这种函数对多行进行操作，并且输出单行结果。当用户在查询时使用 UDAF，分组后的每组数据最后会计算出一个值并展结果集中。典型的 UDAF 比如集合操作 sum() 等。一般来说 UDAF 都会结合 group by 一起使用。

正式推出Java UDF 之前，Apache Doris提供了原生 UDF即C++ UDF 。由于是使用 C++ 来编写的，执行效率高、速度更快，但是在实际使用中也会存在一些问题：

• 跟 Doris 代码耦合度高，需要自己打包编译 Doris 源码
• 只支持 C++ 语言并且 UDF 代码出错会影响 Doris 集群稳定性
• 对于只熟悉 Hive和Spark 等大数据组件的用户有一定使用门槛

针对以上问题，Apache Doris 在1.2.0版本中正式推出全新的Java UDF ，让用户可以更便捷高效地开发和迁移UDF。

二、原理简介

众所周知，Doris的FE主要由JAVA编写、而BE是由C++编写。因此，如果需要C++编写的BE与JAVA UDF联动，那么必然需要借助网络通信或JNI（Java Native Interface）：

• 网络通信：可以跨语言交互，但是会带来网络传输等额外的性能开销，PASS。
• JNI：用于在Java程序中调用本地（C/C++）代码。通过JNI，可以将C++代码编译成动态链接库，然后在Java程序中加载该动态链接库，并通过JNI接口进行函数调用和数据传递。

JNI调用需要进行Java与本地代码之间的切换和数据转换，这也会带来一定的性能开销，如果频繁的JNI调用还可能会对应用的性能产生不利影响。那么Doris该如何设计 Java UDF 呢？

1. 开发规范：制定一些开发规范让流程有序且容错率高，例如UDF 类必须具有 evaluate 方法，并且必须是 Public 和 Non-Static 的。
2. 重用JVM：BE 会创建或重用一个 JVM 来调用真正的 Java UDF，保证效率的同时让资源利用率最大化。
3. 向量化执行：执行时是向量化的，可以实现一次执行多行数据只调用一次 JNI，给用户带来更好的性能体验。

下面，就来一起体验下Apache Doris 的 Java UDF吧。

三、环境信息

3.1 硬件信息

• CPU：48C
• 内存：256G

3.2 软件信息

• 系统：CentOS
• JAVA版本：1.8
• Apache Doris版本：2.1 rc01

四、IDE准备

直接IntelliJ IDEA：

五、JAVA UDF开发流程

Java UDF 使用起来非常简单。只需要按规范开发完并通过mvn打成jar包后，在 Apache Doris 内注册一下，即可调用 jar 包来实现 UDF 逻辑：

5.1 源码准备

5.1.1 pom.xml

仅补齐dependencies和build部分。

    <dependencies>
        <dependency>
            <groupId>org.apache.hive</groupId>
            <artifactId>hive-exec</artifactId>
            <version>2.3.5</version>
            <exclusions>
                <exclusion>
                    <groupId>org.pentaho</groupId>
                    <artifactId>*</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <finalName>doris_java_udf</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.2</version>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>org.apache.doris.udf.AddOne</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>3.3.0</version>
                <configuration>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                    <archive>
                        <manifest>
                            <mainClass>org.apache.doris.udf.AddOne</mainClass>
                        </manifest>
                    </archive>
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>8</source>
                    <target>8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

5.1.2 JAVA代码

直接使用官方的demo：
https://github.com/apache/doris/blob/master/samples/doris-demo/java-udf-demo/src/main/java/org/apache/doris/udf/AddOne.java

package org.apache.doris.udf;

import org.apache.hadoop.hive.ql.exec.UDF;

public class AddOne extends UDF {
    public Integer evaluate(Integer value) {
        return value == null? null: value + 1;
    }
}

5.2 mvn打包

5.2.1 clean

先clean清理target。

5.2.2 package

再package打新包。

5.3 函数使用

5.3.1 upload

打好的jar包（即doris_java_udf.jar，不需要传依赖jar包），可以以两种方式存放：

1. 服务化：多机环境时，也可以使用http的方式下载jar包
2. 本地路径：FE、BE节点都要放置，并且都有权限访问的路径。

本文选择本地路径的方式演练：

5.3.2 使用

-- udf
-- 查看
show full functions;

-- 删除
DROP FUNCTION add_one(int);

-- 创建
-- 函数名可自定义
CREATE FUNCTION add_one(int) RETURNS int PROPERTIES (
	-- 文件路径，可本地或http
    "file"="file:///udf/doris_java_udf.jar",
    -- extends UDF 的类名
    "symbol"="org.apache.doris.udf.AddOne",
    -- 可选，如果在计算中对出现的NULL值有特殊处理，确定结果中不会返回NULL，可以设为false
    "always_nullable"="true",
    -- 默认为 Native，使用 Java UDF时传 JAVA_UDF
    "type"="JAVA_UDF"
)

-- 测试，在传参基础上+1，如果非数字或者null则返回null
select add_one('0');

六、注意事项

虽然JAVA UDF整起来非常顺畅方便，但实际生产使用中有如下一些官方提醒：

1. 不支持复杂数据类型（HLL，Bitmap）。
2. 当前允许用户自己指定JVM最大堆大小，BE配置项是jvm_max_heap_size。配置项在BE安装目录下的be.conf全局配置中，默认512M，如果需要聚合数据，建议调大一些，增加性能，减少内存溢出风险。
3. char类型的udf在create function时需要使用String类型。
4. 由于jvm加载同名类的问题，不要同时使用多个同名类作为udf实现，如果想更新某个同名类的udf，需要重启be重新加载classpath。

七、总结

Java UDF相对1.2之前的C++ UDF而言，使用起来会更加便捷高效，而且更利于Hive/Spark的UDF jar包迁移，并且Doris团队对其底层实现流程进行了一系列性能优化，面面俱到。各位看官大可放心使用！