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 2021/01/06 05:18:48 UTC
[iotdb] branch master updated: add the udf contribution guide
(#2429)
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 6d15e3c add the udf contribution guide (#2429)
6d15e3c is described below
commit 6d15e3c323dd06b418eb8675085e37f1d01c50f1
Author: Steve Yurong Su <st...@outlook.com>
AuthorDate: Wed Jan 6 13:18:23 2021 +0800
add the udf contribution guide (#2429)
---
.../Operation Manual/UDF User Defined Function.md | 58 +++++++++++++++++++++
.../Operation Manual/UDF User Defined Function.md | 60 ++++++++++++++++++++++
2 files changed, 118 insertions(+)
diff --git a/docs/UserGuide/Operation Manual/UDF User Defined Function.md b/docs/UserGuide/Operation Manual/UDF User Defined Function.md
index 76269d1..e744d8b 100644
--- a/docs/UserGuide/Operation Manual/UDF User Defined Function.md
+++ b/docs/UserGuide/Operation Manual/UDF User Defined Function.md
@@ -389,6 +389,7 @@ 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. Place the JAR package in the directory `iotdb-server-0.12.0-SNAPSHOT/ext/udf` or in a subdirectory of `iotdb-server-0.12.0-SNAPSHOT/ext/udf`.
+
> 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`.
@@ -498,6 +499,63 @@ When querying by a UDF, IoTDB may prompt that there is insufficient memory. You
+## Contribute UDF
+
+<!-- The template is copied and modified from the Apache Doris community-->
+
+This part mainly introduces how external users can contribute their own UDFs to the IoTDB community.
+
+
+
+### Prerequisites
+
+1. UDFs must be universal.
+
+ The "universal" mentioned here refers to: UDFs can be widely used in some scenarios. In other words, the UDF function must have reuse value and may be directly used by other users in the community.
+
+ If you are not sure whether the UDF you want to contribute is universal, you can send an email to `dev@iotdb.apache.org` or create an issue to initiate a discussion.
+
+2. The UDF you are going to contribute has been well tested and can run normally in the production environment.
+
+
+
+### What you need to prepare
+
+1. UDF source code
+2. Test cases
+3. Instructions
+
+
+
+#### UDF Source Code
+
+1. Create the UDF main class and related classes in `src/main/java/org/apache/iotdb/db/query/udf/builtin` or in its subfolders.
+2. Register your UDF in `src/main/java/org/apache/iotdb/db/query/udf/builtin/BuiltinFunction.java`.
+
+
+
+#### Test Cases
+
+At a minimum, you need to write integration tests for the UDF.
+
+You can add a test class in `server/src/test/java/org/apache/iotdb/db/integration`.
+
+
+
+#### Instructions
+
+The instructions need to include: the name and the function of the UDF, the attribute parameters that must be provided when the UDF is executed, the applicable scenarios, and the usage examples, etc.
+
+The instructions should be added in `docs/UserGuide/Operation Manual/DML Data Manipulation Language.md`.
+
+
+
+### Submit a PR
+
+When you have prepared the UDF source code, test cases, and instructions, you are ready to submit a Pull Request (PR) on [Github](https://github.com/apache/iotdb). You can refer to our code contribution guide to submit a PR: [Pull Request Guide](https://iotdb.apache.org/Development/HowToCommit.html).
+
+
+
## Q&A
Q1: **How to modify the registered UDF? **
diff --git a/docs/zh/UserGuide/Operation Manual/UDF User Defined Function.md b/docs/zh/UserGuide/Operation Manual/UDF User Defined Function.md
index fa9f3e2..4ace6fe 100644
--- a/docs/zh/UserGuide/Operation Manual/UDF User Defined Function.md
+++ b/docs/zh/UserGuide/Operation Manual/UDF User Defined Function.md
@@ -388,6 +388,7 @@ UDTF的结束方法，您可以在此方法中进行一些资源释放等的操
1. 实现一个完整的UDF类，假定这个类的全类名为`org.apache.iotdb.udf.ExampleUDTF`
2. 将项目打成JAR包，如果您使用Maven管理项目，可以参考上述Maven项目示例的写法
3. 将JAR包放置到目录 `iotdb-server-0.12.0-SNAPSHOT/ext/udf` （也可以是`iotdb-server-0.12.0-SNAPSHOT/ext/udf`的子目录）下。
+
> 您可以通过修改配置文件中的`udf_root_dir`来指定UDF加载Jar的根路径。
4. 使用SQL语句注册该UDF，假定赋予该UDF的名字为`example`
@@ -499,6 +500,65 @@ SHOW FUNCTIONS
+## 贡献UDF
+
+<!-- The template is copied and modified from the Apache Doris community-->
+
+该部分主要讲述了外部用户如何将自己编写的 UDF 贡献给 IoTDB 社区。
+
+
+
+### 前提条件
+
+1. UDF 具有通用性。
+
+ 通用性主要指的是：UDF 在某些业务场景下，可以被广泛使用。换言之，就是 UDF 具有复用价值，可被社区内其他用户直接使用。
+
+ 如果您不确定自己写的 UDF 是否具有通用性，可以发邮件到 `dev@iotdb.apache.org` 或直接创建 ISSUE 发起讨论。
+
+2. UDF 已经完成测试，且能够正常运行在用户的生产环境中。
+
+
+
+### 贡献清单
+
+1. UDF 的源代码
+2. UDF 的测试用例
+3. UDF 的使用说明
+
+
+
+#### 源代码
+
+1. 在`src/main/java/org/apache/iotdb/db/query/udf/builtin`或者它的子文件夹中创建 UDF 主类和相关的辅助类。
+2. 在`src/main/java/org/apache/iotdb/db/query/udf/builtin/BuiltinFunction.java`中注册您编写的 UDF。
+
+
+
+#### 测试用例
+
+您至少需要为您贡献的 UDF 编写集成测试。
+
+您可以在`server/src/test/java/org/apache/iotdb/db/integration`中为您贡献的 UDF 新增一个测试类进行测试。
+
+
+
+#### 使用说明
+
+使用说明需要包含：UDF 的名称、UDF的作用、执行函数必须的属性参数、函数的适用的场景以及使用示例等。
+
+使用说明需包含中英文两个版本。应分别在 `docs/zh/UserGuide/Operation Manual/DML Data Manipulation Language.md` 和 `docs/UserGuide/Operation Manual/DML Data Manipulation Language.md` 中新增使用说明。
+
+
+
+### 提交PR
+
+当您准备好源代码、测试用例和使用说明后，就可以将 UDF 贡献到 IoTDB 社区了。在 [Github](https://github.com/apache/iotdb) 上面提交 Pull Request (PR) 即可。具体提交方式见：[Pull Request Guide](https://iotdb.apache.org/Development/HowToCommit.html)。
+
+当 PR 评审通过并被合并后，您的 UDF 就已经贡献给 IoTDB 社区了！
+
+
+
## Q&A
**Q1: 如何修改已经注册的UDF？**