Class TableFunction<T>
- java.lang.Object
-
- org.apache.flink.table.functions.UserDefinedFunction
-
- org.apache.flink.table.functions.TableFunction<T>
-
- Type Parameters:
T
- The type of the output row. Either an explicit composite type or an atomic type that is implicitly wrapped into a row consisting of one field.
- All Implemented Interfaces:
Serializable
,FunctionDefinition
- Direct Known Subclasses:
BuiltInTableFunction
,CsvTableSource.CsvLookupFunction
,LookupFunction
,PythonTableFunction
,TemporalTableFunction
@PublicEvolving public abstract class TableFunction<T> extends UserDefinedFunction
Base class for a user-defined table function. A user-defined table function maps zero, one, or multiple scalar values to zero, one, or multiple rows (or structured types). If an output record consists of only one field, the structured record can be omitted, and a scalar value can be emitted that will be implicitly wrapped into a row by the runtime.The behavior of a
TableFunction
can be defined by implementing a custom evaluation method. An evaluation method must be declared publicly, not static, and namedeval
. Evaluation methods can also be overloaded by implementing multiple methods namedeval
.By default, input and output data types are automatically extracted using reflection. This includes the generic argument
T
of the class for determining an output data type. Input arguments are derived from one or moreeval()
methods. If the reflective information is not sufficient, it can be supported and enriched withDataTypeHint
andFunctionHint
annotations.The following examples show how to specify a table function:
{@code // a function that accepts an arbitrary number of INT arguments and emits them as implicit ROW < INT > class FlattenFunction extends TableFunction
{ public void eval(Integer... args) { for (Integer i : args) { collect(i); } } } // a function that accepts either INT or STRING and emits them as implicit ROW < STRING > class DuplicatorFunction extends TableFunction { public void eval(Integer i) { eval(String.valueOf(i)); } public void eval(String s) { collect(s); collect(s); } } // a function that produces a ROW < i INT, s STRING > from arguments, the function hint helps in // declaring the row's fields - See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description TableFunction()
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected void
collect(T row)
Emits an (implicit or explicit) output row.void
finish()
This method is called at the end of data processing.FunctionKind
getKind()
Returns the kind of function this definition describes.TypeInformation<?>[]
getParameterTypes(Class<?>[] signature)
Deprecated.This method uses the old type system and is based on the old reflective extraction logic.TypeInformation<T>
getResultType()
Deprecated.This method uses the old type system and is based on the old reflective extraction logic.TypeInference
getTypeInference(DataTypeFactory typeFactory)
Returns the logic for performing type inference of a call to this function definition.void
setCollector(Collector<T> collector)
Internal use.-
Methods inherited from class org.apache.flink.table.functions.UserDefinedFunction
close, functionIdentifier, open, toString
-
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
getRequirements, isDeterministic, supportsConstantFolding
-
-
-
-
Method Detail
-
setCollector
public final void setCollector(Collector<T> collector)
Internal use. Sets the current collector.
-
getResultType
@Deprecated public TypeInformation<T> getResultType()
Deprecated.This method uses the old type system and is based on the old reflective extraction logic. The method will be removed in future versions and is only called when using the deprecatedTableEnvironment.registerFunction(...)
method. The new reflective extraction logic (possibly enriched withDataTypeHint
andFunctionHint
) should be powerful enough to cover most use cases. For advanced users, it is possible to overrideUserDefinedFunction.getTypeInference(DataTypeFactory)
.Returns the result type of the evaluation method.
-
getParameterTypes
@Deprecated public TypeInformation<?>[] getParameterTypes(Class<?>[] signature)
Deprecated.This method uses the old type system and is based on the old reflective extraction logic. The method will be removed in future versions and is only called when using the deprecatedTableEnvironment.registerFunction(...)
method. The new reflective extraction logic (possibly enriched withDataTypeHint
andFunctionHint
) should be powerful enough to cover most use cases. For advanced users, it is possible to overrideUserDefinedFunction.getTypeInference(DataTypeFactory)
.ReturnsTypeInformation
about the operands of the evaluation method with a given signature.
-
collect
protected final void collect(T row)
Emits an (implicit or explicit) output row.If null is emitted as an explicit row, it will be skipped by the runtime. For implicit rows, the row's field will be null.
- Parameters:
row
- the output row
-
getKind
public final FunctionKind getKind()
Description copied from interface:FunctionDefinition
Returns the kind of function this definition describes.
-
getTypeInference
public TypeInference getTypeInference(DataTypeFactory typeFactory)
Description copied from class:UserDefinedFunction
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 withDataTypeHint
andFunctionHint
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, ifDataTypes.TIMESTAMP(3).bridgedTo(java.sql.Timestamp.class)
is an expected argument type, the method must accept a calleval(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 interfaceFunctionDefinition
- Specified by:
getTypeInference
in classUserDefinedFunction
-
finish
public void finish() throws Exception
This method is called at the end of data processing. After this method is called, no more records can be produced for the downstream operators.NOTE:This method does not need to close any resources. You should release external resources in the
UserDefinedFunction.close()
method. More details can seeStreamOperator#finish()
.Important:Emit record in the
UserDefinedFunction.close()
method is impossible since flink-1.14, if you need to emit records at the end of data processing, do so in thefinish()
method.- Throws:
Exception
-
-