Spark SQL 迁移到 Hologres 的函数改写清单

从 Spark SQL 迁移到 Hologres 时，在 Spark SQL 有对应写法的 44 个常用函数中，27 个需要改写（其中 2 个在 Hologres 没有对应函数）。逐个列出两边写法和注意事项。

需要改写的函数 · 迁移注意事项 · 可以直接用的函数 · 反向：Hologres 迁移到 Spark SQL

需要改写的函数

函数	Spark SQL 写法	Hologres 写法	Hologres 说明
ADD_MONTHS	`add_months(start_date, num_months)`	需改写 `d + interval '1 month'`	ADD_MONTHS 是 Oracle 兼容函数，需要先加载 orafce 扩展。原生写法用 interval 加减。
ANY_VALUE	`any_value(expr[, isIgnoreNull])`	需改写 `MAX(col)`	通用聚合函数中没有 ANY_VALUE。组内值都相同时，可以用 MAX 或 MIN 代替。
COLLECT_LIST	`collect_list(expr)`	需改写 `ARRAY_AGG(expression)`	没有 COLLECT_LIST，用 ARRAY_AGG。
COLLECT_SET	`collect_set(expr)`	需改写 `ARRAY_AGG(DISTINCT expression)`	没有 COLLECT_SET，用 ARRAY_AGG。不支持 JSON、JSONB、INTERVAL 和数组等类型。
DATE_ADD	`date_add(start_date, num_days)`	需改写 `DATEADD(d, num, 'day')`	文档中没有 DATE_ADD，可以用 DATEADD 或 d + interval。DATEADD 需要 V2.0.31～V2.1.0 或 V2.1.13 及以上版本。
DATE_FORMAT	`date_format(timestamp, fmt)`	需改写 `TO_CHAR(timestamp, 'YYYY-MM-DD HH24:MI:SS')`	文档中没有 DATE_FORMAT，用 TO_CHAR 代替。格式符是 PostgreSQL 风格，HH 默认是 12 小时制，24 小时制要写 HH24。
DATE_SUB	`date_sub(start_date, num_days)`	需改写 `d - interval '1 day'`	文档中没有 DATE_SUB。可以用日期减 interval，也可以写 DATEADD(d, -n, 'dd')。DATEADD 需要 V2.0.31～V2.1.0 或 V2.1.13 及以上版本。
DATEADD	`ts + INTERVAL n HOUR`	支持 `DATEADD(d, num, str)`	需要 V2.0.31～V2.1.0 或 V2.1.13 及以上版本。单位写法与 MaxCompute 一致，包括 yyyy、mm、dd、hh、mi、ss。默认只支持 1925～2282 年，并且暂不支持常量入参写入。
DAYOFWEEK	`dayofweek(date)`	需改写 `EXTRACT(DOW FROM ts) + 1`	DOW 以周日为 0，所以要加 1 才和其他引擎一致。ISODOW 以周一为 1、周日为 7。
DECODE	`decode(expr, search, result [, search, result ] ... [, default])`	需改写 `CASE expr WHEN search THEN result ... ELSE default END`	条件函数文档中没有 DECODE，用 CASE 改写。
EXPLODE	`explode(expr)`	需改写 `UNNEST(anyarray)`	把数组的每个元素展开成一行。
FROM_JSON	`from_json(jsonStr, schema[, options])`	需改写 `json_str::jsonb ->> 'key'`	没有 FROM_JSON。先转成 JSON 或 JSONB，再用 -> 或 ->> 取字段，->> 返回 TEXT。需要展开成多列时可以用 json_populate_record。
FROM_UNIXTIME	`from_unixtime(unix_time[, fmt])`	需改写 `TO_TIMESTAMP(seconds)`	文档中没有 FROM_UNIXTIME。TO_TIMESTAMP(double precision) 按秒转换，返回 TIMESTAMPTZ。需要字符串时再用 TO_CHAR。
GETDATE	`current_timestamp() 或 now()`	别名 `NOW() 或 CURRENT_TIMESTAMP`	返回当前事务的开始时刻，NOW、CURRENT_TIMESTAMP 和 TRANSACTION_TIMESTAMP 等效。需要每次调用都取实时时刻时用 CLOCK_TIMESTAMP。
INSTR	`instr(str, substr)`	需改写 `STRPOS(str, substr)`	INSTR 是 Oracle 兼容函数，需要先安装 orafce 扩展才能用，支持起始位置和第 N 次出现。不装扩展时用 STRPOS。
MONTHS_BETWEEN	`months_between(timestamp1, timestamp2[, roundOff])`	需改写 `(EXTRACT(YEAR FROM a) - EXTRACT(YEAR FROM b)) * 12 + EXTRACT(MONTH FROM a) - EXTRACT(MONTH FROM b)`	日期函数中没有 MONTHS_BETWEEN，可以用 EXTRACT 取年和月计算整数月差，不含小数部分。
NVL	`nvl(expr1, expr2)`	需改写 `COALESCE(value, default_value)`	条件函数文档中没有 NVL，只有 COALESCE、IF、NULLIF 等，需要改写为 COALESCE。
PERCENTILE_APPROX	`percentile_approx(col, percentage[, accuracy])`	需改写 `APPROX_PERCENTILE(p) WITHIN GROUP (ORDER BY col)`	Hologres V3.1 起提供，用蓄水池抽样计算，最多保留 8,192 个元素。p 是 0～1 之间的常量。
REGEXP_EXTRACT	`regexp_extract(str, regexp[, idx])`	需改写 `(REGEXP_MATCH(str, pattern))[n]`	字符串函数中没有 REGEXP_EXTRACT。REGEXP_MATCH 返回由各分组组成的数组，再用数组下标取第 n 组，下标从 1 开始。
SIZE	`size(expr)`	需改写 `ARRAY_LENGTH(arr, 1)`	第二个参数是维度，从 1 开始，一维数组传 1。数组函数文档只覆盖 ARRAY。
SORT_ARRAY	`sort_array(array[, ascendingOrder])`	需改写 `ARRAY_SORT(anyarray)`	只有升序。V1.1.46 起支持 TEXT 数组，但会先转成 INT8 再排序；V1.3.18 起 TEXT 数组按字典序排序，并支持 INT4、INT8、FLOAT4、FLOAT8 和 BOOLEAN 数组。
SPLIT	`split(str, regex[, limit])`	需改写 `REGEXP_SPLIT_TO_ARRAY(str, pattern)`	字符串函数中没有 SPLIT。拆成数组用 REGEXP_SPLIT_TO_ARRAY，只取第 n 段用 SPLIT_PART(str, delimiter, n)。
STR_TO_MAP	`str_to_map(text[, pairDelim[, keyValueDelim]])`	不支持	字符串函数中没有 STR_TO_MAP。
SUBSTR	`substr(str, pos[, len])`	需改写 `SUBSTRING(str FROM start FOR len)`	SUBSTR 是 Oracle 兼容函数，需要先加载 orafce 扩展。PostgreSQL 标准写法是 SUBSTRING。
SUBSTRING_INDEX	`substring_index(str, delim, count)`	不支持	字符串函数中没有 SUBSTRING_INDEX。只取某一段时可以用 SPLIT_PART。
UNIX_TIMESTAMP	`unix_timestamp([timeExp[, fmt]])`	需改写 `EXTRACT(EPOCH FROM ts)`	日期函数中没有 UNIX_TIMESTAMP。EXTRACT 的 epoch 字段返回秒数，类型是 DOUBLE PRECISION。
WEEKOFYEAR	`weekofyear(date)`	需改写 `EXTRACT(WEEK FROM ts)`	也可以用 week_iso(ts)，文档说明语义与 EXTRACT(WEEK FROM ts) 相同、性能更好。返回 DOUBLE PRECISION。

