# UDF 手册

`dw_base/udf/` 下 UDF 的自查表：每次增删 / 重命名 / 改签名时同步更新本表。函数编号与 `dw_base/udf/common/spark_common_udf.py` 中的 `UDF-XX` 注释保持一致。

## 1. 通用 UDF 自查表

| 函数编号 | 函数名 | 分类 | 入参 | 返回 | 描述 | 示例 |
|----------|--------|------|------|------|------|------|
| UDF-01 | `is_json` | JSON | `data` | `boolean` | 判断输入是否为合法 JSON 字符串 | `SELECT is_json('{"a":1}')` → `true` |
| UDF-02 | `json_object_keys` | JSON | `json_str: string` | `array<string>` | 提取 JSON object 的 key 列表 | `SELECT json_object_keys('{"a":1,"b":2}')` → `['a','b']` |
| UDF-21 | `array_intersect` | ARRAY | `arr1: array, arr2: array` | `array<string>` | 计算两个数组的交集 | `SELECT array_intersect(array('a','b'), array('b','c'))` → `['b']` |
| UDF-22 | `array_slice` | ARRAY | `input_array: array, start: int, end: int` | `array<string>` | 按起止下标截取数组（Python 切片语义） | `SELECT array_slice(array('a','b','c','d'), 1, 3)` → `['b','c']` |
| UDF-23 | `merge_list` | ARRAY | `arr_list: array<array>` | `array<string>` | 合并二维数组，过滤 None 与空字符串 | `SELECT merge_list(array(array('a',''), array('b',null)))` → `['a','b']` |
| UDF-31 | `has_chinese` | STRING | `datum: string` | `boolean` | 判断字符串中是否包含中文字符 | `SELECT has_chinese('hello 你好')` → `true` |
| UDF-32 | `similarity` | STRING | `left: string, right: string` | `float` | 计算两个字符串的快速相似度（difflib `quick_ratio`） | `SELECT similarity('apple','apples')` → `0.909` |
| UDF-33 | `regexp_extract_all` | STRING | `col: string, ptn: string, g: int = 0` | `array<string>` | 提取正则表达式全部匹配结果，`g` 指定捕获组 | `SELECT regexp_extract_all('a1b2c3','\\d',0)` → `['1','2','3']` |
| UDF-41 | `parse_datetime_to_timestamp` | NUMERIC / DATE / HASH | `date_time: string, in_milli_seconds: boolean = false, original_format: string = null` | `bigint` | 字符串日期转时间戳；支持 `YY.MM.DD` / `YYYY年M月D日` 启发式识别 | `SELECT parse_datetime_to_timestamp('2026-04-21')` |
| UDF-42 | `get_md5` | NUMERIC / DATE / HASH | `*cols: string` | `string` | 多列按"长度前缀 + 值"拼接后取 MD5（防碰撞） | `SELECT get_md5('a','bc')` |
| UDF-51 | `str_to_arr` | CROSS-TYPE | `json_str: string` | `array<string>` | JSON array 字符串转 list | `SELECT str_to_arr('["a","b"]')` → `['a','b']` |
| UDF-52 | `str_to_json_arr` | CROSS-TYPE | `json_str: string` | `array<string>` | JSON array 字符串转"JSON 字符串数组"（每个元素再 `json.dumps`） | `SELECT str_to_json_arr('[{"a":1},{"b":2}]')` |
| UDF-53 | `str_to_map_arr` | CROSS-TYPE | `json_str: string` | `array<map<string,string>>` | JSON array 字符串转 map 数组 | `SELECT str_to_map_arr('[{"a":1},{"b":2}]')` |

> 本表行数应等于 `spark_common_udf.py` 中 `@udf` 注册函数数（启动日志里 `注册 Python UDF` 的条数即真值）。非 `@udf` 装饰的普通 `def` 是 Python 侧辅助函数，不进 SparkSQL 注册表，不登记。

## 2. 业务 UDF 自查表

`dw_base/udf/business/` 下 UDF，当前暂无。新增业务 UDF 后在此登记。

| 函数编号 | 函数名 | 分类 | 入参 | 返回 | 描述 | 示例 |
|----------|--------|------|------|------|------|------|
| —        | —      | —    | —    | —    | —    | —    |