THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| 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.
Public Interfaces
Interface change
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 {
/**
* The name of the parameter, default is an empty string.
*/
String name() default "";
/**
* Whether booleanthe isOptional()parameter default true;
} |
Function developing and call procedure developing
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")},
output = @DataTypeHint("STRING"),
argumentNames = {"in1", "in2"})
public void eval(String arg1, String arg2) {
collect(arg1 + ", " + arg2);
}
// Example usage: SELECT * FROM TABLE(my_table_function(in1 => 'value1', in2 => 'value2', in3 => 'value3'))
@FunctionHint(
input = {@DataTypeHint("STRING"), @DataTypeHint("STRING"), @DataTypeHint("STRING")},
output = @DataTypeHint("STRING"),
argumentNames = {"in1", "in2", "in3"})
public void eval(String arg1, String arg2, String arg3) {
collect(arg1 + ", " + arg2);
}
}
// 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"),
argumentNames = {"in1", "in2"})
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"),
argumentNames = {"in1", "in2"})
public String[] call(ProcedureContext procedureContext, Integer arg1, Integer arg2) {
return new String[]{arg1 + ", " + arg2};
}
} |
is optional, default is false.
*/
boolean isOptional() default false;
/**
* The data type hint for the parameter.
*/
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 this attribute.
*/
@Deprecated
String[] argumentNames() default {""};
/**
* Attribute for specifying the hints and additional information for function arguments.
*/
ArgumentHint[] arguments() default {};
} |
| Code Block |
|---|
public @interface ProcedureHint {
/**
* Deprecated attribute for specifying the names of the arguments.
* It is no longer recommended to use this attribute.
*/
@Deprecated
String[] 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 output = {@DataTypeHint("STRING"), @DataTypeHint(value
arguments = {
@ArgumentHint(name = "STRINGin1", isOptional = true, type = false@DataTypeHint("STRING")), @DataTypeHint(value
@ArgumentHint(name = "STRINGin2", isOptional = true)},
output, type = @DataTypeHint("STRING")),
argumentNames
@ArgumentHint(name = {"in1in3", "in2", "in3"})
public 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 output = @DataTypeHint("STRING"),
arguments = {@DataTypeHint(value
@ArgumentHint(name = "STRINGin1", isOptional = false), @DataTypeHint(valuetype = @DataTypeHint("STRING")), isOptional = false), @DataTypeHint(value
@ArgumentHint(name = "STRINGin2", isOptional = true)},
output, type = @DataTypeHint("STRING")),
argumentNames
@ArgumentHint(name = {"cin3", "d", "e"})
public isOptional = true, type = @DataTypeHint("STRING"))})
public String[] call(ProcedureContext procedureContext, String arg1, String arg2, String arg3) {
return new String[]{arg1 + ", " + arg2 + "," + arg3};
}
} |
...
Call functions or procedures using named parameters
Users can now use call functions and call or procedures with named parameters as follows:
| Code Block | ||
|---|---|---|
| ||
-- 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’) |
...
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.