类别：

日期和时间函数

DATEDIFF

根据请求的日期或时间部分计算两个日期、时间或时间戳表达式之间的差异。该函数返回从第三个实参中减去第二个实参的结果。

备注

差异计算会比较指定的日期或时间部分，而非完整的日期或时间。例如，2024 年 11 月 28 日与 2024 年 12 月 5 日之间的月份差为 1，因为 2024 年 11 月与 12 月这两个月之间的差为 1。为了体现两个日期之间的差异小于一个月的事实，应计算天数差异。

您还可以使用减号 (-)，从另一个日期减去一个日期，从而计算两个日期之间的差。

要向日期、时间或时间戳添加时间单位（例如，向日期添加两天）或从中减去时间单位，您可以使用 DATEADD、TIMEADD 或 TIMESTAMPADD 函数。

另请参阅：

TIMEDIFF、TIMESTAMPDIFF

语法

对于 DATEDIFF：

DATEDIFF( <date_or_time_part>, <date_or_time_expr1>, <date_or_time_expr2> )

对于减号：

<date_expr2> - <date_expr1>

实参

对于 DATEDIFF：

date_or_time_part

时间单位。必须是 支持的日期和时间部分 中列出的一个值（例如 month）。该值可以是字符串字面量，也可以不带引号（例如，'month' 或 month）。

date_or_time_expr1、date_or_time_expr2

要比较的值。必须是日期、时间、时间戳或计算结果为日期、时间或时间戳的表达式。从 date_or_time_expr2 中减去 date_or_time_expr1 值。

对于减号：

date_expr1、date_expr2

要比较的值。必须是日期，或者计算结果为日期的表达式。从 date_expr2 中减去 date_expr1 值。

返回

对于 DATEDIFF：

返回一个整数，表示 date_or_time_expr2 和 date_or_time_expr1 之间单位数（秒、天等）之差。

如果任何实参为 NULL，则返回 NULL。

对于减号：

返回一个整数，表示 date_expr2 和 date_expr1 之间的天数差。（单位始终为天。）

如果 date_expr2 或 date_expr1 为 NULL，则返回错误。

使用说明

对于 DATEDIFF 和减号：

  • 输出值可以是负数，例如 -12 天。

对于 DATEDIFF：

  • 此函数支持年、季度、月、周、日、小时、分钟、秒、毫秒、微秒和纳秒的单位。

  • 如果 date_or_time_part 是 week （或其任何变体），则输出由 WEEK_START 会话参数所控制。有关更多详细信息（包括示例），请参阅 日历周和工作日。

  • 用于计算差值的单位（例如 month）决定了计算 DATE、TIME、或 TIMESTAMP 字段的哪些部分。因此，单位决定结果的精度。

    不使用较小的单位，因此值不会四舍五入。例如，即使 2021 年 1 月 1 日和 2021 年 2 月 28 日之间的差值接近两个月而不是一个月，但以下查询返回一个月：

    DATEDIFF(month, '2021-01-01'::DATE, '2021-02-28'::DATE)

    对于 DATE 值：

    • year 仅使用年份，而忽略所有其他部分。

    • month 使用月份和年份。

    • day 使用整个日期。

    对于 TIME 值：

    • hour 仅使用小时，而忽略所有其他部分。

    • minute 使用小时和分钟。

    • second 使用小时、分钟和秒，但不使用小数秒。

    • millisecond 使用小时、分钟、秒和小数秒的前三位数字。小数秒数不四舍五入。例如，DATEDIFF(milliseconds, '2024-02-20 21:18:41.0000', '2024-02-20 21:18:42.1239') 返回 1.123 秒，而不是 1.124 秒。

    • microsecond 使用小时、分钟、秒和小数秒的前六位数字。小数秒数不四舍五入。

    • nanosecond 使用小时、分钟、秒和小数秒的所有九位数字。

    对于 TIMESTAMP 值：

    这些规则与上述 DATE 和 TIME 数据类型的规则相匹配。仅使用指定的单位和较大单位。

对于减号：

  • date_expr1 和 date_expr2 都必须是日期。不允许是时间和时间戳。

示例

计算两个时间戳之间的年差：

SELECT DATEDIFF(year, 
                '2020-04-09 14:39:20'::TIMESTAMP, 
                '2023-05-08 23:39:20'::TIMESTAMP) 
  AS diff_years;

+------------+
| DIFF_YEARS |
|------------|
|          3 |
+------------+

计算两个时间戳之间的小时差：

