Package org.apache.flink.table.annotation

Annotation Type ProcedureHint

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

One or more annotations can be declared on top of a Procedure class or individually for each call() 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 Procedure class are inherited by all call() methods. The DataTypeHint for the output data type should always hint the component type of the array returned by Procedure.

The following examples show how to explicitly specify procedure 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
 @ProcedureHint(
   arguments = {
     @ArgumentHint(type = @DataTypeHint("INT"), name = "in1", isOptional = true),
     @ArgumentHint(type = @DataTypeHint("STRING"), name = "in2", isOptional = true)
   },
   output = @DataTypeHint("BOOLEAN")
 )
 class X implements Procedure { ... }

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

 // accepts (INT, STRING) and returns an array of BOOLEAN
 @ProcedureHint(
   input = [@DataTypeHint("INT"), @DataTypeHint("STRING")],
   output = @DataTypeHint("BOOLEAN")
 )
 class X implements Procedure { ... }

 // accepts (INT, STRING) or (BOOLEAN) and returns an array of BOOLEAN
 @ProcedureHint(
   input = [@DataTypeHint("INT"), @DataTypeHint("STRING")],
   output = @DataTypeHint("BOOLEAN")
 )
 @ProcedureHint(
   input = [@DataTypeHint("BOOLEAN")],
   output = @DataTypeHint("BOOLEAN")
 )
 class X implements Procedure { ... }

 // accepts (INT, STRING) or (BOOLEAN) and always returns an array of BOOLEAN
 @ProcedureHint(
   output = @DataTypeHint("BOOLEAN")
 )
 class X implements Procedure {
   @ProcedureHint(
     input = [@DataTypeHint("INT"), @DataTypeHint("STRING")]
   )
   @ProcedureHint(
     input = [@DataTypeHint("BOOLEAN")]
   )
   Object[] call(Object... o) { ... }
 }

 // accepts (INT) or (BOOLEAN) and always returns an array of ROW<f0 BOOLEAN, f1 INT>
 @ProcedureHint(
   output = @DataTypeHint("ROW<f0 BOOLEAN, f1 INT>")
 )
 class X implements Procedure {
   Row[] call(int i) { ... }
   Row[] call(boolean b) { ... }
 }

 // accepts (ROW<f BOOLEAN>...) or (BOOLEAN...) and returns an array of INT
 class X implements Procedure {
   @ProcedureHint(
     input = [@DataTypeHint("ROW<f BOOLEAN>")],
     isVarArgs = true
   )
   Integer[] call(Row... r) { ... }

   Integer[] call(boolean... b) { ... }
 }
See Also:

  • Element Details

    • input

      DataTypeHint[] input
      Explicitly lists the argument types that a procedure 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 procedure 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:
      {}

    • output

      DataTypeHint output
      Explicitly defines the result type that a procedure 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 procedure 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 procedure 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:
      {}