迁移注意事项

以下内容摘自各函数页中提到 Spark SQL 或 Hologres 的注意事项。

ADD_MONTHS 按月加减

月末日期：StarRocks、Doris 和 Spark 在目标月份没有对应日期时取当月最后一天。StarRocks 文档特别说明，2022-02-28 加 1 个月得到 3 月 28 日而不是 3 月 31 日，这和 Oracle 的行为不同。
Hologres 和 Flink 的月末行为文档没有写明，迁移涉及月末日期时建议用已知数据核对。

ANY_VALUE 取组内任意值

NULL 的处理不同：MaxCompute 和 Doris 会优先返回非 NULL 值，Spark 默认可能返回 NULL，需要传 true 才会跳过 NULL。

DATE_FORMAT 日期格式化

从 MaxCompute 默认模式迁出时，hh:mi:ss 要改成目标引擎的分钟写法。原样照搬到 Spark 或 Flink，mi 不会被识别为分钟。
Hologres 的 HH 默认是 12 小时制，下午的时间会少 12 小时，必须写 HH24。

DATEADD 按单位加减日期

MaxCompute 和 Hologres 中 mm 表示月，mi 表示分钟。把 DATEADD(d, 1, 'mm') 当成加 1 分钟，是迁移时最常见的错误。
Spark 3.4.0 起的 dateadd(d, 1) 表示加 1 天，参数个数和含义都与 MaxCompute 不同，不能直接照搬。
Hologres 的 DATEADD 默认只支持 1925～2282 年。9999-12-31 这类表示“永久有效”的日期需要单独处理。

