MaxCompute：DATETRUNC

命令格式

DATETRUNC函數支援以下兩種簽名格式，可以根據不同使用需求選擇合適的函數簽名。

• 簽名1：將日期/時間資料DATE|DATETIME|TIMESTAMP_NTZ按照指定的時間單位date_part進行截取，並返回截取後的日期/時間值。

  DATE|DATETIME|TIMESTAMP_NTZ DATETRUNC(DATE|DATETIME|TIMESTAMP_NTZ <date>, STRING <date_part>)
  
  -- 標準樣本。
  -- 返回2025-01-01 00:00:00。
  SELECT DATETRUNC(DATETIME '2025-12-07 16:28:46', 'yyyy');

• 簽名2：將TIMESTAMP類型資料轉換為指定時區的時間值，再按照指定的時間單位date_part進行截取，返回當前Session/Project時區的時間值。

  TIMESTAMP DATETRUNC（TIMESTAMP <date>,STRING <date_part>[, STRING <time_zone>]）
  
  -- 標準樣本。
  -- 當前Session/Project的時區為Asia/Shanghai。
  -- 返回2025-01-01 01:00:00。
  SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter', 'Asia/Jakarta');

參數說明

• date：必填。日期或時間戳記。支援DATE、DATETIME、TIMESTAMP或TIMESTAMP_NTZ類型。

  在MaxCompute1.0資料類型版本下，輸入參數可以為STRING類型，時間格式需符合DATETIME類型，即yyyy-mm-dd hh:mi:ss，例如2025-07-21 00:00:00，會隱式轉換為DATETIME類型後參與運算。

• date_part：必填。指定截斷的時間單位。STRING類型常量。 支援如下取值：

  時間單位	取值
  年	year或yyyy
  季度	quarter或q
  月	month或mon或mm
  周	week：以周一為一周的第一天，等效於week(monday) week(weekday)：以指定的星期幾(weekday)為一周的第一天。 有效取值：周日（SUNDAY）、周一（MONDAY）、周二（TUESDAY）、周三（WEDNESDAY）、周四（THURSDAY）、周五（FRIDAY）以及周六（SATURDAY）。
  ISO周	isoweek採用ISO 8601所規定的周邊界。ISO標準下的周從周一開始算起。
  日	day或dd
  小時	hour或hh
  分鐘	mi
  秒	ss
  毫秒	ff3

• time_zone：可選。用來指定時區，STRING類型。若未指定時區，則預設為當前Session/Project的時區。

  說明

  若未修改過專案時區，則預設為東八區（UTC+08:00）。

傳回值說明

使用樣本

• 樣本1：基本樣本。

  -- 返回2024-01-01 00:00:00。
  SELECT DATETRUNC(DATETIME'2024-12-07 16:28:46', 'yyyy');
  
  -- 返回2024-12-01 00:00:00。
  SELECT DATETRUNC(DATETIME'2024-12-07 16:28:46', 'MONTH');
  
  -- 返回2024-12-02。
  SELECT DATETRUNC(DATE'2024-12-07', 'week(monday)');
  
  -- 返回2024-10-01 00:00:00。
  SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46', 'q');
  
  -- 返回2024-12-07 16:28:46。
  SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46.123', 'ss');
  
  -- 返回2024-12-07 16:28:46.123。 
  SELECT DATETRUNC(TIMESTAMP_NTZ'2024-12-07 16:28:46.123456', 'ff3');
  
  -- 返回NULL。
  SELECT DATETRUNC(DATE'2024-12-07', NULL);

• 樣本2：使用time_zone參數指定時區。

  date類型為TIMESTAMP類型時，支援使用time_zone參數指定時區，返回當前Session/Project時區的時間值。

  -- 設定Session時區為Asia/Shanghai。
  SET odps.sql.timezone=Asia/Shanghai;
  -- 返回2024-01-01 00:00:00。
  SELECT DATETRUNC(TIMESTAMP '2024-12-07 16:28:46', 'yyyy');
  
  -- 返回2025-01-01 01:00:00。
  SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter','Asia/Jakarta');
  
  -- 返回2025-03-21 01:00:00。
  SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'week(friday)','Asia/Jakarta');
  
  -- 返回2025-03-24 08:00:00。
  SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'isoweek','Etc/GMT');
  
  -- 返回2025-11-07 01:00:00。
  SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00','dd','Asia/Jakarta');
  
  -- 返回2025-11-07 10:00:00。
  SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00','hour','Asia/Jakarta');
  
  -- 返回2025-11-07 10:30:00。
  SELECT DATETRUNC(TIMESTAMP '2025-11-07 10:30:00','mi','Asia/Jakarta');

• 樣本3：DATE參數為STRING類型。

  在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。
  -- 返回NULL。
  SELECT DATETRUNC('2025-07-27 16:28:46.123','mi');
  
  -- 正確樣本：如下輸入參數為STRING類型，符合DATETIME類型格式。
  -- 返回2025-07-27 16:28:00。
  SELECT DATETRUNC('2025-07-27 16:28:46', 'mi');

相關函數

DATETRUNC函數屬於日期函數，更多日期計算、日期轉換的相關函數請參見日期函數。