DATEADD命令格式、參數和傳回值 - MaxCompute

按照指定的時間單位datepart，在指定的日期date或時間戳記上增加指定的幅度delta。

注意事項

如果您需要擷取在目前時間基礎上指定變動幅度的日期，請結合GETDATE函數使用。

命令格式

DATEADD(DATE|DATETIME|TIMESTAMP|TIMESTAMP_NTZ <date>, BIGINT <delta>, STRING <datepart>)

參數說明

date：必填。日期或時間戳記，支援DATE、DATETIME、TIMESTAMP或TIMESTAMP＿NTZ類型。
在MaxCompute1.0資料類型版本下，如果參數為STRING類型，格式符合DATETIME類型的格式，即yyyy-mm-dd hh:mi:ss，例如2025-07-21 00:00:00，則會隱式轉換為DATETIME類型後參與運算。
delta：必填。修改幅度，BIGINT類型。如果delta大於0，則增，否則減。
在MaxCompute1.0資料類型版本下，如果參數為STRING或DOUBLE類型的數字，則會隱式轉換為BIGINT類型後參與運算。
說明
- 按照指定的單位增減delta時，會導致更高單位的進位或退位。年、月、時、分秒分別按照10進位、12進位、24進位、60進位進行計算。
- 當delta的單位是月時，如果delta的月部分在增加delta值之後不造成Day溢出，則保持Day值不變，否則將Day值設定為結果月份的最後1天。
datepart：必填。指定修改的時間單位，STRING類型常量。非常量、不支援的格式或其他類型會返回報錯。支援如下取值：
時間單位
取值
年
year或yyyy
季度
quarter或q
月
month或mon或mm
周
week
日
day或dd
小時
hour或hh
分鐘
mi
秒
ss
毫秒
ff3
微秒
ff6

傳回值說明

返回DATE、DATETIME、TIMESTAMP或TIMESTAMP_NTZ類型，與輸入date參數資料類型一致。返回規則如下：

date資料類型非DATE、DATETIME、TIMESTAMP或TIMESTAMP＿NTZ類型時，則返回報錯。
date值為NULL時，返回報錯。
delta或datepart值為NULL時，返回NULL。

使用樣本

樣本1：待用資料常見用法

-- 返回2005-03-01 00:00:00。加1天，結果超出當年2月份的最後一天，實際值為下個月的第1天。
SELECT DATEADD(DATETIME '2005-02-28 00:00:00', 1, 'dd');
-- 返回2005-02-27 00:00:00。減1天。
SELECT DATEADD(DATETIME '2005-02-28 00:00:00', -1, 'dd');
-- 返回2006-10-28 00:00:00。加20個月，月份溢出，年份加1。
SELECT DATEADD(DATETIME '2005-02-28 00:00:00', 20, 'mm');
-- 返回2005-03-28 00:00:00。
SELECT DATEADD(DATETIME '2005-02-28 00:00:00', 1, 'mm');
-- 返回2005-02-28 00:00:00。2005年2月沒有29日，日期截取至當月最後1天。
SELECT DATEADD(DATETIME '2005-01-29 00:00:00', 1, 'mm');
-- 返回2005-02-28 00:00:00。
SELECT DATEADD(DATETIME '2005-03-30 00:00:00', -1, 'mm');
-- 返回2005-05-28。
SELECT DATEADD(DATE '2005-02-28', 1, 'quarter');
-- 返回2005-03-18。
SELECT DATEADD(DATE '2005-02-18', 1, 'mm');
-- 返回： 2005-03-14 00:00:00。
SELECT DATEADD(DATETIME '2005-02-28 00:00:00', 2, 'week');
-- 返回： 2005-03-14 00:00:00.123
SELECT DATEADD(TIMESTAMP '2005-02-28 00:00:00.123', 14, 'day');
-- 返回2005-03-30 02:24:00。減去3小時 
SELECT DATEADD(DATETIME '2005-03-30 05:24:00', -3, 'hh');
-- 返回2005-03-30 04:54:00。減去30分鐘 
SELECT DATEADD(DATETIME '2005-03-30 05:24:00', -30, 'mi');
-- 返回2005-03-30 05:23:30。減去30秒 
SELECT DATEADD(DATETIME '2005-03-30 05:24:00', -30, 'ss');
-- 返回： 2005-02-28 00:00:01.123456
SELECT DATEADD(TIMESTAMP_NTZ '2005-02-28 00:00:00.123456', 1000, 'ff3');
-- 返回： 2005-02-28 00:00:00.124456
SELECT DATEADD(TIMESTAMP '2005-02-28 00:00:00.123456', 1000, 'ff6');

-- 開啟2.0新類型。此命令需要與SQL語句一起提交。返回2005-03-18 00:00:00.0。
set odps.sql.type.system.odps2=true;
SELECT DATEADD(TIMESTAMP '2005-02-18 00:00:00', 1, 'mm');
-- 假設目前時間為2020-11-17 16:31:44，返回2020-11-16 16:31:44。
SELECT DATEADD(GETDATE(), -1, 'dd');
-- 返回NULL。
SELECT DATEADD(DATE '2005-02-18', 1, NULL);

樣本2：date參數類型說明

對於MaxCompute2.0資料類型版本，若date非DATE、DATETIME、TIMESTAMP或TIMESTAMP＿NTZ類型，需要進行類型轉換，否則會報錯。

SELECT DATEADD(CAST('2005-03-30 00:00:00' AS datetime), -1, 'mm');

-- 返回結果。
+------------+
| _c0        | 
+------------+
| 2005-02-28 00:00:00 | 
+------------+

對於MaxCompute1.0資料類型版本，若date為STRING類型，且格式符合DATETIME類型的格式即yyyy-mm-dd hh:mi:ss，則會隱式轉換為DATETIME類型後參與運算。

-- 設定資料類型版本為1.0
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- 錯誤樣本：如下輸入參數為STRING類型，但不符合DATETIME類型格式，會返回NULL。
SELECT DATEADD('2021-08-27',1,'dd');

-- 正確樣本：如下輸入參數為STRING類型，符合DATETIME類型格式。
SELECT DATEADD('2005-02-28 00:00:00', 1000000000, 'ff6');

-- 返回結果。
+------------+
| _c0        | 
+------------+
| 2005-02-28 00:16:40 | 
+------------+

MaxCompute：DATEADD