Skip to content

UDF 函数

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

自定义 UDF 函数制作过程:

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

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

准备 UDF 函数

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

js
[
    {
        "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 函数。

衡石分析平台使用手册