You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ja...@apache.org on 2022/12/30 09:32:58 UTC
[iotdb] branch master updated: modify doc of register UDF (#8681)
This is an automated email from the ASF dual-hosted git repository.
jackietien pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new 3d85d27d21 modify doc of register UDF (#8681)
3d85d27d21 is described below
commit 3d85d27d21f108d02abb975d1b01ce3b56b68946
Author: Weihao Li <60...@users.noreply.github.com>
AuthorDate: Fri Dec 30 17:32:52 2022 +0800
modify doc of register UDF (#8681)
---
docs/UserGuide/Operators-Functions/Overview.md | 2 +-
.../Operators-Functions/User-Defined-Function.md | 41 ++++++++++++++--------
docs/zh/UserGuide/Operators-Functions/Overview.md | 2 +-
.../Operators-Functions/User-Defined-Function.md | 36 +++++++++++++------
4 files changed, 53 insertions(+), 28 deletions(-)
diff --git a/docs/UserGuide/Operators-Functions/Overview.md b/docs/UserGuide/Operators-Functions/Overview.md
index af44a10758..f00b3b2d37 100644
--- a/docs/UserGuide/Operators-Functions/Overview.md
+++ b/docs/UserGuide/Operators-Functions/Overview.md
@@ -53,7 +53,7 @@ It effectively meets the demand for data quality in the industrial field.
## Quick Start
1. Download the JAR with all dependencies and the script of registering UDF.
-2. Copy the JAR package to `ext\udf` under the directory of IoTDB system.
+2. Copy the JAR package to `ext\udf` under the directory of IoTDB system (Please put JAR to this directory of all DataNodes if you use Cluster).
3. Run `sbin\start-server.bat` (for Windows) or `sbin\start-server.sh` (for Linux or MacOS) to start IoTDB server.
4. Copy the script to the directory of IoTDB system (under the root directory, at the same level as `sbin`), modify the parameters in the script if needed and run it to register UDF.
diff --git a/docs/UserGuide/Operators-Functions/User-Defined-Function.md b/docs/UserGuide/Operators-Functions/User-Defined-Function.md
index 5bcaf94630..1fe8447e04 100644
--- a/docs/UserGuide/Operators-Functions/User-Defined-Function.md
+++ b/docs/UserGuide/Operators-Functions/User-Defined-Function.md
@@ -407,34 +407,44 @@ The process of registering a UDF in IoTDB is as follows:
1. Implement a complete UDF class, assuming the full class name of this class is `org.apache.iotdb.udf.ExampleUDTF`.
2. Package your project into a JAR. If you use Maven to manage your project, you can refer to the Maven project example above.
-3. Optional. You can place the JAR package in the directory `iotdb-server-1.0.0-all-bin/ext/udf`.
- **Note that if you choose to place the JAR in advance when deploying a cluster, you need to ensure that there is a corresponding JAR package in the UDF JAR package path of each node. **
- The URI of the JAR package to use can also be specified in the SQL. We will try to download the JAR package and distribute it to each node in the cluster, placing it in the directory `iotdb-server-1.0.0-all-bin/ext/udf/install`.
-
- > You can specify the root path for the UDF to load the Jar by modifying the 'udf_root_dir' in the configuration file.
-4. Register the UDF with the SQL statement, assuming that the name given to the UDF is `example`.
-
-The following shows the SQL syntax of how to register a UDF.
-
+3. Make preparations for registration according to the registration mode. For details, see the following example.
+4. You can use following SQL to register UDF.
```sql
CREATE FUNCTION <UDF-NAME> AS <UDF-CLASS-FULL-PATHNAME> (USING URI URI-STRING)?
```
-Here is an example:
+### Example: register UDF named `example`, you can choose either of the following two registration methods
+
+#### No URI
+
+Prepare:
+When use this method to register，you should put JAR to directory `iotdb-server-1.0.0-all-bin/ext/udf`（directory can config）.
+**Note，you should put JAR to this directory of all DataNodes if using Cluster**
+SQL:
```sql
-CREATE FUNCTION example AS 'org.apache.iotdb.udf.ExampleUDTF' USING URI 'http://jar/example.jar'
+CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample'
```
-Since UDF instances are dynamically loaded through reflection technology, you do not need to restart the server during the UDF registration process.
+#### Using URI
-Note: UDF function names are not case sensitive.
+Prepare:
+When use this method to register，you need to upload the JAR to URI server and ensure the IoTDB instance executing this registration statement has access to the URI server.
+**Note，you needn't place JAR manually，IoTDB will download the JAR and sync it.**
-Note: Please ensure that the function name given to the UDF is different from all built-in function names. A UDF with the same name as a built-in function cannot be registered.
+SQL:
+```sql
+CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample' USING URI 'http://jar/example.jar'
+```
+
+### Note
+Since UDF instances are dynamically loaded through reflection technology, you do not need to restart the server during the UDF registration process.
-Note: We recommend that you do not use classes that have the same class name but different function logic in different JAR packages. For example, in `UDF(UDAF/UDTF): udf1, udf2`, the JAR package of udf1 is `udf1.jar` and the JAR package of udf2 is `udf2.jar`. Assume that both JAR packages contain the `org.apache.iotdb.udf.ExampleUDTF` class. If you use two UDFs in the same SQL statement at the same time, the system will randomly load either of them and may cause inconsistency in UDF exec [...]
+UDF function names are not case-sensitive.
+Please ensure that the function name given to the UDF is different from all built-in function names. A UDF with the same name as a built-in function cannot be registered.
+We recommend that you do not use classes that have the same class name but different function logic in different JAR packages. For example, in `UDF(UDAF/UDTF): udf1, udf2`, the JAR package of udf1 is `udf1.jar` and the JAR package of udf2 is `udf2.jar`. Assume that both JAR packages contain the `org.apache.iotdb.udf.ExampleUDTF` class. If you use two UDFs in the same SQL statement at the same time, the system will randomly load either of them and may cause inconsistency in UDF execution [...]
## UDF Deregistration
@@ -528,6 +538,7 @@ For more user permissions related content, please refer to [Account Management S
## Configurable Properties
+You can use `trigger_lib_dir` to config trigger lib directory.
When querying by a UDF, IoTDB may prompt that there is insufficient memory. You can resolve the issue by configuring `udf_initial_byte_array_length_for_memory_control`, `udf_memory_budget_in_mb` and `udf_reader_transformer_collector_memory_proportion` in `iotdb-datanode.properties` and restarting the server.
diff --git a/docs/zh/UserGuide/Operators-Functions/Overview.md b/docs/zh/UserGuide/Operators-Functions/Overview.md
index bf4ef5d1cf..bbcbf0fee1 100644
--- a/docs/zh/UserGuide/Operators-Functions/Overview.md
+++ b/docs/zh/UserGuide/Operators-Functions/Overview.md
@@ -234,6 +234,6 @@ OR, |, ||
**该函数库中的函数不是内置函数，使用前要先加载到系统中。** 操作流程如下：
1. 下载包含全部依赖的 jar 包和注册脚本 [【点击下载】](https://archive.apache.org/dist/iotdb/0.14.0-preview3/apache-iotdb-0.14.0-preview3-library-udf-bin.zip) ；
-2. 将 jar 包复制到 IoTDB 程序目录的 `ext\udf` 目录下；
+2. 将 jar 包复制到 IoTDB 程序目录的 `ext\udf` 目录下 (若您使用的是集群，请将jar包复制到所有DataNode的该目录下)；
3. 启动 IoTDB；
4. 将注册脚本复制到 IoTDB 的程序目录下（与`sbin`目录同级的根目录下），修改脚本中的参数（如果需要）并运行注册脚本以注册 UDF。
\ No newline at end of file
diff --git a/docs/zh/UserGuide/Operators-Functions/User-Defined-Function.md b/docs/zh/UserGuide/Operators-Functions/User-Defined-Function.md
index 6a49cf4458..4ed98d07ed 100644
--- a/docs/zh/UserGuide/Operators-Functions/User-Defined-Function.md
+++ b/docs/zh/UserGuide/Operators-Functions/User-Defined-Function.md
@@ -372,31 +372,44 @@ UDTF 的结束方法，您可以在此方法中进行一些资源释放等的操
1. 实现一个完整的 UDF 类，假定这个类的全类名为`org.apache.iotdb.udf.UDTFExample`
2. 将项目打成 JAR 包，如果您使用 Maven 管理项目，可以参考上述 Maven 项目示例的写法
-3. 可选项。您可以提前将 JAR 包放置到目录 `iotdb-server-1.0.0-all-bin/ext/udf` 下。
- **注意，在部署集群的时候，如果您想将 JAR 包提前放到指定目录下，需要保证每一个节点的 UDF JAR 包路径下都存在相应的 JAR 包。** 您也可以在注册 UDF 的 SQL 中指定要使用的 JAR 包的 URI，我们会尝试下载该 JAR 包并分发到集群中的每个节点，放置在 `iotdb-server-1.0.0-all-bin/ext/udf/install` 下。
-
- > 您可以通过修改配置文件中的`udf_root_dir`来指定 UDF 加载 Jar 的根路径。
-4. 使用 SQL 语句注册该 UDF，假定赋予该 UDF 的名字为`example`
+3. 进行注册前的准备工作，根据注册方式的不同需要做不同的准备，具体可参考以下例子
+4. 使用以下 SQL 语句注册 UDF
+```sql
+CREATE FUNCTION <UDF-NAME> AS <UDF-CLASS-FULL-PATHNAME> (USING URI URI-STRING)?
+```
-注册 UDF 的 SQL 语法如下：
+### 示例：注册名为`example`的 UDF，以下两种注册方式任选其一即可
+#### 不指定URI
+
+准备工作：
+使用该种方式注册时，您需要提前将 JAR 包放置到目录 `iotdb-server-1.0.0-all-bin/ext/udf`（该目录可配置） 下。
+**注意，如果您使用的是集群，那么需要将 JAR 包放置到所有 DataNode 的该目录下**
+
+注册语句：
```sql
-CREATE FUNCTION <UDF-NAME> AS <UDF-CLASS-FULL-PATHNAME> (USING URI URI-STRING)?
+CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample'
```
-例子中注册 UDF 的 SQL 语句如下：
+#### 指定URI
+
+准备工作：
+使用该种方式注册时，您需要提前将 JAR 包上传到 URI 服务器上并确保执行注册语句的 IoTDB 实例能够访问该 URI 服务器。
+**注意，您无需手动放置 JAR 包，IoTDB 会下载 JAR 包并正确同步到整个集群**
+注册语句：
```sql
CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample' USING URI 'http://jar/example.jar'
```
+### 注意
由于 IoTDB 的 UDF 是通过反射技术动态装载的，因此您在装载过程中无需启停服务器。
-注意：UDF 函数名称是大小写不敏感的。
+UDF 函数名称是大小写不敏感的。
-注意：请不要给 UDF 函数注册一个内置函数的名字。使用内置函数的名字给 UDF 注册会失败。
+请不要给 UDF 函数注册一个内置函数的名字。使用内置函数的名字给 UDF 注册会失败。
-注意：不同的 JAR 包中最好不要有全类名相同但实现功能逻辑不一样的类。例如 UDF(UDAF/UDTF)：`udf1`、`udf2`分别对应资源`udf1.jar`、`udf2.jar`。如果两个 JAR 包里都包含一个`org.apache.iotdb.udf.UDTFExample`类，当同一个 SQL 中同时使用到这两个 UDF 时，系统会随机加载其中一个类，导致 UDF 执行行为不一致。
+不同的 JAR 包中最好不要有全类名相同但实现功能逻辑不一样的类。例如 UDF(UDAF/UDTF)：`udf1`、`udf2`分别对应资源`udf1.jar`、`udf2.jar`。如果两个 JAR 包里都包含一个`org.apache.iotdb.udf.UDTFExample`类，当同一个 SQL 中同时使用到这两个 UDF 时，系统会随机加载其中一个类，导致 UDF 执行行为不一致。
## UDF 卸载
@@ -476,6 +489,7 @@ SHOW FUNCTIONS
## 配置项
+使用配置项 `trigger_lib_dir` 来配置 trigger 的存储目录.
在 SQL 语句中使用自定义函数时，可能提示内存不足。这种情况下，您可以通过更改配置文件`iotdb-datanode.properties`中的`udf_initial_byte_array_length_for_memory_control`，`udf_memory_budget_in_mb`和`udf_reader_transformer_collector_memory_proportion`并重启服务来解决此问题。
## 贡献 UDF