UDF 函数

系统提供了扩展 HQL 的功能，用户可自定义 UDF 函数。UDF 函数与原生 HQL 函数在系统内的使用是完全相同的，可用于添加新列、指标、权限过滤等。用户可以添加数据库上的自定义函数到衡石系统中，把数据库管理员的成果普及给报表创作者。用户也可以把权限控制相关查询提取成一些函数，方便报表创作者设置权限。

自定义 UDF 函数制作过程：

1. 准备 UDF 函数文件。
2. 将 UDF 函数文件放置到服务器，并指定服务器路径。
3. 重启服务，使用 UDF 函数。

下面通过示例详细地介绍 UDF 函数制作过程。

准备 UDF 函数

准备自定义 UDF 函数，存放到后缀 json 的文件中。 如下是 regex_replace、localtime 和 dataorgperm 自定义函数示例。

[
    {
        "type": "string", // 函数的返回类型
        "args": [
            {
                "type": "string", // 参数类型
                "placeholder": "s", // 参数占位符
                "desc": "文本类型参数" // 参数描述
            },
            {
                "type": "string",
                "placeholder": "regex",
                "desc": "文本类型参数"
            },
            {
                "type": "string",
                "placeholder": "replace",
                "desc": "文本类型参数"
            }
        ],
        "desc": "正则替换", // 函数描述
        "name": "regex_replace", // 函数名称
        "categories": [ // 函数所属分类
            "string functions",
            "non aggregate functions",
            "new field functions"
        ],
        "presets": {
            "mysql": "regex_replace({0}, {1}, {2})",
            "postgresql": "regex_replace({0}, {1}, {2})"
        }, // 函数的实际实现,每个 dialect 一条记录，mysql 为 dialect 名称
        "varArgs": false, // 函数的变量是否可变的
        "isAggregate":false, // 函数是否为聚合函数
        "isWindow":false // 函数是否为窗口函数
    },
    {
        "type": "date",
        "args": [
        ],
        "desc": "当前时间",
        "name": "localtime",
        "categories": [    //函数分类
            "time functions",
            "non aggregate functions",
            "new field functions"
        ],
        "presets": {
            "mysql": "localtime",
            "postgresql": "localtime"
        },
        "varArgs": true
    }
    {
        "name": "dataorgperm",
        "type": "bool",
        "presets": {
            "postgresql": "exists (select 0 from \"A_IVT_MOVIE\" z where prime_genre like ''%{1}%'' and id = '{{%%_table}}'.{0})"
        },
        "args": [
            {
                "type": "string",
                "placeholder": "literal_unquoted",
                "desc": "权限机构字段"
            },
            {
                "type": "string",
                "placeholder": "literal_unquoted",
                "desc": "用户所属机构"
            }
        ],
        "desc": "数据机构权限",
        "categories": [
            "other functions"
        ],
        "varArgs": false,
        "isAggregate": false,
        "isWindow": false
    }

]

函数的返回值、参数支持以下类型：

• string ：文本类型。
• integer：整数类型。
• number ：数字类型。
• time ：时间类型。
• date ：日期类型。
• bool ：布尔类型。
• any ：任意类型。

函数所属分类支持以下类型：

• string functions ： 字符串函数。
• math functions ： 数学函数。
• time functions ： 日期函数。
• non aggregate functions： 非聚合函数。
• aggregate functions ： 聚合函数。
• window functions ： 窗口函数。
• common functions ： 常用函数。
• new field functions ： 函数会被列在新建字段、指标、权限等界面的函数列表中。

参数占位符：占位符的值可以设定任意值。下面两个占位符值在衡石系统内有具体定义。

• literal ：表示这个参数必须是常量字符串。
• literal_unquoted ：表示该参数是常量字符串，在拼接 SQL 的时候不需要为字符串添加引号。

参数使用：UDF 函数中支持使用格式'{{%%参数名}}'传递参数，单引号是转义符号，避免系统把它当成函数的参数占位符。其中_table 是一个特殊参数，用于表示它所作用的数据集的别名，这个参数一般是用在数据连接或者数据集的权限设定中。

配置 UDF 函数路径

将 UDF 函数文件准备好后，放置到服务器上，并在配置文件中通过配置项 UDF_FILE_PATH 指定服务器路径。

UDF_FILE_PATH=~/Desktop/udf/udf-test.json

使用 UDF 函数

配置 UDF 函数路径后，重启衡石服务，可以在表达式中查看和使用定义的 UDF 函数。

说明

如果 UDF 函数与系统 HQL 函数同名时，优先使用 UDF 函数，函数列表中展示的是 UDF 函数。