Flink 系统内置函数（Built-in Functions）分类、典型用法与选型建议

1. 系统内置函数是什么

1.1 系统（Built-in）函数 是 Flink 默认提供、无需注册即可使用的一组函数，用于数据转换与分析。

1.2 当内置函数不够用时，你可以实现 用户自定义函数（UDF）。如果你认为某个函数足够通用，可以提 Jira 提案。

2. 函数大类总览（按能力域划分）

2.1 标量函数（Scalar Functions）：输入 0/1/N 个值，输出 1 个值

2.2 聚合函数（Aggregate Functions）：跨多行聚合，输出 1 个聚合结果

2.3 列函数（Column Functions，仅 Table API）：用于"选择/排除列"

2.4 其它：命名参数（Named Arguments）、时间单位说明（Time Interval/Point Units）

3. 标量函数（Scalar Functions）

3.1 比较函数（Comparison）

这一类用于比较、判空、范围判断、LIKE/正则匹配、IN/EXISTS 等。

3.1.1 基本比较（注意 NULL）

• =, <>, >, >=, <, <=：当任意一侧为 NULL，结果通常为 UNKNOWN
• IS NULL / IS NOT NULL：专门用于判空

3.1.2 NULL 友好的等价判断

• IS DISTINCT FROM：把 NULL 当作"可比较值"，NULL 与 NULL 视为相同

  • NULL IS DISTINCT FROM NULL 为 FALSE
  • 1 IS DISTINCT FROM NULL 为 TRUE

• IS NOT DISTINCT FROM：同理用于"相等"判断

  • NULL IS NOT DISTINCT FROM NULL 为 TRUE

3.1.3 范围判断

• BETWEEN ... AND ...：支持 ASYMMETRIC（默认）与 SYMMETRIC（对称）
• NOT BETWEEN ... AND ...：与 BETWEEN 相反

3.1.4 模式匹配

• LIKE / NOT LIKE：支持 ESCAPE
• SIMILAR TO / NOT SIMILAR TO：SQL 正则语义（注意部分 ESCAPE 能力尚未支持）

3.1.5 集合与子查询

• IN (...) / NOT IN (...)：列表中包含 NULL 时会出现 UNKNOWN 语义
• EXISTS (sub-query)：可被重写为 join + group 才支持；流式场景可能导致状态无限增长，需要配状态 TTL/保留策略
• value IN (sub-query) / value NOT IN (sub-query)：子查询返回集合参与判断

3.2 逻辑函数（Logical）

这一类的核心是 三值逻辑（TRUE/FALSE/UNKNOWN）。

• OR：任一 TRUE 即 TRUE（例如 TRUE OR NULL 为 TRUE）
• AND：任一 FALSE 即 FALSE，但 TRUE AND NULL 为 UNKNOWN
• NOT：对 UNKNOWN 仍为 UNKNOWN
• IS TRUE / IS FALSE / IS UNKNOWN 及其 NOT 版本：用于精确判断三值逻辑状态

3.3 算术函数（Arithmetic）

常见数值运算与数学函数：

3.3.1 基本运算

• + - * / %（MOD(a,b)）

3.3.2 常见数学函数

• 幂与根：POWER、SQRT
• 对数：LN、LOG10、LOG2、LOG(base, x)（对输入范围有约束）
• 指数：EXP
• 取整：CEIL/CEILING、FLOOR、ROUND(x, n)、TRUNCATE(x, n)
• 三角函数：SIN/COS/TAN/COT 及反函数 ASIN/ACOS/ATAN/ATAN2
• 角度弧度：DEGREES、RADIANS
• 常量与随机：PI()、E()、RAND()、RAND(seed)、RAND_INTEGER(...)
• UUID：UUID()

3.3.3 编码相关

• BIN(int)：转二进制字符串
• HEX(x) / UNHEX(expr)：十六进制与二进制互转

3.3.4 百分位（PERCENTILE）

• PERCENTILE(expr, percentage[, frequency])：连续分布百分位，必要时线性插值
• 建议更适合 window 场景；普通 group aggregation 可能引发排序开销

3.4 字符串函数（String）

3.4.1 拼接与长度

• ||、CONCAT(...)、CONCAT_WS(sep, ...)
• CHAR_LENGTH / CHARACTER_LENGTH

3.4.2 大小写与位置

• UPPER、LOWER、POSITION(x IN y)、INSTR、LOCATE

3.4.3 Trim / Pad / Repeat

