Package org.apache.iotdb.udf.api

Interface UDTF

All Superinterfaces:

UDF

public interface UDTF
extends UDF

User-defined Time-series Generating Function (UDTF)

New UDTF classes need to inherit from this UDTF class.

Generates a variable number of output data points for a single input row or a single input window (time-based or size-based).

A complete UDTF needs to override at least the following methods:

• beforeStart(UDFParameters, UDTFConfigurations)
• transform(RowWindow, PointCollector) or transform(Row, PointCollector)

In the life cycle of a UDTF instance, the calling sequence of each method is as follows:

1. UDF.validate(UDFParameterValidator) 2. beforeStart(UDFParameters, UDTFConfigurations) 3. transform(RowWindow, PointCollector) or transform(Row, PointCollector) 4. terminate(PointCollector) 5. UDF.beforeDestroy()

The query engine will instantiate an independent UDTF instance for each udf query column, and different UDTF instances will not affect each other.

Method Summary

Modifier and Type	Method	Description
void	beforeStart(UDFParameters parameters, UDTFConfigurations configurations)	This method is mainly used to customize UDTF.
default void	terminate(PointCollector collector)	This method will be called once after all calls or {@link UDTF#transform(RowWindow, PointCollector) calls have been executed. In a single UDF query, this method will and will only be called once.
default java.lang.Object	transform(Row row)	When the user specifies MappableRowByRowAccessStrategy to access the original data in UDTFConfigurations, this method will be called to process the transformation.
default void	transform(Row row, PointCollector collector)	When the user specifies RowByRowAccessStrategy to access the original data in UDTFConfigurations, this method will be called to process the transformation.
default void	transform(RowWindow rowWindow, PointCollector collector)	When the user specifies SlidingSizeWindowAccessStrategy or SlidingTimeWindowAccessStrategy to access the original data in UDTFConfigurations, this method will be called to process the transformation.

Methods inherited from interface org.apache.iotdb.udf.api.UDF

beforeDestroy, validate

Method Detail

beforeStart

void beforeStart(UDFParameters parameters,
                 UDTFConfigurations configurations)
          throws java.lang.Exception

This method is mainly used to customize UDTF. In this method, the user can do the following things:

• Use UDFParameters to get the time series paths and parse key-value pair attributes entered by the user.
• Set the strategy to access the original data and set the output data type in UDTFConfigurations.
• Create resources, such as establishing external connections, opening files, etc.

This method is called after the UDTF is instantiated and before the beginning of the transformation process.

Parameters:

parameters - used to parse the input parameters entered by the user

configurations - used to set the required properties in the UDTF

Throws:

java.lang.Exception - the user can throw errors if necessary

transform

default void transform(Row row,
                       PointCollector collector)
                throws java.lang.Exception

When the user specifies RowByRowAccessStrategy to access the original data in UDTFConfigurations, this method will be called to process the transformation. In a single UDF query, this method may be called multiple times.

Parameters:

row - original input data row (aligned by time)

collector - used to collect output data points

Throws:

java.lang.Exception - the user can throw errors if necessary

See Also:

RowByRowAccessStrategy

transform

default void transform(RowWindow rowWindow,
                       PointCollector collector)
                throws java.lang.Exception

When the user specifies SlidingSizeWindowAccessStrategy or SlidingTimeWindowAccessStrategy to access the original data in UDTFConfigurations, this method will be called to process the transformation. In a single UDF query, this method may be called multiple times.

Parameters:

rowWindow - original input data window (rows inside the window are aligned by time)

collector - used to collect output data points

Throws:

java.lang.Exception - the user can throw errors if necessary

See Also:

SlidingSizeWindowAccessStrategy, SlidingTimeWindowAccessStrategy

transform

default java.lang.Object transform(Row row)
                            throws java.lang.Exception

When the user specifies MappableRowByRowAccessStrategy to access the original data in UDTFConfigurations, this method will be called to process the transformation. In a single UDF query, this method may be called multiple times.

Parameters:

row - original input data row (aligned by time)

Throws:

java.lang.Exception - the user can throw errors if necessary

See Also:

MappableRowByRowAccessStrategy

terminate

default void terminate(PointCollector collector)
                throws java.lang.Exception

This method will be called once after all calls or {@link UDTF#transform(RowWindow, PointCollector) calls have been executed. In a single UDF query, this method will and will only be called once.

Parameters:

collector - used to collect output data points

Throws:

java.lang.Exception - the user can throw errors if necessary