Package org.apache.flink.table.functions

Class UserDefinedFunction

java.lang.Object

org.apache.flink.table.functions.UserDefinedFunction

All Implemented Interfaces:

Serializable, FunctionDefinition

Direct Known Subclasses:

AsyncScalarFunction, AsyncTableFunction, ImperativeAggregateFunction, ScalarFunction, TableFunction

@PublicEvolving
public abstract class UserDefinedFunction
extends Object
implements FunctionDefinition, Serializable

Base class for all user-defined functions.

User-defined functions combine the logical definition of a function for validation and planning (see FunctionDefinition) and contain a corresponding runtime implementation.

A runtime implementation might be called at two different stages:

• During planning (i.e. pre-flight phase): If a function is called with constant expressions or constant expressions can be derived from the given statement, a function is pre-evaluated for constant expression reduction and might not be executed on the cluster anymore. Use FunctionDefinition.isDeterministic() to disable constant expression reduction in this case. For example, the following calls to ABS are executed during planning: SELECT ABS(-1) FROM t and SELECT ABS(field) FROM t WHERE field = -1.
• During runtime (i.e. cluster execution): If a function is called with non-constant expressions or FunctionDefinition.isDeterministic() returns false.

See Also:

ScalarFunction, AsyncScalarFunction, TableFunction, AsyncTableFunction, AggregateFunction, TableAggregateFunction, Serialized Form

Constructor Summary

Constructors

Constructor	Description
UserDefinedFunction()

Method Summary

Modifier and Type	Method	Description
void	close()	Tear-down method for user-defined function.
String	functionIdentifier()	Returns a unique, serialized representation for this function.
abstract TypeInference	getTypeInference(DataTypeFactory typeFactory)	Returns the logic for performing type inference of a call to this function definition.
void	open(FunctionContext context)	Setup method for user-defined function.
String	toString()	Returns the name of the UDF that is used for plan explanation and logging.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.flink.table.functions.FunctionDefinition

getKind, getRequirements, isDeterministic, supportsConstantFolding

Constructor Detail

UserDefinedFunction

public UserDefinedFunction()

Method Detail

functionIdentifier

public final String functionIdentifier()

Returns a unique, serialized representation for this function.

open

public void open(FunctionContext context)
          throws Exception

Setup method for user-defined function. It can be used for initialization work. By default, this method does nothing.

Throws:

Exception

close

public void close()
           throws Exception

Tear-down method for user-defined function. It can be used for clean up work. By default, this method does nothing.

Throws:

Exception

getTypeInference

public abstract TypeInference getTypeInference(DataTypeFactory typeFactory)

Returns the logic for performing type inference of a call to this function definition.

The type inference process is responsible for inferring unknown types of input arguments, validating input arguments, and producing result types. The type inference process happens independent of a function body. The output of the type inference is used to search for a corresponding runtime implementation.

Instances of type inference can be created by using TypeInference.newBuilder().

See BuiltInFunctionDefinitions for concrete usage examples.

The type inference for user-defined functions is automatically extracted using reflection. It does this by analyzing implementation methods such as eval() or accumulate() and the generic parameters of a function class if present. If the reflective information is not sufficient, it can be supported and enriched with DataTypeHint and FunctionHint annotations.

Note: Overriding this method is only recommended for advanced users. If a custom type inference is specified, it is the responsibility of the implementer to make sure that the output of the type inference process matches with the implementation method:

The implementation method must comply with each DataType.getConversionClass() returned by the type inference. For example, if DataTypes.TIMESTAMP(3).bridgedTo(java.sql.Timestamp.class) is an expected argument type, the method must accept a call eval(java.sql.Timestamp).

Regular Java calling semantics (including type widening and autoboxing) are applied when calling an implementation method which means that the signature can be eval(java.lang.Object).

The runtime will take care of converting the data to the data format specified by the DataType.getConversionClass() coming from the type inference logic.

Specified by:

getTypeInference in interface FunctionDefinition

toString

public String toString()

Returns the name of the UDF that is used for plan explanation and logging.

Overrides:

toString in class Object