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函数属于日期函数，更多日期计算、日期转换的相关函数请参见日期函数。