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

news2025/1/16 21:59:33

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

一、背景说明
二、原理简介
三、环境信息
- 3.1 硬件信息
- 3.2 软件信息
四、IDE准备
五、JAVA UDF开发流程
- 5.1 源码准备
- - 5.1.1 pom.xml
  - 5.1.2 JAVA代码
- 5.2 mvn打包
- - 5.2.1 clean
  - 5.2.2 package
- 5.3 函数使用
- - 5.3.1 upload
  - 5.3.2 使用
六、注意事项
七、总结

一、背景说明

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 呢？

开发规范：制定一些开发规范让流程有序且容错率高，例如UDF 类必须具有 evaluate 方法，并且必须是 Public 和 Non-Static 的。
重用JVM：BE 会创建或重用一个 JVM 来调用真正的 Java UDF，保证效率的同时让资源利用率最大化。
向量化执行：执行时是向量化的，可以实现一次执行多行数据只调用一次 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包），可以以两种方式存放：

服务化：多机环境时，也可以使用http的方式下载jar包
本地路径：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整起来非常顺畅方便，但实际生产使用中有如下一些官方提醒：

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