MySQL TIMESTAMPDIFF() 函數 (計算兩個日期時間的精確間隔)

TIMESTAMPDIFF() 是 MySQL 中用來計算兩個日期時間之間的精確間隔的函數。與 DATEDIFF() 只能計算天數不同，TIMESTAMPDIFF() 可以指定返回的時間單位（年、月、日、小時、分鐘、秒等）。

TIMESTAMPDIFF() 語法 (Syntax)

TIMESTAMPDIFF(unit, datetime_expr1, datetime_expr2)

unit：返回值的時間單位。
datetime_expr1：開始時間（較早的時間）。
datetime_expr2：結束時間（較晚的時間）。
返回值：datetime_expr2 - datetime_expr1 的整數差值（以指定的 unit 為單位）。

unit 可用的值

unit	說明
MICROSECOND	微秒
SECOND	秒
MINUTE	分鐘
HOUR	小時
DAY	天
WEEK	週
MONTH	月
QUARTER	季度
YEAR	年

TIMESTAMPDIFF() 函數用法範例 (Example)

計算相差幾天

SELECT TIMESTAMPDIFF(DAY, '2024-01-01', '2024-12-31');
-- 結果：365（2024 年是閏年）

SELECT TIMESTAMPDIFF(DAY, '2023-01-01', '2023-12-31');
-- 結果：364（2023 年不是閏年）

計算相差幾個月

SELECT TIMESTAMPDIFF(MONTH, '2024-01-15', '2024-05-15');
-- 結果：4

SELECT TIMESTAMPDIFF(MONTH, '2024-01-31', '2024-02-28');
-- 結果：0（未滿整個月）

SELECT TIMESTAMPDIFF(MONTH, '2024-01-01', '2024-02-01');
-- 結果：1

計算相差幾年

SELECT TIMESTAMPDIFF(YEAR, '2000-06-15', '2024-06-14');
-- 結果：23（未滿 24 年，因為 6/14 還沒到 6/15）

SELECT TIMESTAMPDIFF(YEAR, '2000-06-15', '2024-06-15');
-- 結果：24（剛好 24 年）

計算相差幾小時

SELECT TIMESTAMPDIFF(HOUR, '2024-11-22 08:00:00', '2024-11-22 17:30:00');
-- 結果：9（從 8 點到 17:30 是 9 個完整小時）

SELECT TIMESTAMPDIFF(HOUR, '2024-11-22 08:00:00', '2024-11-23 08:00:00');
-- 結果：24

計算相差幾分鐘

SELECT TIMESTAMPDIFF(MINUTE, '2024-11-22 10:00:00', '2024-11-22 10:45:30');
-- 結果：45（45 分 30 秒，取整數部分）

SELECT TIMESTAMPDIFF(MINUTE, '2024-01-01 00:00:00', '2024-01-01 23:59:59');
-- 結果：1439（一天有 1440 分鐘，這裡是 23:59:59）

計算相差幾秒

SELECT TIMESTAMPDIFF(SECOND, '2024-11-22 10:00:00', '2024-11-22 10:01:30');
-- 結果：90

實際應用範例

計算精確年齡

SELECT 
    name,
    birthday,
    TIMESTAMPDIFF(YEAR, birthday, CURDATE()) AS age
FROM users;

name	birthday	age
張三	1990-05-15	34
李四	2000-12-01	23

計算服務時長（年資）

SELECT 
    employee_name,
    hire_date,
    TIMESTAMPDIFF(YEAR, hire_date, CURDATE()) AS years_of_service,
    TIMESTAMPDIFF(MONTH, hire_date, CURDATE()) AS months_of_service
FROM employees;

計算訂單處理時間

SELECT 
    order_id,
    created_at,
    completed_at,
    TIMESTAMPDIFF(HOUR, created_at, completed_at) AS hours_to_complete
FROM orders
WHERE completed_at IS NOT NULL;

計算會員資格剩餘時間

SELECT 
    user_id,
    membership_end,
    TIMESTAMPDIFF(DAY, NOW(), membership_end) AS days_remaining,
    TIMESTAMPDIFF(HOUR, NOW(), membership_end) AS hours_remaining
FROM memberships
WHERE membership_end > NOW();

篩選最近 N 小時內的記錄

-- 取得最近 24 小時內的活動記錄
SELECT * FROM activity_logs
WHERE TIMESTAMPDIFF(HOUR, created_at, NOW()) <= 24;

-- 或使用更有效率的方式
SELECT * FROM activity_logs
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR);

計算回應時間的統計

SELECT 
    AVG(TIMESTAMPDIFF(MINUTE, created_at, first_response_at)) AS avg_response_minutes,
    MIN(TIMESTAMPDIFF(MINUTE, created_at, first_response_at)) AS min_response_minutes,
    MAX(TIMESTAMPDIFF(MINUTE, created_at, first_response_at)) AS max_response_minutes
FROM support_tickets
WHERE first_response_at IS NOT NULL;

TIMESTAMPDIFF() 與 DATEDIFF() 的比較

特性	TIMESTAMPDIFF()	DATEDIFF()
參數順序	(unit, start, end)	(end, start)
時間單位	可指定（年、月、日、時等）	只有天
時間部分	會考慮	會忽略
計算方向	end - start	end - start

-- 注意：參數順序不同！
SELECT DATEDIFF('2024-12-31', '2024-01-01');
-- 結果：365

SELECT TIMESTAMPDIFF(DAY, '2024-01-01', '2024-12-31');
-- 結果：365

注意事項

TIMESTAMPDIFF() 返回的是整數，會捨棄小數部分。
參數順序是 (unit, start, end)，計算 end - start，與 DATEDIFF(end, start) 的參數順序相反。
如果 datetime_expr1 晚於 datetime_expr2，返回負數。
如果任一參數為 NULL，結果也是 NULL。