THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Motivation
Currently, when users invoke 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 as it is not user-friendly for specifying argument names with optional configuration.
public @interface ArgumentHint {
String name() default "";
boolean isOptional() default true;
}
Develop functions or call procedures that support named parameters
For 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.
// 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 can only have one method, and users can optionally specify parameters when calling functions or procedures.
// 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};
}
}
Call functions or procedures using named parameters
Users can call functions or procedures with named parameters as follows:
-- 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’)
Proposed Changes
Implementing Named Parameters:
In FLIP-65, UDX has already supported the ability to parse argument names from FunctionHint and ProcedureHint. Calcite has long supported the ability to use named optional and default arguments when calling functions (CALCITE-941), but some issues and limitations were discovered during the poc.
1. Passing Named Parameters to the Calcite:
Due to Calcite's behavior of reordering operands based on named arguments, the reordering relies on the implementation of the SqlOperandTypeCheck interface in order to implement the SqlOperandMetadata interface. Therefore, it is necessary to extend the TypeInferenceOperandChecker class for this specific implementation.
2.Fixing Calcite Bugs Related to Named Parameters:
During POC verification, bugs were discovered in Calcite that caused issues during the validation phase. We need to modify the SqlValidatorImpl and SqlToRelConverter to address these problems.
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:
When using the feature without explicitly specifying parameter hints, the function will automatically retrieve the parameter names using reflection, allowing them to be used as named parameters.
- Optional Argument Names:
If the argument names specified in the hint do not match the actual parameter names, it will fall back to using default values. When users use optional argument names, we need corresponding UDX methods without overloads to avoid function conflicts caused by assigning default values.
Limitations:
- Variable arguments are not supported with named parameters.
- The same UDX or call procedure class cannot simultaneously support optional arguments and multiple parameter lists.
Compatibility, Deprecation, and Migration Plan
Compatibility:
Since named parameters are a newly introduced feature, there are no compatibility issues. However, it's important to note that functions registered using the deprecated TableEnvironment.registerFunction API will not support named parameters.
Deprecation:
No deprecation is required for this feature.
Migration Plan:
No migration is needed as this is a new feature.
Test Plan
To validate this feature, we can develop custom UDFs or call procedures and use named parameters when invoking them.