Package org.apache.flink.table.annotation

Annotation Type FunctionHint

@PublicEvolving @Retention(RUNTIME) @Target({TYPE,METHOD}) @Repeatable(FunctionHints.class) public @interface FunctionHint
A hint that influences the reflection-based extraction of arguments, accumulator, and output for constructing the TypeInference logic of a UserDefinedFunction.

One or more annotations can be declared on top of a UserDefinedFunction class or individually for each eval()/accumulate() method for overloading function signatures. All hint parameters are optional. If a parameter is not defined, the default reflection-based extraction is used. Hint parameters defined on top of a UserDefinedFunction class are inherited by all eval()/accumulate() methods.

The following examples show how to explicitly specify function signatures as a whole or in part and let the default extraction do the rest: 


 // accepts (INT, STRING) and returns BOOLEAN,
 // the arguments have names and are optional
 @FunctionHint(
   arguments = {
     @ArgumentHint(type = @DataTypeHint("INT"), name = "in1", isOptional = true),
     @ArgumentHint(type = @DataTypeHint("STRING"), name = "in2", isOptional = true)
   },
   output = @DataTypeHint("BOOLEAN")
 )
 class X extends ScalarFunction { ... }

 // accepts (INT, STRING...) and returns BOOLEAN,
 // the arguments have names
 @FunctionHint(
   arguments = {
     @ArgumentHint(type = @DataTypeHint("INT"), name = "in1"),
     @ArgumentHint(type = @DataTypeHint("STRING"), name = "in2")
   },
   isVarArgs = true,
   output = @DataTypeHint("BOOLEAN")
 )
 class X extends ScalarFunction { ... }

 // accepts (INT, STRING) and returns BOOLEAN
 @FunctionHint(
   input = [@DataTypeHint("INT"), @DataTypeHint("STRING")],
   output = @DataTypeHint("BOOLEAN")
 )
 class X extends ScalarFunction { ... }

 // accepts (INT, STRING) or (BOOLEAN) and returns BOOLEAN
 @FunctionHint(
   input = [@DataTypeHint("INT"), @DataTypeHint("STRING")],
   output = @DataTypeHint("BOOLEAN")
 )
 @FunctionHint(
   input = [@DataTypeHint("BOOLEAN")],
   output = @DataTypeHint("BOOLEAN")
 )
 class X extends ScalarFunction { ... }

 // accepts (INT, STRING) or (BOOLEAN) and always returns BOOLEAN
 @FunctionHint(
   output = @DataTypeHint("BOOLEAN")
 )
 class X extends ScalarFunction {
   @FunctionHint(
     input = [@DataTypeHint("INT"), @DataTypeHint("STRING")]
   )
   @FunctionHint(
     input = [@DataTypeHint("BOOLEAN")]
   )
   Object eval(Object... o) { ... }
 }

 // accepts (INT) or (BOOLEAN) and always returns ROW<f0 BOOLEAN, f1 INT>
 @FunctionHint(
   output = @DataTypeHint("ROW<f0 BOOLEAN, f1 INT>")
 )
 class X extends ScalarFunction {
   Row eval(int i) { ... }
   Row eval(boolean b) { ... }
 }

 // accepts (ROW<f BOOLEAN>...) or (BOOLEAN...) and returns INT
 class X extends ScalarFunction {
   @FunctionHint(
     input = [@DataTypeHint("ROW<f BOOLEAN>")],
     isVarArgs = true
   )
   int eval(Row... r) { ... }

   int eval(boolean... b) { ... }
 }

 // accepts (INT) and returns INT but allows RAW types in the accumulator type
 @FunctionHint(
   accumulator = @DataTypeHint(bridgedTo = my.package.MyClass.class, allowRawPattern = "my.package")
 )
 class X extends AggregateFunction<Integer, MyClass> {
   void accumulate(Row acc, int in) { ... }
   // ...
 }
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    DataTypeHint
    accumulator
    Explicitly defines the intermediate result type (i.e. state entry) that an aggregating function uses as its accumulator.
    ArgumentHint[]
    argument
    Deprecated.
    Use arguments() instead.
    String[]
    argumentNames
    Deprecated.
    Use arguments() instead.
    ArgumentHint[]
    arguments
    Explicitly lists the arguments that a function takes as input.
    DataTypeHint[]
    input
    Explicitly lists the argument types that a function takes as input.
    boolean
    isVarArgs
    Defines that the last argument type defined in input() should be treated as a variable-length argument.
    DataTypeHint
    output
    Explicitly defines the result type that a function uses as output.
    StateHint[]
    state
    Explicitly lists the intermediate results (i.e. state entries) of a function that is managed by the framework (i.e.

  • Element Details

    • input

      DataTypeHint[] input
      Explicitly lists the argument types that a function takes as input.

      By default, explicit input types are undefined and the reflection-based extraction is used.

      Note: Specifying the input arguments manually disables the entire reflection-based extraction around arguments. This means that also isVarArgs() needs to be specified manually if required.

      Use arguments() for more control about argument names and argument kinds.

      Default:
      {@org.apache.flink.table.annotation.DataTypeHint}

    • isVarArgs

      boolean isVarArgs
      Defines that the last argument type defined in input() should be treated as a variable-length argument.

      By default, if input() is defined, the last argument type is not a var-arg. If input() is not defined, the reflection-based extraction is used to decide about the var-arg flag, thus, this parameter is ignored.

      Default:
      false

    • arguments

      ArgumentHint[] arguments
      Explicitly lists the arguments that a function takes as input. Including their names, data types, kinds, and whether they are optional.

      It is recommended to use this parameter instead of input(). Using both input() and this parameter is not allowed. Specifying the list of arguments manually disables the entire reflection-based extraction around arguments.

      Default:
      {}

    • accumulator

      DataTypeHint accumulator
      Explicitly defines the intermediate result type (i.e. state entry) that an aggregating function uses as its accumulator. The entry is managed by the framework (usually via Flink's managed state).

      By default, an explicit accumulator type is undefined and the reflection-based extraction is used.

      This parameter is primarily intended for aggregating functions (i.e. AggregateFunction and TableAggregateFunction). It is recommended to use state() for ProcessTableFunction.

      Default:
      @org.apache.flink.table.annotation.DataTypeHint

    • state

      StateHint[] state
      Explicitly lists the intermediate results (i.e. state entries) of a function that is managed by the framework (i.e. Flink managed state). Including their names and data types.

      State hints are primarily intended for ProcessTableFunction. A PTF supports multiple state entries at the beginning of an eval()/onTimer() method (after an optional context parameter).

      Aggregating functions (i.e. AggregateFunction and TableAggregateFunction) support a single state entry at the beginning of an accumulate()/retract() method (i.e. the accumulator).

      By default, explicit state is undefined and the reflection-based extraction is used where StateHint is present.

      Using both accumulator() and this parameter is not allowed. Specifying the list of state entries manually disables the entire reflection-based extraction around StateHint and accumulators for aggregating functions.

      Default:
      {}

    • output

      DataTypeHint output
      Explicitly defines the result type that a function uses as output.

      By default, an explicit output type is undefined and the reflection-based extraction is used.

      Default:
      @org.apache.flink.table.annotation.DataTypeHint

    • argumentNames

      @Deprecated String[] argumentNames
      Deprecated.
      Use arguments() instead.
      Explicitly lists the argument names that a function takes as input.

      By default, if input() is defined, explicit argument names are undefined and this parameter can be used to provide argument names. If input() is not defined, the reflection-based extraction is used, thus, this parameter is ignored.

      Default:
      {""}

    • argument

      @Deprecated ArgumentHint[] argument
      Deprecated.
      Use arguments() instead.
      Explicitly lists the arguments that a function takes as input. Including their names, data types, kinds, and whether they are optional.

      It is recommended to use this parameter instead of input(). Specifying the list of arguments manually disables the entire reflection-based extraction around arguments.

      Default:
      {}