--- { "title": "原生UDF", "language": "zh-CN" } --- # UDF UDF 主要适用于，用户需要的分析能力 Doris 并不具备的场景。用户可以自行根据自己的需求，实现自定义的函数，并且通过 UDF 框架注册到 Doris 中，来扩展 Doris 的能力，并解决用户分析需求。 UDF 能满足的分析需求分为两种：UDF 和 UDAF。本文中的 UDF 指的是二者的统称。 1. UDF: 用户自定义函数，这种函数会对单行进行操作，并且输出单行结果。当用户在查询时使用 UDF ，每行数据最终都会出现在结果集中。典型的 UDF 比如字符串操作 concat() 等。 2. UDAF: 用户自定义的聚合函数，这种函数对多行进行操作，并且输出单行结果。当用户在查询时使用 UDAF，分组后的每组数据最后会计算出一个值并展结果集中。典型的 UDAF 比如集合操作 sum() 等。一般来说 UDAF 都会结合 group by 一起使用。 这篇文档主要讲述了，如何编写自定义的 UDF 函数，以及如何在 Doris 中使用它。 如果用户使用 UDF 功能并扩展了 Doris 的函数分析，并且希望将自己实现的 UDF 函数贡献回 Doris 社区给其他用户使用，这时候请看文档 [Contribute UDF](./contribute-udf.md)。 ## 编写 UDF 函数 在使用UDF之前，用户需要先在 Doris 的 UDF 框架下，编写自己的UDF函数。在`contrib/udf/src/udf_samples/udf_sample.h|cpp`文件中是一个简单的 UDF Demo。 编写一个 UDF 函数需要以下几个步骤。 ### 编写函数 创建对应的头文件、CPP文件，在CPP文件中实现你需要的逻辑。CPP文件中的实现函数格式与UDF的对应关系。 用户可以把自己的 source code 统一放在一个文件夹下。这里以 udf_sample 为例，目录结构如下： ``` └── udf_samples ├── uda_sample.cpp ├── uda_sample.h ├── udf_sample.cpp └── udf_sample.h ``` #### 非可变参数 对于非可变参数的UDF，那么两者之间的对应关系很直接。 比如`INT MyADD(INT, INT)`的UDF就会对应`IntVal AddUdf(FunctionContext* context, const IntVal& arg1, const IntVal& arg2)`。 1. `AddUdf`可以为任意的名字，只要创建UDF的时候指定即可。 2. 实现函数中的第一个参数永远是`FunctionContext*`。实现者可以通过这个结构体获得一些查询相关的内容，以及申请一些需要使用的内存。具体使用的接口可以参考`udf/udf.h`中的定义。 3. 实现函数中从第二个参数开始需要与UDF的参数一一对应，比如`IntVal`对应`INT`类型。这部分的类型都要使用`const`引用。 4. 返回参数与UDF的参数的类型要相对应。 #### 可变参数 对于可变参数，可以参见以下例子，UDF`String md5sum(String, ...)`对应的 实现函数是`StringVal md5sumUdf(FunctionContext* ctx, int num_args, const StringVal* args)` 1. `md5sumUdf`这个也是可以任意改变的，创建的时候指定即可。 2. 第一个参数与非可变参数函数一样，传入的是一个`FunctionContext*`。 3. 可变参数部分由两部分组成，首先会传入一个整数，说明后面还有几个参数。后面传入的是一个可变参数部分的数组。 #### 类型对应关系 |UDF Type|Argument Type| |----|---------| |TinyInt|TinyIntVal| |SmallInt|SmallIntVal| |Int|IntVal| |BigInt|BigIntVal| |LargeInt|LargeIntVal| |Float|FloatVal| |Double|DoubleVal| |Date|DateTimeVal| |Datetime|DateTimeVal| |Char|StringVal| |Varchar|StringVal| |Decimal|DecimalVal| ## 编译 UDF 函数 由于 UDF 实现中依赖了 Doris 的 UDF 框架 , 所以在编译 UDF 函数的时候首先要对 Doris 进行编译，也就是对 UDF 框架进行编译。 编译完成后会生成，UDF 框架的静态库文件。之后引入 UDF 框架依赖，并编译 UDF 即可。 ### 编译Doris 在 Doris 根目录下执行 `sh build.sh` 就会在 `output/udf/` 生成 UDF 框架的静态库文件 `headers|libs` ``` ├── output │   └── udf │   ├── include │   │   ├── uda_test_harness.h │   │   └── udf.h │   └── lib │   └── libDorisUdf.a ``` ### 编写 UDF 编译文件 1. 准备 thirdparty `thirdparty` 文件夹主要用于存放用户 UDF 函数依赖的第三方库，包括头文件及静态库。其中必须包含依赖的 Doris UDF 框架中 `udf.h` 和 `libDorisUdf.a` 这两个文件。 这里以 `udf_sample` 为例, 在 用户自己 `udf_samples` 目录用于存放 source code。在同级目录下再创建一个 `thirdparty` 文件夹用于存放静态库。目录结构如下： ``` ├── thirdparty │ │── include │ │ └── udf.h │ └── lib │ └── libDorisUdf.a └── udf_samples ``` `udf.h` 是 UDF 框架头文件。存放路径为 `doris/output/udf/include/udf.h`。 用户需要将 Doris 编译产出中的这个头文件拷贝到自己的 `thirdparty` 的 include 文件夹下。 `libDorisUdf.a` 是 UDF 框架的静态库。Doris 编译完成后该文件存放在 `doris/output/udf/lib/libDorisUdf.a`。用户需要将该文件拷贝到自己的 `thirdparty` 的 lib 文件夹下。 *注意：UDF 框架的静态库只有完成 Doris 编译后才会生成。 2. 准备编译 UDF 的 CMakeFiles.txt CMakeFiles.txt 用于声明 UDF 函数如何进行编译。存放在源码文件夹下，与用户代码平级。这里以 `udf_samples` 为例目录结构如下: ``` ├── thirdparty └── udf_samples ├── CMakeLists.txt ├── uda_sample.cpp ├── uda_sample.h ├── udf_sample.cpp └── udf_sample.h ``` + 需要显示声明引用 `libDorisUdf.a` + 声明 `udf.h` 头文件位置 以 udf_sample 为例 ``` # Include udf include_directories(thirdparty/include) # Set all libraries add_library(udf STATIC IMPORTED) set_target_properties(udf PROPERTIES IMPORTED_LOCATION thirdparty/lib/libDorisUdf.a) # where to put generated libraries set(LIBRARY_OUTPUT_PATH "${BUILD_DIR}/src/udf_samples") # where to put generated binaries set(EXECUTABLE_OUTPUT_PATH "${BUILD_DIR}/src/udf_samples") add_library(udfsample SHARED udf_sample.cpp) target_link_libraries(udfsample udf -static-libstdc++ -static-libgcc ) add_library(udasample SHARED uda_sample.cpp) target_link_libraries(udasample udf -static-libstdc++ -static-libgcc ) ``` 如果用户的 UDF 函数还依赖了其他的三方库，则需要声明 include，lib，并在 `add_library` 中增加依赖。 所有文件准备齐后完整的目录结构如下： ``` ├── thirdparty │ │── include │ │ └── udf.h │ └── lib │ └── libDorisUdf.a └── udf_samples ├── CMakeLists.txt ├── uda_sample.cpp ├── uda_sample.h ├── udf_sample.cpp └── udf_sample.h ``` 准备好上述文件就可以直接编译 UDF 了 ### 执行编译 在 udf_samples 文件夹下创建一个 build 文件夹，用于存放编译产出。 在 build 文件夹下运行命令 `cmake ../` 生成Makefile，并执行 make 就会生成对应动态库。 ``` ├── thirdparty ├── udf_samples └── build ``` ### 编译结果 编译完成后的 UDF 动态链接库就生成成功了。在 `build/src/` 下，以 udf_samples 为例，目录结构如下： ``` ├── thirdparty ├── udf_samples └── build └── src └── udf_samples ├── libudasample.so    └── libudfsample.so ``` ## 创建 UDF 函数 通过上述的步骤后，你可以得到 UDF 的动态库（也就是编译结果中的 `.so` 文件）。你需要将这个动态库放到一个能够通过 HTTP 协议访问到的位置。 然后登录 Doris 系统，在 mysql-client 中通过 `CREATE FUNCTION` 语法创建 UDF 函数。你需要拥有ADMIN权限才能够完成这个操作。这时 Doris 系统内部就会存在刚才创建好的 UDF。 ``` CREATE [AGGREGATE] FUNCTION name ([argtype][,...]) [RETURNS] rettype PROPERTIES (["key"="value"][,...]) ``` 说明： 1. PROPERTIES中`symbol`表示的是，执行入口函数的对应symbol，这个参数是必须设定。你可以通过`nm`命令来获得对应的symbol，比如`nm libudfsample.so | grep AddUdf`获得到的`_ZN9doris_udf6AddUdfEPNS_15FunctionContextERKNS_6IntValES4_`就是对应的symbol。 2. PROPERTIES中`object_file`表示的是从哪里能够下载到对应的动态库，这个参数是必须设定的。 3. name: 一个function是要归属于某个DB的，name的形式为`dbName`.`funcName`。当`dbName`没有明确指定的时候，就是使用当前session所在的db作为`dbName`。 具体使用可以参见 `CREATE FUNCTION` 获取更详细信息。 ## 使用 UDF 用户使用 UDF 必须拥有对应数据库的 `SELECT` 权限。 UDF 的使用与普通的函数方式一致，唯一的区别在于，内置函数的作用域是全局的，而 UDF 的作用域是 DB内部。当链接 session 位于数据内部时，直接使用 UDF 名字会在当前DB内部查找对应的 UDF。否则用户需要显示的指定 UDF 的数据库名字，例如 `dbName`.`funcName`。 ## 删除 UDF函数 当你不再需要 UDF 函数时，你可以通过下述命令来删除一个 UDF 函数, 可以参考 `DROP FUNCTION`。