THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
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.
...
Develop functions or call procedures that support named parameters
For The UDX 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 calling the functions or procedures.
| 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 = {
@ArgumentHint(name = "in1"),
@ArgumentHint(name = "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 NOT NULL")},
output = @DataTypeHint("STRING"),
arguments = {
@ArgumentHint(name = "in1"),
@ArgumentHint(name = "in2"),
@ArgumentHint(name = "in3")
})
public void eval(String arg1, String arg2, String arg3) {
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 = {
@ArgumentHint(name = "in1"),
@ArgumentHint(name = "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"),
arguments = {
@ArgumentHint(name = "in1"),
@ArgumentHint(name = "in2")})
public String[] call(ProcedureContext procedureContext, Integer arg1, Integer arg2, Integer arg3) {
return new String[]{arg1 + ", " + arg2};
}
} |
2 .The class procedure class that support named parameters 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),
@ArgumentHint(name = "in2", isOptional = true)
@ArgumentHint(name = "in3", isOptional = true)})
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),
@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};
}
} |
...
Capabilities and Limitations
Capabilities
...
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
1 . https://issues.apache.org/jira/browse/CALCITE-947