Package org.apache.flink.table.functions

Class AsyncScalarFunction

java.lang.Object
org.apache.flink.table.functions.UserDefinedFunction
org.apache.flink.table.functions.AsyncScalarFunction
All Implemented Interfaces:
Serializable, FunctionDefinition
@PublicEvolving public class AsyncScalarFunction extends UserDefinedFunction
Base class for a user-defined scalar function which returns results asynchronously. A user-defined scalar function maps zero, one, or multiple scalar values to a new scalar value.

The behavior of a AsyncScalarFunction can be defined by implementing a custom evaluation method. An evaluation method must be declared publicly and named eval. Evaluation methods can also be overloaded by implementing multiple methods named eval . The first argument of the method must be a CompletableFuture of the return type. The method body must complete the future either if there is a result or if it completes exceptionally.

By default, input and output data types are automatically extracted using reflection. If the reflective information is not sufficient, it can be supported and enriched with DataTypeHint and FunctionHint annotations.

The following examples show how to specify an async scalar function: 


 // a function that accepts two INT arguments and computes a sum
 class SumFunction extends AsyncScalarFunction {
   public void eval(CompletableFuture<Integer> future, Integer a, Integer b) {
     return future.complete(a + b);
   }
 }

 // a function that accepts either INT NOT NULL or BOOLEAN NOT NULL and computes a STRING
 class StringifyFunction extends AsyncScalarFunction {
   public void eval(CompletableFuture<String> future, int i) {
     return future.complete(String.valueOf(i));
   }
   public void eval(CompletableFuture<String> future, boolean b) {
     return future.complete(String.valueOf(b));
   }
 }

 // a function that accepts either INT or BOOLEAN and computes a STRING using function hints
 @FunctionHint(input = [@DataTypeHint("INT")])
 @FunctionHint(input = [@DataTypeHint("BOOLEAN")])
 class StringifyFunction extends AsyncScalarFunction {
   public void eval(CompletableFuture<String> future, Object o) {
     return future.complete(o.toString());
   }
 }

 // a function that accepts any data type as argument and computes a STRING
 class StringifyFunction extends AsyncScalarFunction {
   public void eval(CompletableFuture<String> future,
                    @DataTypeHint(inputGroup = InputGroup.ANY) Object o) {
     return future.complete(o.toString());
   }
 }

 // a function that accepts an arbitrary number of BIGINT values and computes a DECIMAL(10, 4)
 class SumFunction extends AsyncScalarFunction {
   public void eval(@DataTypeHint("DECIMAL(10, 4)") CompletableFuture<BigDecimal> future,
                    Long... values) {
     // ...
   }
 }

For storing a user-defined function in a catalog, the class must have a default constructor and must be instantiable during runtime. Anonymous functions in Table API can only be persisted if the function is not stateful (i.e. containing only transient and static fields).

See Also:

  • Constructor Details

    • AsyncScalarFunction

      public AsyncScalarFunction()

  • Method Details

    • 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 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
      Specified by:
      getTypeInference in class UserDefinedFunction