[GitHub] asfgit closed pull request #6356: [FLINK-9790] [doc] Add documentation for UDF in SQL Client

[GitBox <gi...@apache.org>]

asfgit closed pull request #6356: [FLINK-9790] [doc] Add documentation for UDF in SQL Client
URL: https://github.com/apache/flink/pull/6356
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/docs/dev/table/sqlClient.md b/docs/dev/table/sqlClient.md
index 24af6557dc6..d7d1548b978 100644
--- a/docs/dev/table/sqlClient.md
+++ b/docs/dev/table/sqlClient.md
@@ -181,6 +181,24 @@ tables:
       line-delimiter: "\n"
       comment-prefix: "#"
 
+# Define the user-defined functions here.
+
+functions:
+  - name: myUDF
+    from: class
+    class: foo.bar.AggregateUDF
+    constructor:
+      - 7.6
+      - 1
+      - StarryName
+      - false
+      - class: java.lang.Integer
+        constructor:
+          - class: java.lang.String
+            constructor:
+              - type: VARCHAR
+                value: 3
+
 # Execution properties allow for changing the behavior of a table program.
 
 execution:
@@ -202,6 +220,7 @@ deployment:
 This configuration:
 
 - defines an environment with a table source `MyTableName` that reads from a CSV file,
+- defines a user-defined function `myUDF` that can be instantiated with the class name and the five constructor parameters,
 - specifies a parallelism of 1 for queries executed in this streaming environment,
 - specifies an event-time characteristic, and
 - runs queries in the `table` result mode.
@@ -631,6 +650,85 @@ Avro uses [Joda-Time](http://www.joda.org/joda-time/) for representing logical d
 
 Make sure to download the [Apache Avro SQL JAR](sqlClient.html#dependencies) file and pass it to the SQL Client.
 
+{% top %}
+
+User-defined Functions
+--------------------
+The SQL Client allows users to create user-defined functions, which can be used in queries, on their needs.
+Currently, these functions are restricted to be defined in classes.
+
+To enable a user-defined function, you should first implement and compile a function class that extends `ScalarFunction`, `AggregateFunction` or `TableFunction` (see [User-defined Functions]( {{ site.baseurl }}/dev/table/udfs.html))
+and then package it into a dependency JAR of the SQL Client.
+
+All the functions must be declared with the configuration properties before being called.
+For each item in the list property `functions`, you should specify a `name`, with which the function is registered in the `TableEnvironment`, a `from`, which is restricted to be `class` now,
+a `class`, which indicates the full class name of the function and an optional list of constructor parameters for instantiation.
+Just make sure that the order and types of the specified parameters are strictly match one of the constructors of your function class.
+
+{% highlight yaml %}
+functions:
+  - name: ...               # required: name of the function
+    from: class             # required: source of the function (can only be class now)
+    class: ...              # required: full class name of the function
+    constructor:            # optimal: constructor parameters of the function class
+      - ...                 # optimal: a literal parameter with implicit type
+      - class: ...          # optimal: full class name of the parameter
+        constructor:        # optimal: constructor parameters of the parameter's class
+          - type: ...       # optimal: type of the literal parameter
+            value: ...      # optimal: value of the literal parameter
+{% endhighlight %}
+
+### Constructor Parameters
+
+As shown before, when declaring a user-defined function, each constructor parameter can be one of the following three forms.
+
+**A literal value with implicit type.** 
+Currently, only values of `BOOLEAN`, `INT`, `DOUBLE` and `VARCHAR` are supported in this form and the SQL Client will automatically derive the type according to the literal value itself.
+If the automatic derivation does not work as expected (e.g., you need a VARCHAR `false`), use the next form instead.
+{% highlight yaml %}
+- true         # -> BOOLEAN (case sensitive)
+- 42           # -> INT
+- 1234.222     # -> DOUBLE
+- foo          # -> VARCHAR
+{% endhighlight %}
+
+**A literal value with explicit type.**
+You can also explicitly declare the type of a parameter with a `type` and a `value` properties for some purposes.
+{% highlight yaml %}
+- type: DECIMAL
+  value: 11111111111111111
+{% endhighlight %}
+The table below illustrates the supported parameter types and the corresponding SQL types (which should be used in configurations).
+More types (e.g., `TIMESTAMP` and `ARRAY`) are going to be supported in the future.
+
+| Parameter type          |  SQL type         |
+| :---------------------- | :---------------- |
+| `java.math.BigDecimal`  | `DECIMAL`         |
+| `java.lang.Boolean`     | `BOOLEAN`         |
+| `java.lang.Byte`        | `TINYINT`         |
+| `java.lang.Double`      | `DOUBLE`          |
+| `java.lang.Float`       | `REAL`, `FLOAT`   |
+| `java.lang.Integer`     | `INTETER`, `INT`  |
+| `java.lang.Long`        | `BIGINT`          |
+| `java.lang.Short`       | `SMALLINT`        |
+| `java.lang.String`      | `VARCHAR`         |
+
+**A class instance.**
+Besides literal values, you can also create class instances for the constructor parameters by specifying the `class` and `constructor` properties.
+This process can be recursively performed until all the constructor parameters are represented with literal values.
+{% highlight yaml %}
+- class: foo.bar.paramClass
+  constructor:
+    - StarryName
+    - class: java.lang.Integer
+      constructor:
+        - class: java.lang.String
+          constructor:
+            - type: VARCHAR
+              value: 3
+{% endhighlight %}
+
+
 {% top %}
 
 Limitations & Future


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services