自定义函数

KaiwuDB 支持使用 Lua 脚本、SQL语言在时序和关系数据库中创建、使用、查看和删除自定义函数。自定义函数的使用方式与 KaiwuDB 其他函数相似。

创建自定义函数

所需权限

• 非三权分立模式下，用户是 admin 角色的成员或者拥有当前数据库的 CREATE 权限和自定义函数中引用的所有对象的相关权限（例如表的 SELECT 权限）。默认情况下，sysroot 用户属于 sysadmin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员或者是拥有当前数据库 CREATE 权限和自定义函数中引用的所有对象的相关权限（例如表的 SELECT 权限）的普通用户。默认情况下，sysroot 用户属于 sysadmin 角色。
• 调用时，需要拥有目标自定义函数 EXECUTE 权限和自定义函数中引用的所有对象的相关权限（例如表的 SELECT 权限）的普通用户。

语法格式

参数说明

参数	说明
function_name	自定义函数的名称。
arguments	函数参数，需指定参数名称和参数类型，支持的类型包括 TIMESTAMP、INT2、INT4、INT8、FLOAT4、FLOAT8、DECIMAL、CITEXT、CHAR、VARCHAR、NCHAR 和 NVARCHAR。支持指定多个参数，参数之间使用逗号（,）隔开。
return_type	返回类型。支持的类型包括 TIMESTAMP、INT2、INT4、INT8、FLOAT4、FLOAT8、DECIMAL、CITEXT、CHAR、VARCHAR、NCHAR 和 NVARCHAR。
lang_name	函数实现语言，支持LUA、SQL两种。
function_content	函数内容，需要使用单引号（''）将函数内容括起来。如果函数内容中包含特殊字符，系统会自动进行转义，例如单引号（''） 会被转义为'。

注意

• 自定义函数名称支持两段式/三段式解析。裸函数名按着当前数据库与schema解析，两段式/三段式函数名按着指定数据库与schema解析。
• 自定义函数注册为标量函数。
• 不支持函数重载。
• CREATE FUNCTION 必须显式指定返回值类型，返回值类型仅支持标量值。
• 函数体使用SQL语言时，支持DECLARE变量声明、SET变量赋值、SELECT查询语句、IF条件判断语句、WHILE循环语句、LEAVE跳出循环语句。不支持INSERT/UPDATE/DELETE/UPSERT、COMMIT、ROLLBACK、游标、PREPARE/EXCUTE语句。

语法示例

以下示例假设已经创建 power 时序数据库 、consumption 时序表，并向时序表中写入数据。

-- 1. 创建 power 时序数据库。

CREATE TS DATABASE power;
CREATE TS DATABASE

-- 2. 切换到 power 时序数据库。

USE power;
SET

-- 3. 创建 consumption 时序表。

CREATE TABLE consumption (k_timestamp timestamp not null,c1 int,c2 int) tags (site int not null) primary tags (site);
CREATE TABLE

-- 4. 设置时序数据库的时区。
SET timezone = 8;
SET

-- 5. 向 consumption 时序表中写入数据。

INSERT INTO consumption VALUES('2024-1-1 1:00:00',1,2,1),('2024-1-1 1:00:00',2,4,1),('2024-1-1 2:00:00',6,3,1),('2024-1-1 5:00:00',8,12,1),('2024-1-1 5:00:00',0,3,1);
INSERT 5

使用lua语言创建自定义函数

-- 1. 使用LUA语言创建 calculate_growth_rate 自定义函数。

CREATE FUNCTION calculate_growth_rate(previous_consumption int, current_consumption int)
    RETURNS FLOAT
    LANGUAGE LUA
BEGIN
'function calculate_growth_rate(previous_consumption, current_consumption)
  if previous_consumption == 0 then
        return nil
    end
  return (current_consumption - previous_consumption) / previous_consumption
end'
END;
CREATE FUNCTION

-- 2. 使用 calculate_growth_rate 自定义函数。

