TO_TIME函数将时间数据转换为微秒单位的BIGINT值-云原生大数据计算服务 MaxCompute-阿里云

TO_TIME函数用于将不同类型和格式的时间数据，构造或转换为以微秒为单位，用BIGINT类型表示的时间值。

命令格式

TO_TIME函数支持以下四种签名格式，请根据不同使用需求选择不同的函数签名。

签名1：将时间格式的String类型输入value，按照指定的format格式解析，并返回以微秒为单位用BIGINT类型表示的时间值。
```
BIGINT TO_TIME(STRING <value>, STRING <format>)

-- 标准示例。
-- 返回48273000000。
SELECT TO_TIME('13:24:33', '%H:%M:%S');
```

签名2：使用代表时、分、秒的BIGINT数据，构造以微秒为单位用BIGINT类型表示的时间值。

BIGINT TO_TIME(BIGINT <hour>, BIGINT <minute>, BIGINT <second>)

-- 标准示例。
-- 返回55800000000。
SELECT TO_TIME(15, 30, 0);

签名3：将TIMESTAMP类型数据转换为指定时区的时间值，并返回以微秒为单位用BIGINT类型表示的时间值。

BIGINT TO_TIME(TIMESTAMP <timestamp>[, STRING <time_zone>])

-- 标准示例。
-- 返回55801123000。
SELECT TO_TIME(TIMESTAMP '2019-09-01 15:30:01.123');

签名4：将TIMESTAMP_NTZ类型数据转换为以微秒为单位用BIGINT类型表示的时间值。

BIGINT TO_TIME(TIMESTAMP_NTZ <timestamp_ntz>)

-- 标准示例。
-- 返回55801123456。
SELECT TO_TIME(TIMESTAMP_NTZ '2025-09-01 15:30:01.123456');

参数说明

参数	描述
value	必填，STRING类型。待转换的时间值，例如`15:20:23`。
format	必填，STRING类型。待解析value的时间格式。待解析的时间字符串value中，每个时间元素都必须有对应的格式元素。例如：15:20对应`hh:mi`、15:20:23对应`hh:mi:ss`。 format目前支持的时间部分的格式元素如下： `hh`、`HH`或`%H`：小时。 `mi`、`MI`或`%M`：分钟。 `ss`、`SS`或`%S`：秒。 `ff3`：毫秒，单独匹配秒的小数部分，例如用`%S.ff3`匹配`00.123`。 `%E<number>S`：秒，小数精度为`<number>`位，例如用`%E3S`匹配`00.123`。 `%ES`：有完整6位小数精度的秒，例如`00.123456`。示例：`hh:mi:ss`、`HH:MI:SS`、`%H:%M:%S`、`%H:%M:%E6S`、`%H:%M:%ES`。
hour	必填，BIGINT类型。待转换时间的小时。
minute	必填，BIGINT类型。待转换时间的分钟。
second	必填，BIGINT类型。待转换时间的秒。
timestamp	必填，TIMESTAMP类型。待转换的时间戳值。
time_zone	可选，STRING类型，用来指定时区，若未指定时区，则默认为当前Session/Project的时区。时区详情请参见时区列表。说明若未修改过项目时区，则默认为东八区（UTC+08:00）。
timestamp_ntz	必填，TIMESTAMP_NTZ类型。待转换的无时区时间戳值。

返回值说明

返回BIGINT类型。默认以微秒为单位表示时间值，返回规则如下：

当入参为TIMESTAMP或TIMESTAMP_NTZ类型时，去除其日期值和纳秒部分，返回结果的时间单位为微秒。
当参数value、timestamp或timestamp_ntz的值为NULL时，返回报错。
当参数hour、minute或second的值为NULL时，返回NULL。
当参数format格式不合法，或者值为NULL时，返回NULL。

使用示例

签名1：TO_TIME(STRING <value>, STRING <format>)。

将时间格式的String类型输入value，按照指定的format格式解析，并返回以微秒为单位用BIGINT类型表示的时间值。

示例1：合法format解析时间。

-- 使用标准格式 %H:%M:%S 解析完整时间。
-- 返回48273000000。
SELECT TO_TIME('13:24:33', '%H:%M:%S');