DAYOFWEEK 星期几

Hologres 的 EXTRACT(DOW ...) 以周日为 0，直接替换 DAYOFWEEK 会让每天都差 1，周日从 1 变成 0。
“星期几”的编号有三种：DAYOFWEEK 周日为 1；MaxCompute 和 Spark 的 WEEKDAY 周一为 0；Hologres 的 ISODOW 周一为 1、周日为 7。迁移时先确认原 SQL 用的是哪一种。
需要“周一为 1、周日为 7”时，可以写成 (DAYOFWEEK(d) + 5) % 7 + 1，在 Hologres 中直接用 EXTRACT(ISODOW FROM d)。

DECODE 多值匹配

Spark 3.2 之前只有字符集解码的 decode，多值匹配写法在旧版本中会报错。

EXPLODE 数组展开为多行

空数组和 NULL 数组的行会被直接丢掉：MaxCompute、Doris 的 EXPLODE 和 StarRocks 的 UNNEST 都是这样。需要保留时，Doris 和 Spark 用 EXPLODE_OUTER，StarRocks 3.2.7 起用 LEFT JOIN UNNEST(...) ON TRUE。
需要元素位置时，Hive 和 Spark 的 posexplode 位置从 0 开始，Flink 的 WITH ORDINALITY 从 1 开始，迁移时要调整下标。

FROM_UNIXTIME 时间戳转日期

返回类型不同：MaxCompute 返回 DATETIME，Hologres 的 TO_TIMESTAMP 返回 TIMESTAMPTZ，其他引擎返回字符串。拿结果做日期计算前，确认是否需要再转换类型。
结果受会话时区影响。Spark 文档的示例中，from_unixtime(0) 返回 1969-12-31 16:00:00，因为示例环境的时区是 UTC-8。

GETDATE 获取当前时间

返回类型不同：MaxCompute、StarRocks 和 Doris 返回 DATETIME，Hologres 的 NOW 带时区（文档把不带时区的版本单独列为 LOCALTIMESTAMP），Flink 返回 TIMESTAMP_LTZ(3)。直接写入字符串或 DATETIME 字段时，格式可能变化。
Hive 和 Spark 的 current_timestamp 可以不带括号，Doris 文档中的写法是 current_timestamp()。迁移时统一写 NOW() 更容易对齐。

INSTR 查找子串位置

MaxCompute 的三参数和四参数写法，例如 INSTR(s, 'e', 3, 2)，在 StarRocks、Doris、Hive、Spark 和 Flink 中都没有对应写法。只传起始位置时可以改成 LOCATE，取第 N 次出现时需要改写成多步计算。
Hologres 的 INSTR 依赖 orafce 扩展。没有安装扩展时 SQL 会报函数不存在，改用 STRPOS 即可。

MONTHS_BETWEEN 相差月数

StarRocks 的 months_diff、Flink 的 TIMESTAMPDIFF 和 Hologres 的 EXTRACT 写法都只返回整数月，原 SQL 中依赖小数部分的计算（例如按 0.5 个月判断）需要重新设计。
时间部分的处理不同：Doris 只看日期，Hive 会把时间部分算进小数，Spark 在同一天或都是月末时忽略时间。同样的输入可能得到不同的小数。
舍入不同：Hive 和 Spark 默认保留 8 位小数，MaxCompute 返回完整的 DOUBLE，Doris 由 round_type 控制。和原结果做等值比较前，先统一 ROUND。

NVL 空值替换

迁移到 Hologres、StarRocks 或 Flink SQL 时，统一改写为 COALESCE 最省事，因为 COALESCE 在七个引擎中都可用。

PERCENTILE_APPROX 近似分位数

第三个参数含义不同：MaxCompute 和 Hive 的 B、Spark 的 accuracy 都默认 10000；StarRocks 和 Doris 的 compression 只接受 2048～10000。从 Spark 迁移时，如果写了大于 10000 的 accuracy，要调整到这个范围内。
各引擎的算法不同，结果不会完全一致。MaxCompute 文档写明 p 落在两个值中间时取两者均值，Spark 返回满足条件的最小值，Flink 的 PERCENTILE 用线性插值。P50、P99 这类指标迁移后要实测对比。
Hologres 的 APPROX_PERCENTILE 需要 V3.1 及以上版本，而且只抽样 8,192 个元素。数据量很大时，尾部分位数（例如 P999）的误差可能偏大。

