MICROSECONDS_SUB

描述

MICROSECONDS_SUB 函数用于从输入的日期时间值中减去指定的微秒数，并返回计算后的新日期时间值。该函数支持 DATETIME、TIMESTAMP_NS 和 TIMESTAMPTZ。

该函数与 mysql 中的 date_sub 函数 使用 MICROSECOND 为单位的行为一致。

语法

MICROSECONDS_SUB(`<datetime_like_type>`, `<delta>`)

参数

参数	说明
<datetime_like_type>	输入的日期时间值，类型为 DATETIME、TIMESTAMP_NS 或 TIMESTAMPTZ。具体格式请参见 DATETIME 的转换、TIMESTAMP_NS 的转换和 TIMESTAMPTZ 的转换。
<delta>	要减去的微秒数，类型为 BIGINT，1 秒 = 1,000,000 微秒

返回值

返回基准时间<datetime_like_type>减去指定微秒<delta>后的结果，返回类型与第一个参数类型相同

• 若第一个参数为 TIMESTAMP_NS，则返回 TIMESTAMP_NS 并保留纳秒部分。

• 若 <delta> 为负数，函数效果等同于向基准时间中添加对应微秒数（即 MICROSECONDS_SUB(basetime, -n) 等价于 MICROSECONDS_ADD(basetime, n)）。

• 若计算结果超出 DATETIME 类型的有效范围（0000-01-01 00:00:00 至 9999-12-31 23:59:59.999999），抛出异常。

• 对于 TIMESTAMP_NS，结果必须在 1677-09-21 00:12:43.145224192 到 2262-04-11 23:47:16.854775807 范围内。

• 若任一参数为 NULL，返回 NULL。

举例

---减去微秒
SELECT NOW(3) AS current_time, MICROSECONDS_SUB(NOW(3), 100000) AS after_sub;
+-------------------------+----------------------------+
| current_time            | after_sub                  |
+-------------------------+----------------------------+
| 2025-01-16 11:52:22.296 | 2025-01-16 11:52:22.196000 |
+-------------------------+----------------------------+

--- delta 为负数（等价于加法）
mysql> SELECT MICROSECONDS_SUB('2023-10-01 12:00:00.200000', -300000) AS after_sub;
+----------------------------+
| after_sub                  |
+----------------------------+
| 2023-10-01 12:00:00.500000 |
+----------------------------+

--- TIMESTAMP_NS 会保留纳秒部分
SELECT MICROSECONDS_SUB(CAST('2025-01-02 03:04:05.123456789' AS TIMESTAMP_NS), 1);
+-----------------------------------------------------------------------------------+
| MICROSECONDS_SUB(CAST('2025-01-02 03:04:05.123456789' AS TIMESTAMP_NS), 1) |
+-----------------------------------------------------------------------------------+
| 2025-01-02 03:04:05.123455789                                                     |
+-----------------------------------------------------------------------------------+

--- 任一参数为 NULL，返回 NULL
SELECT MICROSECONDS_SUB(NULL, 1000), MICROSECONDS_SUB('2023-01-01', NULL) AS after_sub;
+------------------------------+----------------------------+
| microseconds_sub(NULL, 1000) | after_sub                  |
+------------------------------+----------------------------+
| NULL                         | NULL                       |
+------------------------------+----------------------------+

---输入类型为 date ,时间部分自动设置为 00:00:00.000000
SELECT MICROSECONDS_SUB('2023-10-01', -300000);
+-----------------------------------------+
| MICROSECONDS_SUB('2023-10-01', -300000) |
+-----------------------------------------+
| 2023-10-01 00:00:00.300000              |
+-----------------------------------------+

-- TimeStampTz 类型测试, SET time_zone = '+08:00'
SELECT MICROSECONDS_SUB('2024-12-25 12:34:56.123+04:00', '765800');
+-------------------------------------------------------------+
| MICROSECONDS_SUB('2024-12-25 12:34:56.123+04:00', '765800') |
+-------------------------------------------------------------+
| 2024-12-25 16:34:55.357200+08:00                            |
+-------------------------------------------------------------+

---超出日期时间范围，抛出错误
mysql> SELECT MICROSECONDS_SUB('0000-01-01 00:00:00.000000', 1000000) AS after_sub;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation microseconds_add of 0000-01-01 00:00:00, -1000000 
out of range