• TRIM、LTRIM、RTRIM、BTRIM
• LPAD、RPAD
• REPEAT

3.4.4 子串与替换

• SUBSTRING / SUBSTR
• REPLACE
• OVERLAY

3.4.5 正则族（非常常用）

• REGEXP_REPLACE
• REGEXP_COUNT / EXTRACT / EXTRACT_ALL / INSTR / SUBSTR
• REGEXP(str, regex)：判断是否匹配

3.4.6 URL / Base64 / 编解码

• URL_ENCODE/URL_DECODE
• FROM_BASE64/TO_BASE64
• ENCODE/DECODE（指定字符集）
• PARSE_URL（支持提取 HOST/PATH/QUERY 等）

3.4.7 其它实用函数

• STARTSWITH、ENDSWITH
• REVERSE
• SPLIT_INDEX、STR_TO_MAP
• JSON 字符串转义：JSON_QUOTE/JSON_UNQUOTE
• ELT(index, ...)：按序取第 N 个表达式

3.5 时间与区间函数（Temporal）

3.5.1 字符串转时间

• DATE str、TIME str、TIMESTAMP str
• TO_DATE(str[, fmt])
TO_TIMESTAMP(str[, fmt])
• TO_TIMESTAMP_LTZ(epochOrStr[, ...])

3.5.2 当前时间（批/流语义不同）

• LOCALTIME、LOCALTIMESTAMP、CURRENT_DATE、CURRENT_TIMESTAMP、NOW()

• 重要语义：

  • 流式：通常"每条记录计算一次"
  • 批式：通常"查询启动时计算一次"

3.5.3 抽取与日期字段

• EXTRACT(unit FROM temporal)
• YEAR/QUARTER/MONTH/WEEK/DAYOFYEAR/DAYOFMONTH/DAYOFWEEK/HOUR/MINUTE/SECOND

3.5.4 对齐时间单位

• FLOOR(timepoint TO unit)
• CEIL(timepoint TO unit)

3.5.5 时间间隔判断与转换

• OVERLAPS

• DATE_FORMAT(timestamp, pattern)（pattern 兼容 Java SimpleDateFormat）

• TIMESTAMPDIFF(unit, t1, t2)

• CONVERT_TZ(datetime, fromTz, toTz)

• Unix 时间戳：

  • UNIX_TIMESTAMP()
  • UNIX_TIMESTAMP(str[, fmt])（注意时区解析规则）
  • FROM_UNIXTIME(sec[, fmt])

3.5.6 水位线

• CURRENT_WATERMARK(rowtime)：返回当前 watermark（可能为 NULL）

3.6 条件函数（Conditional）

• CASE WHEN ... THEN ... ELSE ... END
• NULLIF(a,b)
• COALESCE(a,b,...)
• IF(cond, x, y)
• IFNULL(x, replacement)：在 nullability 推导上更"具体"
• GREATEST(...) / LEAST(...)：任意参数为 NULL 则返回 NULL（这是常见坑）
• 字符串判定：IS_ALPHA、IS_DIGIT、IS_DECIMAL

3.7 类型转换函数（Type Conversion）

• CAST(x AS type)：失败会抛异常并失败作业
• TRY_CAST(x AS type)：失败返回 NULL，更适合脏数据场景
• TYPEOF(expr[, force_serializable])：返回类型字符串（可用于调试、动态 schema 观察）

3.8 集合函数（Collection）

数组（ARRAY）常用：

• CARDINALITY(array)、array[INT] / ARRAY.at(INT)、ELEMENT(array)
• ARRAY_APPEND/PREPEND、ARRAY_CONTAINS
• ARRAY_DISTINCT、ARRAY_POSITION
• ARRAY_REMOVE、ARRAY_REVERSE
• ARRAY_SLICE（支持正负索引、0 视为开头）
• ARRAY_SORT（可控升降序与 NULL 位置）
• ARRAY_UNION/EXCEPT/INTERSECT/CONCAT
• ARRAY_MAX/ARRAY_MIN
• ARRAY_JOIN

Map（MAP）常用：

• CARDINALITY(map)、map[key] / MAP.at(key)
• MAP_KEYS、MAP_VALUES、MAP_ENTRIES
• MAP_FROM_ARRAYS
• MAP_UNION

字符串分割：

• SPLIT(str, delimiter)：返回 ARRAY

3.9 JSON 函数（JSON）

JSON 函数基于 SQL 标准 JSON Path，支持 strict/lax（默认 strict），并有已知限制（lax 并非所有特性都稳定）。

常用函数：

