MAPREDUCE服务 MRS-IoTDB UDF概述:UDTF（User Defined Timeseries Generating Function）

时间：2024-06-12 19:16:30

UDTF（User Defined Timeseries Generating Function）

编写一个UDTF需要继承“org.apache.iotdb.db.query.udf.api.UDTF”类，并至少实现“beforeStart”方法和一种“transform”方法。

表2是所有可供用户实现的接口说明。

表2 接口说明
接口定义	描述	是否必须
void validate(UDFParameterValidator validator) throws Exception	在初始化方法“beforeStart”调用前执行，用于检测“UDFParameters”中用户输入的参数是否合法。	否
void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception	初始化方法，在UDTF处理输入数据前，调用用户自定义的初始化行为。用户每执行一次UDTF查询，框架就会构造一个新的UDF类实例，该方法在每个UDF类实例被初始化时调用一次。在每一个UDF类实例的生命周期内，该方法只会被调用一次。	是
void transform(Row row, PointCollector collector) throws Exception	该方法由框架调用。当在“beforeStart”中选择以“RowByRowAccessStrategy”的策略消费原始数据时，这个数据处理方法就会被调用。输入参数以“Row”的形式传入，输出结果通过“PointCollector”输出。需要在该方法内自行调用“collector”提供的数据收集方法，以决定最终的输出数据。	与“transform(RowWindow rowWindow, PointCollector collector) ”方法二选一
void transform(RowWindow rowWindow, PointCollector collector) throws Exception	该方法由框架调用。当在“beforeStart”中选择以“SlidingSizeWindowAccessStrategy”或者“SlidingTimeWindowAccessStrategy”的策略消费原始数据时，这个数据处理方法就会被调用。输入参数以“RowWindow”的形式传入，输出结果通过“PointCollector”输出。需要在该方法内自行调用“collector”提供的数据收集方法，以决定最终的输出数据。	与“transform(Row row, PointCollector collector)”方法二选一
void terminate(PointCollector collector) throws Exception	该方法由框架调用。该方法会在所有的“transform”调用执行完成后，在“beforeDestory”方法执行前被调用。在一个UDF查询过程中，该方法会且只会调用一次。需要在该方法内自行调用“collector”提供的数据收集方法，以决定最终的输出数据。	否
void beforeDestroy()	UDTF的结束方法。此方法由框架调用，并且只会被调用一次，即在处理完最后一条记录之后被调用。	否

调用顺序：

void validate(UDFParameterValidator validator) throws Exception
void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception
void transform(Row row, PointCollector collector) throws Exception或者void transform(RowWindow rowWindow, PointCollector collector) throws Exception
void terminate(PointCollector collector) throws Exception
void beforeDestroy()

框架每执行一次UDTF查询，都会构造一个全新的UDF类实例，查询结束时，对应的UDF类实例即被销毁，因此不同UDTF查询（即使是在同一个SQL语句中）UDF类实例内部的数据都是隔离的。用户可以放心地在UDTF中维护一些状态数据，无需考虑并发对UDF类实例内部状态数据的影响。

使用方法：

void validate(UDFParameterValidator validator) throws Exception
“validate”方法能够对用户输入的参数进行验证。

在该方法中限制输入序列的数量和类型，检查用户输入的属性或者进行自定义逻辑的验证。

void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception
“beforeStart”方法有以下作用：
- 帮助用户解析SQL语句中的UDF参数。
- 配置UDF运行时必要的信息，即指定UDF访问原始数据时采取的策略和输出结果序列的类型。
- 创建资源，比如建立外部链接，打开文件等。

上一篇：MAPREDUCE服务 MRS-IoTDB UDF概述:UDFParameters

下一篇：MAPREDUCE服务 MRS-IoTDB UDF概述:UDFParameters