...
Page properties | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Table of Contents
Motivation
Currently, when users invoke 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.
...
Introduce a new annotation to specify the parameter name, indicate if it is optional, and potentially support specifying default values in the future.
Deprecate the ArgumentNames annotation argumentNames method in FunctionHints as it is not user-friendly for specifying argument names with optional configuration.
Code Block | ||
---|---|---|
| ||
public @interface ArgumentHint {
String name() default "";
boolean isOptional() default true;
} |
Develop UDX or call procedures that support named parameters
For UDF development or call developers, the UDX or procedure we develop can be roughly divided into two types:
1 . Class overloads multiple methods with different parameters and types. Users need to specify all the parameters when using.
Code Block | ||
---|---|---|
| ||
// UDF Development public static class NamedArgumentsTableFunction extends TableFunction<Object> { // Method overloads with different parameter sets // Example usage: SELECT * FROM TABLE(my_table_function(in1 => 'value1', in2 => 'value2')) @FunctionHint( input = {@DataTypeHint("STRING"), @DataTypeHint("STRING NOT NULL")}, output = @DataTypeHint("STRING"), arguments = {/** * The name of the parameter, default is an empty string. */ String name() default ""; /** * Whether the parameter @ArgumentHint(name = "in1"), @ArgumentHint(name = "in2")is optional, default is false. })*/ publicboolean void eval(String arg1, String arg2isOptional() { collect(arg1 + ", " + arg2); default false; } // Example usage: SELECT/** * FROM TABLE(my_table_function(in1 => 'value1', in2 => 'value2', in3 => 'value3'))The data type hint for the parameter. @FunctionHint(*/ input = {@DataTypeHint("STRING"), @DataTypeHint("STRING NOT NULL")}, output = @DataTypeHint("STRING"), arguments = {DataTypeHint type() default @DataTypeHint(); } |
Code Block |
---|
public @interface FunctionHint { /** * Deprecated attribute for specifying the names of the arguments. * It is no longer recommended to use @ArgumentHint(name = "in1"),this attribute. */ @Deprecated @ArgumentHint(name = "in2"), @ArgumentHint(name = "in3") String[] argumentNames() default {""}; /** * Attribute for specifying }) the hints and additional publicinformation voidfor eval(String arg1, String arg2, String arg3) {function arguments. */ ArgumentHint[] arguments() default {}; } |
Code Block |
---|
public @interface ProcedureHint { /** * Deprecated attribute for specifying the names of the arguments. collect(arg1 + ", " + arg2 + "," + arg3); } } // Call Procedure Development public static class NamedArgumentsProcedure implements Procedure { // Method overloads with different parameter sets // Example usage: CALL myNamedProcedure(in1 => 'value1', d => 100) @ProcedureHint( input = {@DataTypeHint("STRING"), @DataTypeHint("INT")},= output = @DataTypeHint("STRING"), arguments = { * It is no longer recommended to use @ArgumentHint(name = "in1"),this attribute. @ArgumentHint(name = "in2")*/ }) @Deprecated public String[] call(ProcedureContext procedureContext, String arg1, Integer arg2) { return new String[]{arg1 + ", " + arg2}; } // Example usage: CALL myNamedProcedure(in1 => 100, in2 => 200) @ProcedureHint( input = {@DataTypeHint("INT"), @DataTypeHint("INT")}, output = @DataTypeHint("STRING"), arguments = { @ArgumentHint(name = "in1"), @ArgumentHint(name = "in2")}) public String[] call(ProcedureContext procedureContext, Integer arg1, Integer arg2, Integer arg3) { return new String[]{arg1 + ", " + arg2}; } }argumentNames() default {""}; /** * Attribute for specifying the hints and additional information for procedure arguments. */ ArgumentHint[] arguments() default {}; } |
Develop functions or call procedures that support named parameters
The UDX or procedure class that support named parameters 2 .The class can only have one method, and users can optionally specify parameters when calling functions or procedures.
And we can use ArgumentHint to specific the argument name and indicate if argument is optional.
Code Block | ||
---|---|---|
| ||
// UDF Development public static class NamedArgumentsTableFunction extends TableFunction<Object> { // Example usage: SELECT * FROM TABLE(my_table_function(in1 => 'value1', in2 => 'value2')) // Example usage: SELECT * FROM TABLE(my_table_function(in1 => 'value1', in2 => 'value2', in3 => 'value3')) @FunctionHint( input = {@DataTypeHint("STRING"), @DataTypeHint(value = "STRING"), @DataTypeHint(value = "STRING")}, output = @DataTypeHint("STRING"), arguments = { @ArgumentHint(name = "in1", isOptional = true, type = @DataTypeHint("STRING")), @ArgumentHint(name = "in2", isOptional = true, type = @DataTypeHint("STRING")) @ArgumentHint(name = "in3", isOptional = true, type = @DataTypeHint("STRING"))}) public void eval(String arg1, String arg2, String arg3) { collect(arg1 + ", " + arg2 + "," + arg3); } } // 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, type = @DataTypeHint("STRING")), @ArgumentHint(name = "in2", isOptional = true, type = @DataTypeHint("STRING")) @ArgumentHint(name = "in3", isOptional = true, type = @DataTypeHint("STRING"))}) public String[] call(ProcedureContext procedureContext, String arg1, String arg2, String arg3) { return new String[]{arg1 + ", " + arg2 + "," + arg3}; } } |
...
Capabilities and Limitations
Capabilities
- Multiple Parameter Lists:
Within one UDX and Procedure, you can declare multi parameter lists with different sets of parameters for overloaded functions.
- Reflection-based Named Parameters:
...
- Variable arguments are not supported with named parameters.
- The same the UDX or call procedure class cannot simultaneously support optional arguments and multiple parameter lists that support named parameters can only have one eval method
Due to the current limitations of Calcite-947[1], we are unable to specify a default value for omitted parameter. The default value for omitted parameters is Null.
Compatibility, Deprecation, and Migration Plan
...
To validate this feature, we can develop custom UDFs or call procedures and use named parameters when invoking them.
Rejected Alternatives
Rejected Alternatives
None
1 . https://issues.apache.org/jira/browse/CALCITE-947
2. poc: https://github.com/apache/flink/compare/master...hackergin:flink:poc_named_argumentIf there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way.