SELECT DATEDIFF(hour, 
               '2023-05-08T23:39:20.123-07:00'::TIMESTAMP, 
               DATEADD(year, 2, ('2023-05-08T23:39:20.123-07:00')::TIMESTAMP)) 
  AS diff_hours;

+------------+
| DIFF_HOURS |
|------------|
|      17544 |
+------------+

演示日期部分如何影响 DATEDIFF 计算；此外，还演示使用减号进行日期减法：

SELECT column1 date_1, column2 date_2,
       DATEDIFF(year, column1, column2) diff_years,
       DATEDIFF(month, column1, column2) diff_months,
       DATEDIFF(day, column1, column2) diff_days,
       column2::DATE - column1::DATE AS diff_days_via_minus
  FROM VALUES
       ('2015-12-30', '2015-12-31'),
       ('2015-12-31', '2016-01-01'),
       ('2016-01-01', '2017-12-31'),
       ('2016-08-23', '2016-09-07');

+------------+------------+------------+-------------+-----------+---------------------+
| DATE_1     | DATE_2     | DIFF_YEARS | DIFF_MONTHS | DIFF_DAYS | DIFF_DAYS_VIA_MINUS |
|------------+------------+------------+-------------+-----------+---------------------|
| 2015-12-30 | 2015-12-31 |          0 |           0 |         1 |                   1 |
| 2015-12-31 | 2016-01-01 |          1 |           1 |         1 |                   1 |
| 2016-01-01 | 2017-12-31 |          1 |          23 |       730 |                 730 |
| 2016-08-23 | 2016-09-07 |          0 |           1 |        15 |                  15 |
+------------+------------+------------+-------------+-----------+---------------------+

演示时间部分如何影响 DATEDIFF 计算：

ALTER SESSION SET TIMESTAMP_NTZ_OUTPUT_FORMAT = 'DY, DD MON YYYY HH24:MI:SS';

SELECT column1 timestamp_1, column2 timestamp_2,
       DATEDIFF(hour, column1, column2) diff_hours,
       DATEDIFF(minute, column1, column2) diff_minutes,
       DATEDIFF(second, column1, column2) diff_seconds
  FROM VALUES
       ('2016-01-01 01:59:59'::TIMESTAMP, '2016-01-01 02:00:00'::TIMESTAMP),
       ('2016-01-01 01:00:00'::TIMESTAMP, '2016-01-01 01:59:00'::TIMESTAMP),
       ('2016-01-01 01:00:59'::TIMESTAMP, '2016-01-01 02:00:00'::TIMESTAMP);

+---------------------------+---------------------------+------------+--------------+--------------+
| TIMESTAMP_1               | TIMESTAMP_2               | DIFF_HOURS | DIFF_MINUTES | DIFF_SECONDS |
|---------------------------+---------------------------+------------+--------------+--------------|
| Fri, 01 Jan 2016 01:59:59 | Fri, 01 Jan 2016 02:00:00 |          1 |            1 |            1 |
| Fri, 01 Jan 2016 01:00:00 | Fri, 01 Jan 2016 01:59:00 |          0 |           59 |         3540 |
| Fri, 01 Jan 2016 01:00:59 | Fri, 01 Jan 2016 02:00:00 |          1 |           60 |         3541 |
+---------------------------+---------------------------+------------+--------------+--------------+

将 CURRENT_TIMESTAMP 函数与 DATEDIFF 函数结合使用，计算指定时间戳和当前时间戳之间的年、月和日之差：

SELECT column1 specified_timestamp,
       column2 timestamp_now,
       DATEDIFF(year, column1, column2) diff_years,
       DATEDIFF(month, column1, column2) diff_months,
       DATEDIFF(day, column1, column2) diff_days,
       column2::DATE - column1::DATE AS diff_days_via_minus
  FROM VALUES
    ('2012-08-23 09:00:00.000 -0700', CURRENT_TIMESTAMP);

+-------------------------------+-------------------------------+------------+-------------+-----------+---------------------+
| SPECIFIED_TIMESTAMP           | TIMESTAMP_NOW                 | DIFF_YEARS | DIFF_MONTHS | DIFF_DAYS | DIFF_DAYS_VIA_MINUS |
|-------------------------------+-------------------------------+------------+-------------+-----------+---------------------|
| 2012-08-23 09:00:00.000 -0700 | 2024-09-04 17:21:12.189 -0700 |         12 |         145 |      4395 |                4395 |
+-------------------------------+-------------------------------+------------+-------------+-----------+---------------------+