This is an automated email from the ASF dual-hosted git repository.
shengkai pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new 26b1d1bbff5 [FLINK-34265][doc] Add the doc of named parameters (#24260)
26b1d1bbff5 is described below
commit 26b1d1bbff590589c72af892fc22f80fa4ee1261
Author: Feng Jin <jinfeng1...@gmail.com>
AuthorDate: Mon Feb 26 13:21:01 2024 +0800
[FLINK-34265][doc] Add the doc of named parameters (#24260)
---
docs/content.zh/docs/dev/table/functions/udfs.md | 139 +++++++++++++++++++++
docs/content.zh/docs/dev/table/procedures.md | 146 +++++++++++++++++++++++
docs/content/docs/dev/table/functions/udfs.md | 137 +++++++++++++++++++++
docs/content/docs/dev/table/procedures.md | 144 ++++++++++++++++++++++
4 files changed, 566 insertions(+)
diff --git a/docs/content.zh/docs/dev/table/functions/udfs.md
b/docs/content.zh/docs/dev/table/functions/udfs.md
index 5527cfcb978..f137b2ba446 100644
--- a/docs/content.zh/docs/dev/table/functions/udfs.md
+++ b/docs/content.zh/docs/dev/table/functions/udfs.md
@@ -77,6 +77,9 @@ env.from("MyTable").select(call("SubstringFunction",
$("myField"), 5, 12));
// 在 SQL 里调用注册好的函数
env.sqlQuery("SELECT SubstringFunction(myField, 5, 12) FROM MyTable");
+// 在 SQL 里使用命名参数调用注册好的函数
+env.sqlQuery("SELECT SubstringFunction(param1 => myField, param2 => 5, param3
=> 12) FROM MyTable");
+
```
{{< /tab >}}
{{< tab "Scala" >}}
@@ -599,6 +602,142 @@ public static class LiteralFunction extends
ScalarFunction {
For more examples of custom type inference, see also the
`flink-examples-table` module with
{{< gh_link
file="flink-examples/flink-examples-table/src/main/java/org/apache/flink/table/examples/java/functions/AdvancedFunctionsExample.java"
name="advanced function implementation" >}}.
+### 命名参数
+
+在调用函数时，可以使用参数名称来指定参数值。命名参数允许同时传递参数名和值给函数，避免了因为错误的参数顺序而导致混淆，并提高了代码的可读性和可维护性。
此外，命名参数还可以省略非必需的参数，默认情况下会使用 `null` 进行填充。
+我们可以通过 `@ArgumentHint` 注解来指定参数的名称，类型，是否是必需的参数等。
+
+**`@ArgumentHint`**
+
+下面三个示例展示了如何在不同的范围内使用 `@ArgumentHint`。更多信息请参考注解类的文档。
+
+1. 在 function 的 `eval` 方法的参数上使用 `@ArgumentHint` 注解。
+
+{{< tabs "8064df87-eb42-4def-9bd2-0988fc246d37" >}}
+{{< tab "Java" >}}
+
+```java
+import com.sun.tracing.dtrace.ArgsAttributes;
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+public static class NamedParameterClass extends ScalarFunction {
+
+ // 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及是否是必需的参数
+ public String eval(@ArgumentHint(name = "param1", isOptional = false, type
= @DataTypeHint("STRING")) String s1,
+ @ArgumentHint(name = "param2", isOptional = true, type
= @DataTypeHint("INT")) Integer s2) {
+ return s1 + ", " + s2;
+ }
+}
+
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+class NamedParameterClass extends ScalarFunction {
+
+ // 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及是否是必需的参数
+ def eval(@ArgumentHint(name = "param1", isOptional = false, `type` =
@DataTypeHint("STRING")) s1: String,
+ @ArgumentHint(name = "param2", isOptional = true, `type` =
@DataTypeHint("INTEGER")) s2: Integer) = {
+ s1 + ", " + s2
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+2. 在 function 的 `eval` 方法上使用 `@ArgumentHint` 注解。
+
+{{< tabs "1356086c-189c-4932-a797-badf5b5e27ab" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+public static class NamedParameterClass extends ScalarFunction {
+
+ // 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及该参数是否是必需的参数
+ @FunctionHint(
+ argument = {@ArgumentHint(name = "param1", isOptional = false, type
= @DataTypeHint("STRING")),
+ @ArgumentHint(name = "param2", isOptional = true, type =
@DataTypeHint("INTEGER"))}
+ )
+ public String eval(String s1, Integer s2) {
+ return s1 + ", " + s2;
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+class NamedParameterClass extends ScalarFunction {
+
+ // 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及是否是必需的参数
+ @FunctionHint(
+ argument = Array(new ArgumentHint(name = "param1", isOptional = false,
`type` = new DataTypeHint("STRING")),
+ new ArgumentHint(name = "param2", isOptional = true, `type`
= new DataTypeHint("INTEGER")))
+ )
+ def eval(s1: String, s2: Int): String = {
+ s1 + ", " + s2
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+3. 在 function 的 class 上使用 `@ArgumentHint` 注解。
+
+{{< tabs "ba00146a-08bf-496c-89bc-8d5e333f04f7" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+// 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及是否是必需的参数
+@FunctionHint(
+ argument = {@ArgumentHint(name = "param1", isOptional = false, type =
@DataTypeHint("STRING")),
+ @ArgumentHint(name = "param2", isOptional = true, type =
@DataTypeHint("INTEGER"))}
+)
+public static class NamedParameterClass extends ScalarFunction {
+
+ public String eval(String s1, Integer s2) {
+ return s1 + ", " + s2;
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+// 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及是否是必需的参数
+@FunctionHint(
+ argument = Array(new ArgumentHint(name = "param1", isOptional = false,
`type` = new DataTypeHint("STRING")),
+ new ArgumentHint(name = "param2", isOptional = true, `type` = new
DataTypeHint("INTEGER")))
+)
+class NamedParameterClass extends ScalarFunction {
+
+ // 使用 @ArgumentHint 注解指定参数的名称，参数类型，以及是否是必需的参数
+ def eval(s1: String, s2: Int): String = {
+ s1 + ", " + s2
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+
+{{< hint info >}}
+* `@ArgumentHint` 内部包含了 `@DataTypeHint` 注解，因此在 `@FunctionHint` 中不能同时声明 `input`
和 `argument` ，当作用于函数的参数时 `@ArgumentHint` 也不能和 `@DataTypeHint` 同时使用，推荐使用
`@ArgumentHint` 。
+* 命名参数只有在对应的类不包含重载函数和可变参函数才会生效，否则使用命名参数会导致报错。
+{{< /hint >}}
+
### 确定性
每个用户自定义函数类都可以通过重写 `isDeterministic()`
方法来声明它是否产生确定性的结果。如果该函数不是纯粹函数式的（如`random()`, `date()`, 或`now()`），该方法必须返回
`false`。默认情况下，`isDeterministic()` 返回 `true`。
diff --git a/docs/content.zh/docs/dev/table/procedures.md
b/docs/content.zh/docs/dev/table/procedures.md
index cb70d759ebc..d7efa89b31f 100644
--- a/docs/content.zh/docs/dev/table/procedures.md
+++ b/docs/content.zh/docs/dev/table/procedures.md
@@ -338,6 +338,152 @@ class OverloadedProcedure extends Procedure {
{{< /tab >}}
{{< /tabs >}}
+### 命名参数
+
+在调用存储过程时，可以使用参数名称来指定参数值。命名参数允许同时传递参数名和值给存储过程，避免了因为错误的参数顺序而导致混淆，并提高了代码的可读性和可维护性。
此外，命名参数还可以省略非必需的参数，默认情况下会使用 `null` 进行填充。
+我们可以通过 `@ArgumentHint` 注解来指定参数的名称，类型，是否是必需的参数等。
+
+下面三个示例展示了如何在不同的范围内使用 `@ArgumentHint`。更多信息请参考注解类的文档。
+
+1. 在存储过程的 `call` 方法的参数上使用 `@ArgumentHint` 注解。
+
+{{< tabs "d2132879-26dc-45ba-8daa-365733a738e0" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.ProcedureHint;
+import org.apache.flink.table.procedure.ProcedureContext;
+import org.apache.flink.table.procedures.Procedure;
+import org.apache.flink.types.Row;
+
+public static class NamedParameterProcedure extends Procedure {
+
+ public @DataTypeHint("INT") Integer[] call(ProcedureContext context,
@ArgumentHint(name = "a", isOption = true) Integer a, @ArgumentHint(name = "b")
Integer b) {
+ return new Integer[] {a + (b == null ? 0 : b)};
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+
+import org.apache.flink.table.annotation.DataTypeHint
+import org.apache.flink.table.annotation.ProcedureHint
+import org.apache.flink.table.procedure.ProcedureContext
+import org.apache.flink.table.procedures.Procedure
+import org.apache.flink.types.Row
+import scala.annotation.varargs
+
+class NamedParameterProcedure extends Procedure {
+
+ def call(context: ProcedureContext, @ArgumentHint(name = "param1",
isOptional = true) a: Integer, @ArgumentHint(name = "param2") b: Integer):
Array[Integer] = {
+ Array(a + (if (b == null) 0 else b))
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+2. 在存储过程的 `call` 方法上使用 `@ArgumentHint` 注解。
+
+{{< tabs "5c682030-fdbd-485c-9961-b402971e14d4" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.ProcedureHint;
+import org.apache.flink.table.procedure.ProcedureContext;
+import org.apache.flink.table.procedures.Procedure;
+import org.apache.flink.types.Row;
+
+public static class NamedParameterProcedure extends Procedure {
+
+ @ProcedureHint(
+ argument = {@ArgumentHint(name = "param1", type =
@DataTypeHint("INTEGER"), isOptional = false),
+ @ArgumentHint(name = "param2", type =
@DataTypeHint("INTEGER"), isOptional = true)}
+ )
+ public @DataTypeHint("INT") Integer[] call(ProcedureContext context,
Integer a, Integer b) {
+ return new Integer[] {a + (b == null ? 0 : b)};
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+
+import org.apache.flink.table.annotation.DataTypeHint
+import org.apache.flink.table.annotation.ProcedureHint
+import org.apache.flink.table.procedure.ProcedureContext
+import org.apache.flink.table.procedures.Procedure
+import org.apache.flink.types.Row
+import scala.annotation.varargs
+
+class NamedParameterProcedure extends Procedure {
+ @ProcedureHint(
+ argument = Array(
+ new ArgumentHint(name = "param1", `type` = new DataTypeHint("INTEGER"),
isOptional = false),
+ new ArgumentHint(name = "param2", `type` = new DataTypeHint("INTEGER"),
isOptional = true)
+ )
+ )
+ def call(context: ProcedureContext, a: Integer, b: Integer):
Array[Integer] = {
+ Array(a + (if (b == null) 0 else b))
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+3. 在存储过程的 class 上使用 `@ArgumentHint` 注解。
+
+{{< tabs "64db1ce1-1251-4cc4-a7d8-13b5664f9019" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.ProcedureHint;
+import org.apache.flink.table.procedure.ProcedureContext;
+import org.apache.flink.table.procedures.Procedure;
+import org.apache.flink.types.Row;
+
+@ProcedureHint(
+ argument = {@ArgumentHint(name = "param1", type =
@DataTypeHint("INTEGER"), isOptional = false),
+ @ArgumentHint(name = "param2", type =
@DataTypeHint("INTEGER"), isOptional = true)}
+)
+public static class NamedParameterProcedure extends Procedure {
+
+ public @DataTypeHint("INT") Integer[] call(ProcedureContext context, Integer
a, Integer b) {
+ return new Integer[] {a + (b == null ? 0 : b)};
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+
+import org.apache.flink.table.annotation.DataTypeHint
+import org.apache.flink.table.annotation.ProcedureHint
+import org.apache.flink.table.procedure.ProcedureContext
+import org.apache.flink.table.procedures.Procedure
+import org.apache.flink.types.Row
+import scala.annotation.varargs
+
+@ProcedureHint(
+ argument = Array(
+ new ArgumentHint(name = "param1", `type` = new DataTypeHint("INTEGER"),
isOptional = false),
+ new ArgumentHint(name = "param2", `type` = new DataTypeHint("INTEGER"),
isOptional = true)
+ )
+)
+class NamedParameterProcedure extends Procedure {
+ def call(context: ProcedureContext, a: Integer, b: Integer): Array[Integer]
= {
+ Array(a + (if (b == null) 0 else b))
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< hint info >}}
+* `@ArgumentHint` 内部包含了 `@DataTypeHint` 注解，因此在 `@ProcedureHint` 中不能同时声明
`input` 和 `argument`, 当作用于函数的参数时 `@ArgumentHint` 也不能和 `@DataTypeHint` 同时使用，推荐使用
`@ArgumentHint`。
+* 命名参数只有在对应的存储过程类不包含重载函数和可变参函数才会生效， 否则使用命名参数会导致报错。
+ {{< /hint >}}
### 在 Catalog 中返回存储过程
在实现了一个存储过程后，Catalog 可以通过方法 `Catalog.getProcedure(ObjectPath procedurePath)`
来返回该存储过程，下面的例子展示了如何在 Catalog 中返回存储过程。
diff --git a/docs/content/docs/dev/table/functions/udfs.md
b/docs/content/docs/dev/table/functions/udfs.md
index b0c095f26b8..1b824387941 100644
--- a/docs/content/docs/dev/table/functions/udfs.md
+++ b/docs/content/docs/dev/table/functions/udfs.md
@@ -77,6 +77,9 @@ env.from("MyTable").select(call("SubstringFunction",
$("myField"), 5, 12));
// call registered function in SQL
env.sqlQuery("SELECT SubstringFunction(myField, 5, 12) FROM MyTable");
+// call registered function in SQL using named parameters
+env.sqlQuery("SELECT SubstringFunction(param1 => myField, param2 => 5, param3
=> 12) FROM MyTable");
+
```
{{< /tab >}}
{{< tab "Scala" >}}
@@ -610,6 +613,140 @@ public static class LiteralFunction extends
ScalarFunction {
For more examples of custom type inference, see also the
`flink-examples-table` module with
{{< gh_link
file="/flink-examples/flink-examples-table/src/main/java/org/apache/flink/table/examples/java/functions/AdvancedFunctionsExample.java"
name="advanced function implementation" >}}.
+### Named Parameters
+
+When calling a function, you can use parameter names to specify the values of
the parameters. Named parameters allow passing both the parameter name and
value to a function, avoiding confusion caused by incorrect parameter order and
improving code readability and maintainability. In addition, named parameters
can also omit optional parameters, which are filled with `null` by default.
+We can use the `@ArgumentHint` annotation to specify the name, type, and
whether a parameter is required or not.
+
+**`@ArgumentHint`**
+
+The following 3 examples demonstrate how to use `@ArgumentHint` in different
scopes. More information can be found in the documentation of the annotation
class.
+
+1. Using `@ArgumentHint` annotation on the parameters of the `eval` method of
the function.
+
+{{< tabs "20405d05-739c-4038-a885-3bde5f7998e8" >}}
+{{< tab "Java" >}}
+```java
+import com.sun.tracing.dtrace.ArgsAttributes;
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+public static class NamedParameterClass extends ScalarFunction {
+
+ // Use the @ArgumentHint annotation to specify the name, type, and whether
a parameter is required.
+ public String eval(@ArgumentHint(name = "param1", isOptional = false, type
= @DataTypeHint("STRING")) String s1,
+ @ArgumentHint(name = "param2", isOptional = true, type
= @DataTypeHint("INT")) Integer s2) {
+ return s1 + ", " + s2;
+ }
+}
+
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+class NamedParameterClass extends ScalarFunction {
+
+ // Use the @ArgumentHint annotation to specify the name, type, and whether a
parameter is required.
+ def eval(@ArgumentHint(name = "param1", isOptional = false, `type` =
@DataTypeHint("STRING")) s1: String,
+ @ArgumentHint(name = "param2", isOptional = true, `type` =
@DataTypeHint("INTEGER")) s2: Integer) = {
+ s1 + ", " + s2
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+2. Using `@ArgumentHint` annotation on the `eval` method of the function.
+
+{{< tabs "dbecd8a8-6285-4bc8-94e0-e79f6ca7f7c3" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+public static class NamedParameterClass extends ScalarFunction {
+
+ // Use the @ArgumentHint annotation to specify the name, type, and whether a
parameter is required.
+ @FunctionHint(
+ argument = {@ArgumentHint(name = "param1", isOptional = false, type
= @DataTypeHint("STRING")),
+ @ArgumentHint(name = "param2", isOptional = true, type =
@DataTypeHint("INTEGER"))}
+ )
+ public String eval(String s1, Integer s2) {
+ return s1 + ", " + s2;
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+class NamedParameterClass extends ScalarFunction {
+
+ // Use the @ArgumentHint annotation to specify the name, type, and whether a
parameter is required.
+ @FunctionHint(
+ argument = Array(new ArgumentHint(name = "param1", isOptional = false,
`type` = new DataTypeHint("STRING")),
+ new ArgumentHint(name = "param2", isOptional = true, `type`
= new DataTypeHint("INTEGER")))
+ )
+ def eval(s1: String, s2: Int): String = {
+ s1 + ", " + s2
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+3. Using `@ArgumentHint` annotation on the class of the function.
+
+{{< tabs "924dd007-3827-44ce-83c6-017dea78b9c4" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+// Use the @ArgumentHint annotation to specify the name, type, and whether a
parameter is required.
+@FunctionHint(
+ argument = {@ArgumentHint(name = "param1", isOptional = false, type =
@DataTypeHint("STRING")),
+ @ArgumentHint(name = "param2", isOptional = true, type =
@DataTypeHint("INTEGER"))}
+)
+public static class NamedParameterClass extends ScalarFunction {
+
+ public String eval(String s1, Integer s2) {
+ return s1 + ", " + s2;
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+import org.apache.flink.table.annotation.ArgumentHint;
+import org.apache.flink.table.functions.ScalarFunction;
+
+// Use the @ArgumentHint annotation to specify the name, type, and whether a
parameter is required.
+@FunctionHint(
+ argument = Array(new ArgumentHint(name = "param1", isOptional = false,
`type` = new DataTypeHint("STRING")),
+ new ArgumentHint(name = "param2", isOptional = true, `type` = new
DataTypeHint("INTEGER")))
+)
+class NamedParameterClass extends ScalarFunction {
+
+ def eval(s1: String, s2: Int): String = {
+ s1 + ", " + s2
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+
+{{< hint info >}}
+* `@ArgumentHint` annotation already contains `@DataTypeHint` annotation, so
it cannot be used together with `@DataTypeHint` in `@FunctionHint`. When
applied to function parameters, `@ArgumentHint` cannot be used with
`@DataTypeHint` at the same time, and it is recommended to use `@ArgumentHint`.
+* Named parameters only take effect when the corresponding class does not
contain overloaded functions and variable parameter functions, otherwise using
named parameters will cause an error.
+{{< /hint >}}
+
### Determinism
Every user-defined function class can declare whether it produces
deterministic results or not by overriding
diff --git a/docs/content/docs/dev/table/procedures.md
b/docs/content/docs/dev/table/procedures.md
index 0122a0de191..fbdbd469121 100644
--- a/docs/content/docs/dev/table/procedures.md
+++ b/docs/content/docs/dev/table/procedures.md
@@ -339,6 +339,150 @@ class OverloadedProcedure extends Procedure {
{{< /tab >}}
{{< /tabs >}}
+### Named Parameters
+
+When calling a procedure, you can use parameter names to specify parameter
values. Named parameters allow you to pass both the parameter name and value to
the procedure at the same time, avoiding confusion caused by the wrong
parameter order, and improving the readability and maintainability of the code.
In addition, named parameters can also omit non-required parameters, which are
filled with `null` by default. We can use the `@ArgumentHint` annotation to
specify the name, type, and whe [...]
+
+The following three examples show how to use `@ArgumentHint` in different
scopes. For more information, please refer to the documentation of the
annotation class.
+
+1. Using `@ArgumentHint` annotation on the parameters of the `call` method of
the procedure.
+
+{{< tabs "5d205654-30da-11ee-be56-0242ac120003" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.ProcedureHint;
+import org.apache.flink.table.procedure.ProcedureContext;
+import org.apache.flink.table.procedures.Procedure;
+import org.apache.flink.types.Row;
+
+public static class NamedParameterProcedure extends Procedure {
+
+ public @DataTypeHint("INT") Integer[] call(ProcedureContext context,
@ArgumentHint(name = "a", isOption = true) Integer a, @ArgumentHint(name = "b")
Integer b) {
+ return new Integer[] {a + (b == null ? 0 : b)};
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+
+import org.apache.flink.table.annotation.DataTypeHint
+import org.apache.flink.table.annotation.ProcedureHint
+import org.apache.flink.table.procedure.ProcedureContext
+import org.apache.flink.table.procedures.Procedure
+import org.apache.flink.types.Row
+import scala.annotation.varargs
+
+class NamedParameterProcedure extends Procedure {
+
+ def call(context: ProcedureContext, @ArgumentHint(name = "param1",
isOptional = true) a: Integer, @ArgumentHint(name = "param2") b: Integer):
Array[Integer] = {
+ Array(a + (if (b == null) 0 else b))
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+2. Using `@ArgumentHint` annotation on the `call` method of the procedure.
+{{< tabs "5d205654-30da-11ee-be56-0242ac120004" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.ProcedureHint;
+import org.apache.flink.table.procedure.ProcedureContext;
+import org.apache.flink.table.procedures.Procedure;
+import org.apache.flink.types.Row;
+
+public static class NamedParameterProcedure extends Procedure {
+
+ @ProcedureHint(
+ argument = {@ArgumentHint(name = "param1", type =
@DataTypeHint("INTEGER"), isOptional = false),
+ @ArgumentHint(name = "param2", type =
@DataTypeHint("INTEGER"), isOptional = true)}
+ )
+ public @DataTypeHint("INT") Integer[] call(ProcedureContext context,
Integer a, Integer b) {
+ return new Integer[] {a + (b == null ? 0 : b)};
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+
+import org.apache.flink.table.annotation.DataTypeHint
+import org.apache.flink.table.annotation.ProcedureHint
+import org.apache.flink.table.procedure.ProcedureContext
+import org.apache.flink.table.procedures.Procedure
+import org.apache.flink.types.Row
+import scala.annotation.varargs
+
+class NamedParameterProcedure extends Procedure {
+ @ProcedureHint(
+ argument = Array(
+ new ArgumentHint(name = "param1", `type` = new DataTypeHint("INTEGER"),
isOptional = false),
+ new ArgumentHint(name = "param2", `type` = new DataTypeHint("INTEGER"),
isOptional = true)
+ )
+ )
+ def call(context: ProcedureContext, a: Integer, b: Integer):
Array[Integer] = {
+ Array(a + (if (b == null) 0 else b))
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+3. Using `@ArgumentHint` annotation on the class of the procedure.
+
+{{< tabs "5d205654-30da-11ee-be56-0242ac120005" >}}
+{{< tab "Java" >}}
+```java
+import org.apache.flink.table.annotation.DataTypeHint;
+import org.apache.flink.table.annotation.ProcedureHint;
+import org.apache.flink.table.procedure.ProcedureContext;
+import org.apache.flink.table.procedures.Procedure;
+import org.apache.flink.types.Row;
+
+@ProcedureHint(
+ argument = {@ArgumentHint(name = "param1", type =
@DataTypeHint("INTEGER"), isOptional = false),
+ @ArgumentHint(name = "param2", type =
@DataTypeHint("INTEGER"), isOptional = true)}
+)
+public static class NamedParameterProcedure extends Procedure {
+
+ public @DataTypeHint("INT") Integer[] call(ProcedureContext context, Integer
a, Integer b) {
+ return new Integer[] {a + (b == null ? 0 : b)};
+ }
+}
+```
+{{< /tab >}}
+{{< tab "Scala" >}}
+```scala
+
+import org.apache.flink.table.annotation.DataTypeHint
+import org.apache.flink.table.annotation.ProcedureHint
+import org.apache.flink.table.procedure.ProcedureContext
+import org.apache.flink.table.procedures.Procedure
+import org.apache.flink.types.Row
+import scala.annotation.varargs
+
+@ProcedureHint(
+ argument = Array(
+ new ArgumentHint(name = "param1", `type` = new DataTypeHint("INTEGER"),
isOptional = false),
+ new ArgumentHint(name = "param2", `type` = new DataTypeHint("INTEGER"),
isOptional = true)
+ )
+)
+class NamedParameterProcedure extends Procedure {
+ def call(context: ProcedureContext, a: Integer, b: Integer): Array[Integer]
= {
+ Array(a + (if (b == null) 0 else b))
+ }
+}
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+{{< hint info >}}
+* `@ArgumentHint` annotation already contains `@DataTypeHint` annotation, so
it cannot be used together with `@DataTypeHint` in `@ProcedureHint`. When
applied to function parameters, `@ArgumentHint` cannot be used with
`@DataTypeHint` at the same time, and it is recommended to use `@ArgumentHint`.
+* Named parameters only take effect when the corresponding procedure class
does not contain overloaded functions and variable parameter functions,
otherwise using named parameters will cause an error.
+{{< /hint >}}
### Return Procedure in Catalog
After implementing a procedure, the catalog can then return the procedure in
method `Catalog.getProcedure(ObjectPath procedurePath)`. The following example
shows how to return it in a catalog.
