Hi all,
Xuyang and I would like to start a discussion of FLIP-387: Support
named parameters for functions and call procedures [1]
Currently, when users call a function or call a procedure, they must
specify all fields in order. When there are a large number of
parameters, it is easy to make mistakes and cannot omit specifying
non-mandatory fields.
By using named parameters, you can selectively specify the required
parameters, reducing the probability of errors and making it more
convenient to use.
Here is an example of using Named Procedure.
```
-- for scalar function
SELECT my_scalar_function(param1 => ‘value1’, param2 => ‘value2’’) FROM []
-- for table function
SELECT * FROM TABLE(my_table_function(param1 => 'value1', param2 => 'value2'))
-- for agg function
SELECT my_agg_function(param1 => 'value1', param2 => 'value2') FROM []
-- for call procedure
CALL procedure_name(param1 => ‘value1’, param2 => ‘value2’)
```
For UDX and Call procedure developers, we introduce a new annotation
to specify the parameter name, indicate if it is optional, and
potentially support specifying default values in the future
```
public @interface ArgumentHint {
/**
* The name of the parameter, default is an empty string.
*/
String name() default "";
/**
* Whether the parameter is optional, default is true.
*/
boolean isOptional() default true;
}}
```
```
// Call Procedure Development
public static class NamedArgumentsProcedure implements Procedure {
// Example usage: CALL myNamedProcedure(in1 => 'value1', in2 => 'value2')
// Example usage: CALL myNamedProcedure(in1 => 'value1', in2 =>
'value2', in3 => 'value3')
@ProcedureHint(
input = {@DataTypeHint(value = "STRING"),
@DataTypeHint(value = "STRING"), @DataTypeHint(value = "STRING")},
output = @DataTypeHint("STRING"),
arguments = {
@ArgumentHint(name = "in1", isOptional = false),
@ArgumentHint(name = "in2", isOptional = true)
@ArgumentHint(name = "in3", isOptional = true)})
public String[] call(ProcedureContext procedureContext, String
arg1, String arg2, String arg3) {
return new String[]{arg1 + ", " + arg2 + "," + arg3};
}
}
```
Currently, we offer support for two scenarios when calling a function
or procedure:
1. The corresponding parameters can be specified using the parameter
name, without a specific order.
2. Unnecessary parameters can be omitted.
There are still some limitations when using Named parameters:
1. Named parameters do not support variable arguments.
2. UDX or procedure classes that support named parameters can only
have one eval method.
3. Due to the current limitations of Calcite-947[2], we cannot specify
a default value for omitted parameters, which is Null by default.
Also, thanks very much for the suggestions and help provided by Zelin
and Lincoln.
1.
https://cwiki.apache.org/confluence/display/FLINK/FLIP-387%3A+Support+named+parameters+for+functions+and+call+procedures.
2. https://issues.apache.org/jira/browse/CALCITE-947
Best,
Feng
