DATE_DIFF

​

Syntax

​

Days (scalar)

date_diff(end, start)

​

Units (scalar)

date_diff(unit, start, end)

​

Arguments

​

Days

​

Units

​

Returns

• Type: BIGINT
• NULL behavior: Returns NULL if a temporal argument or unit is NULL, or a timestamp cannot be represented by the temporal conversion. An unknown non-NULL unit raises an error.

​

Properties

​

Units

• Input unit: Calendar dates or timestamps
• Output unit: Days for the two-argument form; specified complete units for the three-argument form

​

Usage notes

• Two-argument order is (end,start); three-argument order is (unit,start,end).
• Two arguments compare local calendar dates and discard time-of-day; three arguments count complete elapsed units.
• Calendar year/quarter/month results use complete calendar units, not a fixed number of seconds. Negative differences are possible.

​

Examples

​

Cross a date boundary

SELECT date_diff(TIMESTAMP '2024-07-16 00:01:00', TIMESTAMP '2024-07-15 23:59:00') AS result;

​

Complete elapsed hours

SELECT date_diff('hour', TIMESTAMP '2024-07-15 22:00:00', TIMESTAMP '2024-07-16 00:30:00') AS result;