MaxCompute:DATETRUNC

構文

この関数は、次の 2 つのシグネチャをサポートしています。

• シグネチャ 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 に切り捨ててから、現在のセッションまたはプロジェクトのタイムゾーンでの時刻値を返します。

  TIMESTAMP DATETRUNC(TIMESTAMP <date>,STRING <date_part>[, STRING <time_zone>])
  
  -- 標準的な例。
  -- 現在のセッションまたはプロジェクトのタイムゾーンはアジア/上海です。
  -- 2025-01-01 01:00:00 を返します。
  SELECT DATETRUNC(TIMESTAMP '2025-03-27 16:28:46', 'quarter', 'Asia/Jakarta');

パラメーター

• date: 必須。 日付またはタイムスタンプ。 サポートされているデータの型は DATE、DATETIME、TIMESTAMP、および TIMESTAMP_NTZ です。

  お使いの MaxCompute プロジェクトで V1.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
  2番目	ss
  ミリ秒	ff3

• time_zone：オプション。 タイムゾーン を指定する STRING 型。 このパラメーターを指定しない場合、デフォルトで現在のセッションまたはプロジェクトのタイムゾーンが使用されます。

  説明

  プロジェクトのタイムゾーンを変更していない場合、デフォルトは中国標準時 (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 パラメーターを使用してタイムゾーンを指定できます。 この関数は、現在のセッションまたはプロジェクトのタイムゾーンでの時刻値を返します。

  -- セッションタイムゾーンをアジア/上海に設定します。
  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 型の場合

  ご利用の MaxCompute プロジェクトで V1.0 データ型エディション を使用しており、date パラメーターが DATETIME フォーマット yyyy-mm-dd hh:mi:ss に一致する STRING 型である場合、その文字列は計算のために暗黙的に DATETIME 型に変換されます。

  -- データ型エディションを V1.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');
  
  -- 正しい例：次の入力パラメーターは DATETIME フォーマットに一致する STRING 型です。
  -- 2025-07-27 16:28:00 を返します。
  SELECT DATETRUNC('2025-07-27 16:28:46', 'mi');

関連関数

DATETRUNC は日付関数です。 日付の計算と変換のための関数の詳細については、「日付関数」をご参照ください。