REGEXP_EXTRACT 正则提取

第三个参数是否必填不一样：MaxCompute、Spark 和 Flink 可以省略，默认取第 1 组；StarRocks、Doris 和 Hive 必须写上。迁移时统一写出分组下标最稳妥。
反斜杠转义各引擎不同。MaxCompute 文档要求在客户端写两个反斜杠，Spark 文档建议用 r'' 原始字符串。示例里用 [0-9] 代替 \d，可以避开转义差异。
Doris 默认用 RE2 语法，不支持 (?=...) 这类零宽断言。从 Hive 或 Spark 的 Java 正则迁移过来时，需要先确认是否用到这些写法。

SIZE 数组和 Map 元素个数

Spark 对 NULL 输入可能返回 -1，也可能返回 NULL，取决于 ANSI 模式和 spark.sql.legacy.sizeOfNull 两个配置。Spark 3.x 默认关闭 ANSI 模式，所用版本的默认值要按对应版本文档确认。下游有 size(x) = -1 这类判断时，迁移前要先核对配置。
Hologres 文档中 ARRAY_LENGTH 的签名带维度参数，一维数组也要写成 ARRAY_LENGTH(arr, 1)。

SORT_ARRAY 数组排序

Spark 有两个排序函数：sort_array 升序时把 NULL 放在开头，array_sort 把 NULL 放在末尾。从 MaxCompute 或 Hive 迁移时应使用 sort_array，结果才一致。
降序的写法不同：MaxCompute 和 Spark 传第二个参数，Flink 传 ascending_order，Doris 用 ARRAY_REVERSE_SORT，Hive 和 Hologres 的函数只能升序。
Hologres V1.3.18 之前会把 TEXT 数组转成 INT8 再排序，字符串内容不是数字时结果可能不符合预期，使用前先确认实例版本。

SPLIT 字符串拆分

MaxCompute、Hive 和 Spark 按正则处理分隔符。用 . 或 | 拆分时要写成 '\\.' 或 '\\|'，否则会被当成正则元字符，结果出错。
只需要取某一段时，Hologres 的 SPLIT_PART 和 Flink 的 SPLIT_INDEX 更直接。注意 SPLIT_PART 的序号从 1 开始，SPLIT_INDEX 为负数时返回 NULL。

STR_TO_MAP 字符串转 Map

默认的键值分隔符不同：MaxCompute 和 Flink 是等号，StarRocks、Doris、Hive 和 Spark 是冒号。省略分隔符的写法迁移后会解析出错误结果，而且不会报错。
Spark、Flink 把分隔符当作正则表达式，MaxCompute 也要求对句点、问号等特殊字符转义。分隔符是 | 或 . 时，迁移前后都要检查转义写法。
Hologres 没有 STR_TO_MAP。可以先用 REGEXP_SPLIT_TO_ARRAY 拆分，再按需取值，或者在入库前把数据转成 JSON。

SUBSTR 截取子串

Hologres 直接写 SUBSTR 可能报函数不存在，需要先创建 orafce 扩展，或改用标准的 SUBSTRING。

SUBSTRING_INDEX 按分隔符截取

Hologres 和 Flink 没有这个函数。只取某一段可以改用 Hologres 的 SPLIT_PART 或 Flink 的 SPLIT_INDEX；要取“前两段”这种跨分隔符的结果，需要拼接或用正则改写。
从 URL 中取域名这类场景常写成 substring_index(substring_index(url, '/', 3), '/', -1)，嵌套写法在 Hologres 和 Flink 中要整体改写。

UNIX_TIMESTAMP 日期转时间戳

格式参数的写法不同：StarRocks 和 Doris 用 %Y-%m-%d %H:%i:%s，Hive、Spark 和 Flink 用 yyyy-MM-dd HH:mm:ss，MaxCompute 不支持格式参数。

WEEKOFYEAR 一年中的第几周

Hologres 的 EXTRACT 返回 DOUBLE PRECISION，直接拼接字符串会得到 12.0 这类结果，需要先 CAST 成整数。

可以直接用的函数

下面 17 个函数在两个引擎中写法相同。参数、返回值和边界情况仍可能不同，点开函数页查看细节。