时序数据库IoTDB用户自定义函数（UDF）使用指南

1. 编写UDF

时序数据库IoTDB为用户提供了编写UDF的JAVA API，用户可以自主实现UDTF（用户自定义转换函数）类，IoTDB将通过类加载机制装载用户编写的类。

Maven依赖

如果使用Maven，可以从Maven库中搜索以下依赖，并确保依赖版本与目标IoTDB服务器版本相同。以下示例中使用1.0.0版本：

<dependency>
    <groupId>org.apache.iotdb</groupId>
    <artifactId>udf-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

UDTF接口

在完整的UDTF实例生命周期中，各个方法的调用顺序如下：

• validate(UDFParameterValidator validator)：用于检测用户输入的参数是否合法，以及输入时间序列的数据类型是否符合预期。
• beforeStart(UDFParameters parameters, UDTFConfigurations configurations)：必须实现的方法，用于指定UDF访问原始数据的策略和输出结果序列的类型。
• transform(Row row, PointCollector collector) 或 transform(RowWindow rowWindow, PointCollector collector)：根据beforeStart中设置的访问策略调用，用于处理数据转换。
• terminate(PointCollector collector)：在查询结束时调用，用于执行必要的清理工作。
• beforeDestroy()：在UDF实例销毁前调用，用于释放资源。

实现注意事项

• ‌validate接口‌：用于参数验证，例如指定输入时间序列的数量和类型。
• ‌beforeStart接口‌：设置数据访问策略和输出数据类型。
• ‌transform接口‌：根据访问策略处理数据。当使用窗口策略时，需特别注意窗口可能为空，以及避免同一时间戳被多次放入PointCollector。

2. 注册UDF

注册UDF的流程如下：

步骤

1. 实现完整的UDF类。
2. 将项目打包成JAR文件。
3. 根据注册方式进行准备工作：
   • 不指定URI：将JAR包放置到IoTDB服务器的指定目录（如iotdb-server-1.0.0-all-bin/ext/udf，该目录可配置）。
   • 指定URI：将JAR包上传到服务器并确保IoTDB实例能够访问该服务器。
4. 使用SQL语法注册UDF：

CREATE FUNCTION <UDF-NAME> AS <UDF-CLASS-FULL-PATHNAME> (USING URI URI-STRING)?

示例

注册名为example的UDF，以下两种注册方式任选其一：

• 不指定URI：

  CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample'

  需提前将JAR包放置到所有DataNode的指定目录下。
• 指定URI：

  CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample' USING URI 'http://jar/example.jar'

  IoTDB会自动下载并同步JAR包到整个集群。

注意事项

• 1.0.0版本的IoTDB实例不能注册0.13及之前版本的UDF JAR包。
• UDF是通过反射技术动态装载的，无需启停服务器。
• UDF函数名称大小写不敏感，避免与内置函数重名。
• 不同的JAR包中不要有全类名相同但实现逻辑不同的类，以避免SQL执行时行为不一致。