...

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.

public @interface ArgumentHint {
    String name() default "";

    boolean isOptional() 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.

// 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();
}

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 {};
}

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.

// 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};
   }
}

...

Call functions or procedures using named parameters

...

Users can use call functions and call or procedures with named parameters as follows:

...

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.