[FLINK-37446][table-api-java] Support named arguments in Table API

This closes #26282.

Author: twalthr

docs/content.zh/docs/dev/table/functions/systemFunctions.md

@@ -230,3 +230,42 @@ table
 {{< /tabs >}}
 
 {{< top >}}
+
+Named Arguments
+---------------------------------------
+
+By default, values and expressions are mapped to a function's arguments based on the position in the function call,
+for example `f(42, true)`. All functions in both SQL and Table API support position-based arguments.
+
+If the function declares a static signature, named arguments are available as a convenient alternative.
+The framework is able to reorder named arguments and consider optional arguments accordingly, before passing them
+into the function call. Thus, the order of arguments doesn't matter when calling a function and optional arguments
+don't have to be provided.
+
+In `DESCRIBE FUNCTION` and documentation a static signature is indicated by the `=>` assignment operator,
+for example `f(left => INT, right => BOOLEAN)`. Note that not every function supports named arguments. Named
+arguments are not available for signatures that are overloaded, use varargs, or any other kind of input type strategy.
+User-defined functions with a single `eval()` method usually qualify for named arguments.
+
+Named arguments can be used as shown below:
+
+{{< tabs "902fe991-5fb9-4b17-ae99-f05cbd48b4dd" >}}
+{{< tab "SQL" >}}
+```text
+SELECT MyUdf(input => my_column, threshold => 42)
+```
+{{< /tab >}}
+{{< tab "Table API" >}}
+```java
+table.select(
+  call(
+    MyUdf.class,
+    $("my_column").asArgument("input"),
+    lit(42).asArgument("threshold")
+  )
+);
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}

docs/content/docs/dev/table/functions/systemFunctions.md

@@ -235,3 +235,42 @@ table \
 {{< /tabs >}}
 
 {{< top >}}
+
+Named Arguments
+---------------------------------------
+
+By default, values and expressions are mapped to a function's arguments based on the position in the function call,
+for example `f(42, true)`. All functions in both SQL and Table API support position-based arguments.
+
+If the function declares a static signature, named arguments are available as a convenient alternative.
+The framework is able to reorder named arguments and consider optional arguments accordingly, before passing them
+into the function call. Thus, the order of arguments doesn't matter when calling a function and optional arguments
+don't have to be provided.
+
+In `DESCRIBE FUNCTION` and documentation a static signature is indicated by the `=>` assignment operator,
+for example `f(left => INT, right => BOOLEAN)`. Note that not every function supports named arguments. Named
+arguments are not available for signatures that are overloaded, use varargs, or any other kind of input type strategy.
+User-defined functions with a single `eval()` method usually qualify for named arguments.
+
+Named arguments can be used as shown below:
+
+{{< tabs "902fe991-5fb9-4b17-ae99-f05cbd48b4dd" >}}
+{{< tab "SQL" >}}
+```text
+SELECT MyUdf(input => my_column, threshold => 42)
+```
+{{< /tab >}}
+{{< tab "Table API" >}}
+```java
+table.select(
+  call(
+    MyUdf.class,
+    $("my_column").asArgument("input"),
+    lit(42).asArgument("threshold")
+  )
+);
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< top >}}

flink-python/pyflink/table/tests/test_expression_completeness.py

@@ -57,7 +57,8 @@ def excluded_methods(cls):
             'dividedBy',
             'times',
             'mod',
-            'power'
+            'power',
+            'asArgument',
         }
 
     @classmethod

flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/internal/BaseExpressions.java

@@ -250,6 +250,36 @@ public OutType as(String name, String... extraNames) {
                                 .toArray(Expression[]::new)));
     }
 
+    /**
+     * Converts this expression into a named argument.
+     *
+     * <p>If the function declares a static signature (usually indicated by the "=>" assignment
+     * operator), the framework is able to reorder named arguments and consider optional arguments
+     * accordingly, before passing them into the function call.
+     *
+     * <p>Note: Not every function supports named arguments. Named arguments are not available for
+     * signatures that are overloaded, use varargs, or any other kind of input type strategy.
+     *
+     * <p>Example:
+     *
+     * <pre>{@code
+     * table.select(
+     *   Expressions.call(
+     *     "MyFunction",
+     *     $("my_column").asArgument("input"),
+     *     lit(42).asArgument("threshold")
+     *   )
+     * )
+     * }</pre>
+     */
+    public OutType asArgument(String name) {
+        return toApiSpecificExpression(
+                ApiExpressionUtils.unresolvedCall(
+                        BuiltInFunctionDefinitions.ASSIGNMENT,
+                        ApiExpressionUtils.valueLiteral(name),
+                        toExpr()));
+    }
+
     /**
      * Returns an ARRAY that contains the elements from array1 that are not in array2. If no
      * elements remain after excluding the elements in array2 from array1, the function returns an