-- 使用 Oracle 风格格式 hh:mi:ss。
-- 返回46860000000。
SELECT TO_TIME('13:01:00', 'hh:mi:ss');

-- 仅包含小时和分钟。
-- 返回46860000000。
SELECT TO_TIME('13:01', 'hh:mi');

示例2：含毫秒和微秒的时间字符串解析。

-- 包含毫秒部分，使用ff3格式。
-- 返回781000000。
SELECT TO_TIME('13:01', 'mi:ss');

-- ff3表示三位小数秒。
-- 返回781123000。
SELECT TO_TIME('13:01.123', 'mi:ss.ff3');

-- 六位小数秒（微秒），使用%E6S。
-- 返回48273123456。
SELECT TO_TIME('13:24:33.123456', '%H:%M:%E6S');

-- 支持通配符%E*S自动识别精度。
-- 返回48273123456。
SELECT TO_TIME('13:24:33.123456', '%H:%M:%E*S');

示例3：非法或不匹配format处理。

-- format中%h是非法占位符（应为%H）。
-- 返回NULL。
SELECT TO_TIME('13:24:33', '%h:%m:%s');

示例4：NULL值输入处理。

-- format 为 NULL。
-- 返回NULL。
SELECT TO_TIME('13:24:33', NULL);

签名2：TO_TIME(BIGINT <hour>, BIGINT <minute>, BIGINT <second>)。

使用代表时、分、秒的BIGINT数据，构造以微秒为单位用BIGINT类型表示的时间值。

示例1：正常传参构造时间。

-- 使用标准格式 %H:%M:%S 解析完整时间。
-- 返回48273000000。
SELECT TO_TIME('13:24:33', '%H:%M:%S');

-- 使用 Oracle 风格格式 hh:mi:ss。
-- 返回46860000000。
SELECT TO_TIME('13:01:00', 'hh:mi:ss');

-- 仅包含小时和分钟。
-- 返回46860000000。
SELECT TO_TIME('13:01', 'hh:mi');

示例2：参数缺失导致失败。

-- 只传入两个参数，不符合函数签名。
-- 返回NULL。
SELECT TO_TIME(15, 30);

示例3：NULL值输入处理。

-- 任意参数为NULL，返回NULL。
-- 返回NULL。
SELECT TO_TIME(15, 30, NULL);

-- 返回NULL。
SELECT TO_TIME(15, NULL, 00);

-- 返回NULL。
SELECT TO_TIME(NULL, 30, 00);

签名3：TO_TIME(TIMESTAMP <timestamp>[, STRING <time_zone>])。

将TIMESTAMP类型数据转换为指定时区的时间值，并返回以微秒为单位用BIGINT类型表示的时间值。

示例1：默认时区下解析 TIMESTAMP。

-- 提取 Shanghai 时间 15:30:01.123 的微秒值。
-- 返回55801123000。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123');

示例2：配合FORMAT_TIME查看可读结果。

-- 将 TO_TIME 结果转为可读时间字符串。
-- 返回15:30:01.123。
SELECT FORMAT_TIME(TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123'), "%H:%M:%S.ff3");

示例3：指定目标时区。

-- 显式指定 Asia/Shanghai 时区。
-- 返回55801123000。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123', 'Asia/Shanghai');

示例4：跨时区转换。

-- Tokyo 比 Shanghai 快1小时，15:30 在 Tokyo 是 16:30。
-- 返回59401123456。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123456', 'Asia/Tokyo');

-- Bangkok 比 Shanghai 慢1小时，15:30 在 Bangkok 是 14:30。
-- 返回52201123456。
SELECT TO_TIME(TIMESTAMP '2025-09-01 15:30:01.123456789', 'Asia/Bangkok');

签名4：TO_TIME(TIMESTAMP_NTZ <timestamp_ntz>)。

将TIMESTAMP_NTZ类型数据转换为以微秒为单位用BIGINT类型表示的时间值。

示例：直接提取 NTZ 时间。

-- timestamp_ntz 不涉及时区转换，直接取时间部分。
-- 返回55801123456。
SELECT TO_TIME(TIMESTAMP_NTZ '2025-09-01 15:30:01.123456789');