SELECT calculate_growth_rate(c1,c2) from consumption where k_timestamp >= '2024-1-1 1:00:00' and k_timestamp <= '2024-1-1 5:00:00';

    calculate_growth_rate
----------------------------------
                        1
                      -0.5
NULL
(3 rows)

使用SQL语言创建并调用自定义函数 fn_calculate_growth_rate

-- 1、 使用SQL语言创建函数 fn_calculate_growth_rate
DELIMITER \\
CREATE FUNCTION fn_calculate_growth_rate(
    p_previous_consumption int,
    p_current_consumption  int
)
RETURNS DECIMAL
LANGUAGE SQL 
BEGIN
    -- 处理NULL或上期为0的情况，直接返回NULL
    IF p_previous_consumption IS NULL OR p_previous_consumption = 0 
	THEN select 0.0;
    ELSE 
    -- 正常计算增长率
    select (p_current_consumption - p_previous_consumption) / p_previous_consumption;
	ENDIF;
END \\
DELIMITER ;

-- 2、使用 growth_rate 函数
select fn_calculate_growth_rate(c1,c2) from consumption;
  fn_calculate_growth_rate
----------------------------
                         1
                      -0.5
                       0.0
(3 rows)

查看自定义函数

SHOW FUNCTIONS 语句用于查看所有自定义函数或指定的自定义函数的具体信息。

所需权限

无

语法格式

• 查看所有自定义函数

  

• 查看指定的自定义函数的信息

  

参数说明

参数	说明
function_name	待查看的自定义函数的名称。

语法示例

• 查看所有自定义函数。

  SHOW FUNCTIONS;
  

  执行成功后，控制台输出以下信息：

        function_name
  ---------------------------
    calculate_growth_rate
  

• 查看指定自定义函数信息。

  SHOW FUNCTION calculate_growth_rate;
  

  执行成功后，控制台输出以下信息：

        function_name     | argument_types | return_type | function_type | language
  ------------------------+----------------+-------------+---------------+-----------
    calculate_growth_rate | INT, INT       | DOUBLE      | function      | LUA
  (1 row)
  

查看自定义函数的的创建语句

SHOW CREATE [FUNCTION] <function_name> 语句用于查看当前或指定数据库下指定自定义函数的创建语句。如未指定数据库，则默认为当前数据库。

所需权限

用户拥有目标函数的任何权限。

语法格式

参数说明

参数	说明
database_name	函数所在的数据库的名称。如未指定，则默认使用当前数据库。
function_name	待查看函数的名称。

语法示例

• 查看当前数据库中指定函数的创建语句。

  以下示例查看当前数据库中 calculate_growth_rate 的创建语句。

  -- 查看已创建的自定义函数的创建语句。
  
  SHOW CREATE FUNCTION calculate_growth_rate;
        function_name     |                                      function_body
  ------------------------+-------------------------------------------------------------------------------------------
  calculate_growth_rate | CREATE FUNCTION calculate_growth_rate(previous_consumption INT, current_consumption INT)
                      | RETURNS FLOAT8
                      | LANGUAGE LUA
                      | BEGIN
                      | 'function calculate_growth_rate(previous_consumption, current_consumption)
                      |   if previous_consumption == 0 then
                      |         return nil
                      |     end
                      |   return (current_consumption - previous_consumption) / previous_consumption
                      | end'
                      | END
  (1 row)
  

删除自定义函数

DROP FUNCTION 语句用于删除自定义函数。

所需权限

• 非三权分立模式下，用户是 admin 角色的成员或者拥有目标自定义函数的 DROP 权限。默认情况下，root 用户属于 admin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员或者是拥有目标自定义函数 DROP 权限的普通用户。默认情况下，sysroot 用户属于 sysadmin 角色。

语法格式

参数说明

参数	说明
function_name	待删除的自定义函数的名称。

语法示例

以下示例删除 calculate_growth_rate 自定义函数。

DROP FUNCTION calculate_growth_rate;