大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:TIMESTAMPDIFF

· 52CE 我爱测

与 date-diff 函数 作用一致 TIMESTAMPDIFF 函数用于计算两个日期时间值之间的差值,并以指定的时间单位返回结果。该函数支持多种时间单位(如秒、分、时、日、周、月、年)

描述

与 date-diff 函数 作用一致 TIMESTAMPDIFF 函数用于计算两个日期时间值之间的差值,并以指定的时间单位返回结果。该函数支持多种时间单位(如秒、分、时、日、周、月、年)

该函数与 mysql 中的 date_diff 函数 行为一致

语法

TIMESTAMPDIFF(<unit>, <date_or_time_expr1>, <date_or_time_expr2>)

参数

参数 说明
<unit> 时间单位,指定要返回的单位,常见的值有 SECOND、MINUTE、HOUR、DAY、MONTH、QUARTERYEAR 等
<date_or_time_expr1> 第一个日期时间,开始日期时间,支持输入 date/datetime 类型,具体 datetime 和 date 格式请查看 datetime 的转换 和 date 的转换
<date_or_time_expr2> 第二个日期时间,结束日期时间,支持输入 date/datetime 类型

返回值

返回两个日期时间之间的差异,类型为 BIGINT。

  • 若 <date_or_time_expr2> 晚于 <date_or_time_expr1>,返回正数;
  • 若 <dat_or_etime_expr2> 早于 <date_or_time_expr1>,返回负数;
  • 若任一参数为 NULL,返回 NULL;
  • 若 <unit> 为不支持的单位,返回 错误;
  • 计算一个单位时,不会忽略下一个单位,例如会计算真实差距是否满足一天,若不足则返回 0
  • 月份计算特殊情况,如 1-31 与 2-28,差数为一月
  • 输入 date 类型时,时间部分默认设置为 00:00:00

举例

-- 计算两个日期的月份差
SELECT TIMESTAMPDIFF(MONTH, '2003-02-01', '2003-05-01') AS result;
+--------+
| result |
+--------+
|      3 |
+--------+

-- 计算年份差(结束日期早于起始日期,返回负值)
SELECT TIMESTAMPDIFF(YEAR, '2002-05-01', '2001-01-01') AS result;
+--------+
| result |
+--------+
|     -1 |
+--------+

-- 计算分钟差
SELECT TIMESTAMPDIFF(MINUTE, '2003-02-01', '2003-05-01 12:05:55') AS result;
+--------+
| result |
+--------+
| 128885 |
+--------+

-- 计算真实差距不足一天
SELECT TIMESTAMPDIFF(DAY, '2023-12-31 23:59:50', '2024-01-01 00:00:05') AS result;
+--------+
| result |
+--------+
|      0 |
+--------+

-- 输入非法单位 QUARTER ,返回错误
SELECT TIMESTAMPDIFF(QUAR, '2023-01-01', '2023-07-01') AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = Unsupported time stamp diff time unit: QUAR, supported time unit: YEAR/MONTH/WEEK/DAY/HOUR/MINUTE/SECOND

-- 月份计算特殊情况(月底跨月)
SELECT TIMESTAMPDIFF(MONTH, '2023-01-31', '2023-02-28') AS result;
+--------+
| result |
+--------+
|      1 |
+--------+

SELECT TIMESTAMPDIFF(MONTH, '2023-01-31', '2023-02-27') AS result;
+--------+
| result |
+--------+
|      0 |
+--------+

-- 任一参数为NULL(返回NULL)
SELECT TIMESTAMPDIFF(DAY, NULL, '2023-01-01'), TIMESTAMPDIFF(DAY, '2023-01-01', NULL) AS result;
+---------------------------------------+--------+
| timestampdiff(DAY, NULL, '2023-01-01') | result |
+---------------------------------------+--------+
| NULL                                  | NULL   |
+---------------------------------------+--------+

-- 周数差计算
SELECT TIMESTAMPDIFF(WEEK, '2023-01-01', '2023-01-15') AS result;
+--------+
| result |
+--------+
|      2 |
+--------+

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。