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, ProcessTableFunction, 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:

  • Constructor Details

    • UserDefinedFunction

      public UserDefinedFunction()

  • Method Details

    • 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