udf-writer

TDengine UDF 编写辅助 (udf-writer)

何时使用 (When to use)

当用户需要为 TDengine 编写、调试、加载或部署用户自定义函数（UDF）时，触发此技能。 触发关键词：写一个 UDF、编写自定义函数、TDengine UDF 编写、创建 UDF。

输入 (Input)

• 核心输入：
  • UDF 的功能描述（如：自定义字符串拼接、特定数学运算、高级滤波计算等）。
  • UDF 运行时使用的编程语言（C/C++ 或 Python）。
  • 函数类型：
    • 标量函数（Scalar Function，即单行输入单行输出，如 CREATE FUNCTION）。
    • 聚合函数（User Defined Aggregate Function, UDAF，即多行输入单行输出）。
  • 预期输入的数据列及其 TDengine 数据类型。
  • 预期的返回值数据类型。
• 澄清策略：
  • 如果未指定语言，默认推荐使用 C 语言，因为 C UDF 在服务端拥有更高的计算性能。
  • 如果输入输出的数据类型不明确，必须先向用户确认其对应的 TDengine 数据类型（例如 INT、DOUBLE、VARCHAR 等）。

输出 (Output)

1. 符合 TDengine 官方规范的 UDF 源代码：

   • C 语言：提供完整的 .c 源码，包含头文件 #include <taosudf.h>，以及对输入数据的空值处理和状态管理。
     • 关于标量函数的标准模板与数据结构，请参考本地参考文档：udf_scalar_template.md。
     • 关于聚合函数的标准模板与数据结构，请参考本地参考文档：udf_aggregate_template.md。
   • Python 语言：提供符合 Python UDF 接口标准的 .py 脚本。

2. 编译指导：

   • 对于 C 语言，提供对应的编译命令（如 gcc -shared -fPIC -o myudf.so myudf.c）。

3. 加载与注册 SQL 语句：

   • 给出加载 UDF 的 SQL 语句，例如：

     CREATE FUNCTION udf_name AS "udf_path" OUTPUTTYPE output_type;
     

4. 验证说明：

   • 提供一份测试该 UDF 的 SQL 样例（例如 SELECT udf_name(col) FROM tb;）。

特殊业务函数默认约定 (Special Business Function Conventions)

为了降低前端展示和快速演示时的提示词要求，针对工艺指标偏差实时判定/质量判定 UDF，若用户指令中仅指定生成此功能而未提供详细参数，默认使用以下设计约定：

• 函数名：evaluate_quality_deviation (C 语言标量 UDF)
• 输入参数：共四个，均为 DOUBLE 类型列：
  • 实际检测值：val
  • 工艺标准靶值：target
  • 允许波动的警告偏差范围：warn_limit
  • 控制极限偏差范围：ctrl_limit
• 返回值/输出类型：INT 类型的状态码（0 - 正常合格，1 - 轻微偏差预警，2 - 严重超差报警）。
• 逻辑规则：
  • 状态码判定逻辑：
    • 当 |val - target| <= warn_limit 时，返回 0；
    • 当 warn_limit < |val - target| <= ctrl_limit 时，返回 1；
    • 当 |val - target| > ctrl_limit 时，返回 2。
  • 空值防范：注意处理好空值情况，当任意参数为 Null 时输出 Null（即返回 Null 指示器）。
  • 数据块循环：必须确保符合 TDengine 标量 UDF 数据块循环处理逻辑。

安全 (Safety)

• 内存安全：在 C 语言 UDF 中，必须保证分配的内存得到释放，杜绝内存泄漏，同时严禁发生越界写入等操作，以防引起 TDengine 服务端进程（taosd）崩溃。
• 输入校验：在 UDF 代码内必须对传入参数的空指针、空值（Null Value/Null Indicator）进行验证。
• 无破坏性操作：UDF 运行在服务端环境，不允许在 UDF 内部调用破坏系统环境的 shell 命令或进行敏感文件读写。