• IS JSON [VALUE|SCALAR|ARRAY|OBJECT]

• JSON_EXISTS(json, path [ ... ON ERROR ])

• JSON_STRING(value)：序列化成 JSON 字符串

• JSON_VALUE(json, path ... )：取标量，可指定 RETURNING 与 ON EMPTY/ON ERROR 的兜底

• JSON_QUERY(json, path ... )：取 JSON 片段，可控制 wrapper 与 onEmpty/onError

• 构造函数：

  • JSON_OBJECT(...)
  • JSON_ARRAY(...)
  • JSON(value)：仅可在 JSON_OBJECT/JSON_ARRAY 内用于插入"原样 JSON"

• 聚合构造：

  • JSON_OBJECTAGG(KEY k VALUE v ...)
  • JSON_ARRAYAGG(expr ...)

Variant（变体类型）：

• PARSE_JSON / TRY_PARSE_JSON：将 JSON 字符串解析为 Variant

3.10 值构造与访问（Row/Array/Map/Descriptor/Object）

• 行：(v1, v2, ...) 或 ROW(v1, ...)
• 数组：ARRAY[ ... ]
• Map：MAP[ k1, v1, k2, v2, ... ]
• DESCRIPTOR(col1, col2, ...)：用于传列名列表（尤其 PTF）
• OBJECT_OF(className, key, value, ...)：构造结构化对象（需 classpath 可解析）

值访问：

• composite.field 或 COMPOSITE.get(name/index)
• flatten()：把复合类型拉平为多列

3.11 Hash、Grouping 等

• Hash：MD5、SHA1、SHA224/256/384/512、SHA2(str, bitLen)
• 分组标识：GROUP_ID()、GROUPING(...)、GROUPING_ID(...)

4. 聚合函数（Aggregate Functions）

这一类跨多行计算：

• 计数：COUNT(*)、COUNT(expr)、COUNT(DISTINCT ...)

• 数值聚合：AVG、SUM、MAX、MIN

• 方差标准差：VAR_POP/VAR_SAMP/VARIANCE、STDDEV_POP/STDDEV_SAMP

• 收集：COLLECT、ARRAY_AGG

• 窗口分析函数（常与 OVER 搭配）：

  • RANK、DENSE_RANK、ROW_NUMBER
  • LAG/LEAD
  • FIRST_VALUE/LAST_VALUE
  • CUME_DIST、PERCENT_RANK、NTILE

• 字符串聚合：LISTAGG

5. 时间区间与时间点单位（Units）

5.1 Table API 使用下划线替代空格（例如 DAY_TO_HOUR）

5.2 SQL 里可用复数（YEARS）

5.3 既有 interval unit，也有 time point unit（如 YEAR/MONTH/DAY/HOUR...）

6. 列函数（Column Functions，仅 Table API）

这部分只在 Table API 中用，SQL 里没有。

6.1 三个入口函数

• withColumns(...)：选择指定列
• withoutColumns(...)：排除指定列
• withAllColumns()：选择所有列（类似 SQL SELECT *）

6.2 列表达方式

• 按列名："a"
• 按列索引（从 1 开始）
• 按范围：range(2, 4) 或 range("a", "b")

6.3 一个典型组合例子（概念展示）

• groupBy(withColumns(range(1, 3)))
• select(withColumns(range("a","b")), myUDAgg(myUDF(withColumns(range(5, 20)))))

7. 命名参数（Named Arguments）

7.1 默认是 位置参数 ：f(42, true)

7.2 若函数声明了静态签名（文档/DESCRIBE FUNCTION 中用 => 表示），可用 命名参数，例如：

SELECT MyUdf(input => my_column, threshold => 42);

7.3 命名参数的价值

• 调用更清晰、顺序可交换
• 可选参数不必强制填写
• 但并非所有函数都支持（重载/varargs 等通常不支持）

8. 实战选型建议（快速决策）

8.1 脏数据转换：优先 TRY_CAST + COALESCE 做兜底，别让 CAST 直接把作业打挂

8.2 NULL 语义敏感的等值判断：优先 IS NOT DISTINCT FROM / IS DISTINCT FROM，避免 = 遇 NULL 变 UNKNOWN

8.3 JSON 解析：

• 抽标量用 JSON_VALUE，抽片段用 JSON_QUERY
• strict/lax 要明确，必要时配置 ON ERROR/ON EMPTY 的默认值
  8.4 流式 EXISTS/子查询：注意状态可能无限增长，需要配置合理的 state retention