日付関数リファレンス：DATEADD、DATEDIFF 他 - IoT Platform

このトピックでは、データ分析機能でサポートされている日付関数の構文、パラメーター、および例について説明します。ビジネス要件に基づいて日付の計算または変換を実行するために、適切な日付関数を選択できます。

関数	説明
CURRENT_TIMESTAMP	現在のタイムスタンプを返します。
DATEADD	datepart で指定された時間単位と delta で指定された間隔に基づいて、日付値を変更します。
DATEDIFF	datepart で指定された時間単位に基づいて、2 つの日付値の差を計算します。
FROM_UNIXTIME	BIGINT 型の UNIX タイムスタンプを DATETIME 型の日付値に変換します。
FROM_UTC_TIMESTAMP	UTC タイムスタンプを指定されたタイムゾーンのタイムスタンプに変換します。
GETDATE	現在のシステム時刻を日付値として返します。
ISDATE	日付文字列を指定された形式の日付値に変換できるかどうかを判断します。
TO_DATE	文字列を指定された形式の日付値に変換します。
TO_CHAR	日付値を指定された形式の文字列に変換します。
UNIX_TIMESTAMP	日付値を整数である UNIX タイムスタンプに変換します。
LAST_DAY	日付値が属する月の最終日を返します。

CURRENT_TIMESTAMP

構文
```
timestamp current_timestamp()
```
説明
現在のタイムスタンプを返します。戻り値は固定されていません。
戻り値
TIMESTAMP 型の値が返されます。

例

-- 戻り値は '2017-08-03 11:50:30.661' です。
    current_timestamp();

DATEADD

構文

datetime dateadd(datetime <date>, bigint <delta>, string <datepart>)

説明
date 値を、datepart で指定された時間単位と delta で指定された間隔に基づいて変更します。現在時刻に加算または減算するには、この関数を GETDATE 関数と共に呼び出すことができます。
パラメーター
- date: 必須。DATETIME 型の日付値。
  入力値が STRING 型の場合、計算前に暗黙的に DATETIME 型の値に変換されます。入力値が別のデータ型の場合、エラーが返されます。
- delta: 必須。日付値の指定されたコンポーネントに加算または減算する間隔。このパラメーターの値は BIGINT 型である必要があります。delta の値が 0 より大きい場合、間隔が日付値に加算されます。それ以外の場合、間隔が日付値から減算されます。
  入力値が STRING 型または DOUBLE 型の場合、計算前に値は暗黙的に BIGINT 型の値に変換されます。入力値が別のデータ型の場合、エラーが返されます。
  説明
  - datepart で指定された時間単位に基づいて delta で指定された間隔を加算または減算すると、より重要な日付コンポーネントで繰り上げまたは繰り下げが発生する場合があります。年、月、時、分、秒のコンポーネントは、異なる記数法を使用して計算されます。年のコンポーネントは 10 進法を使用します。月のコンポーネントは 12 進法を使用します。時のコンポーネントは 24 進法を使用します。分と秒のコンポーネントは 60 進法を使用します。
  - DATEADD 関数が日付値の月のコンポーネントに delta で指定された間隔を加算し、この操作によって日のコンポーネントでオーバーフローが発生しない場合、日のコンポーネントの値を保持できます。それ以外の場合、日のコンポーネントの値を指定された月の最終日に設定する必要があります。
- datepart: 必須。日付値で変更する日付部分。値は STRING 型の定数です。入力値の形式が無効であるか、入力値が STRING 型の定数でない場合、エラーが返されます。
  このパラメーターの値は、STRING 型と DATETIME 型の間の変換ルールに準拠して指定されます。yyyy 値は、DATEADD 関数が日付値の年のコンポーネントに間隔を加算または減算することを示します。mm 値は、DATEADD 関数が日付値の月のコンポーネントに間隔を加算または減算することを示します。dd 値は、DATEADD 関数が日付値の日のコンポーネントに間隔を加算または減算することを示します。データ型の変換ルールの詳細については、「STRING 型と DATETIME 型の間の変換」をご参照ください。拡張日付/時刻形式 (EDTF) もサポートされています (例: -year、-month、-mon、-day、-hour)。
戻り値
DATETIME 型の値が返されます。入力パラメーターが NULL に設定されている場合、NULL が返されます。

例

例 1: trans_date=2005-02-28 00:00:00。

-- 戻り値は 2005-03-01 00:00:00 です。1 日が加算された後、結果は 2 月の最終日の後になります。3 月の最初の日が返されます。
    dateadd(trans_date, 1, 'dd');

-- 戻り値は 2005-02-27 00:00:00 です。1 日が減算されます。
    dateadd(trans_date, -1, 'dd');

-- 戻り値は 2006-10-28 00:00:00 です。20 か月が加算された後、月がオーバーフローし、年の値が 1 増加します。
    dateadd(trans_date, 20, 'mm');

-- 戻り値は 2005-03-28 00:00:00 です。
    dateadd(trans_date, 1, 'mm');

例 2: trans_date=2005-01-29 00:00:00。

-- 戻り値は 2005-02-28 00:00:00 です。2005 年 2 月は 28 日しかありません。したがって、2 月の最終日が返されます。
    dateadd(trans_date, 1, 'mm');

例 3: trans_date2005-03-30 00:00:00。

-- 戻り値は 2005-02-28 00:00:00 です。
    dateadd(trans_date, -1, 'mm');

例 4: 現在時刻を計算します。

-- 現在時刻が 2020 年 11 月 17 日 16:31:44 の場合、戻り値は 2020-11-16 16:31:44 です。
    dateadd(getdate(),-1,'dd');

例 5: STRING 型の定数を明示的に DATETIME 型に変換します。

-- 戻り値は 2005-02-28 00:00:00 です。
    dateadd(cast("2005-03-30 00:00:00" as datetime), -1, 'mm');

DATEDIFF

構文

bigint datediff(datetime <date1>, datetime <date2>, string <datepart>)

説明
date1 と date2 の差を計算します。差は、datepart で指定された時間単位で測定されます。
パラメーター
- date1 および date2: 必須。DATETIME 型の値。値は、被減数と減数を示します。入力値が STRING 型の場合、計算前に値は暗黙的に DATETIME 型の値に変換されます。入力値が別のデータ型の場合、エラーが返されます。
- datepart: 必須。日付値で変更する日付部分。値は STRING 型の定数です。入力値の形式が無効であるか、入力値が STRING 型の定数でない場合、エラーが返されます。
  このパラメーターの値は、STRING 型と DATETIME 型の間の変換ルールに準拠して指定されます。yyyy 値は、DATEADD 関数が日付値の年のコンポーネントに間隔を加算または減算することを示します。mm 値は、DATEADD 関数が日付値の月のコンポーネントに間隔を加算または減算することを示します。dd 値は、DATEADD 関数が日付値の日のコンポーネントに間隔を加算または減算することを示します。データ型の変換ルールの詳細については、「STRING 型と DATETIME 型の間の変換」をご参照ください。拡張日付/時刻形式 (EDTF) もサポートされています (例: -year、-month、-mon、-day、-hour)。
  説明
  この関数は、datepart で指定された時間単位に基づいて下位単位を省略し、結果を計算します。
戻り値
BIGINT 型の値が返されます。入力パラメーターが NULL に設定されている場合、NULL が返されます。date1 が date2 より前の場合、負の値が返されます。

例

例 1: start=2005-12-31 23:59:59, end=2006-01-01 00:00:00。

-- 戻り値は 1 です。
    datediff(end, start, 'dd'); 

-- 戻り値は 1 です。
    datediff(end, start, 'mm');

-- 戻り値は 1 です。
    datediff(end, start, 'yyyy');

-- 戻り値は 1 です。
    datediff(end, start, 'hh');

-- 戻り値は 1 です。
    datediff(end, start, 'mi');

-- 戻り値は 1 です。
    datediff(end, start, 'ss');

-- 戻り値は 1800 です。
    datediff(datetime'2013-05-31 13:00:00', '2013-05-31 12:30:00', 'ss');

-- 戻り値は 30 です。
    datediff(datetime'2013-05-31 13:00:00', '2013-05-31 12:30:00', 'mi');

例 2: 開始時刻が 2018-06-04 19:33:23.234 で、終了時刻が 2018-06-04 19:33:23.250 の場合、ミリ秒単位まで正確な日付値は標準の DATETIME 型を使用せず、暗黙的に DATETIME 型に変換できません。この場合、明示的な変換が必要です。
```
-- 戻り値は 16 です。
    datediff(to_date('2018-06-04 19:33:23.250', 'yyyy-mm-dd hh:mi:ss.ff3'), to_date('2018-06-04 19:33:23.234', 'yyyy-mm-dd hh:mi:ss.ff3') , 'ff3');
```

FROM_UNIXTIME

構文

datetime from_unixtime(bigint <unixtime>)

説明
BIGINT 型の unixtime を DATETIME 型の日付値に変換します。
パラメーター
unixtime: 必須。UNIX 形式の BIGINT 型の日付値。このパラメーターの値は秒単位まで正確です。入力値が STRING 型、DOUBLE 型、または DECIMAL 型の場合、計算前に値は暗黙的に BIGINT 型の値に変換されます。
戻り値
DATETIME 型の値が返されます。入力パラメーターが NULL に設定されている場合、NULL が返されます。

例

-- 戻り値は 1973-11-30 05:33:09 です。
    from_unixtime(123456789);

FROM_UTC_TIMESTAMP

構文

timestamp from_utc_timestamp({any primitive type}*, string <timezone>)

説明
UTC タイムスタンプを指定されたタイムゾーンのタイムスタンプに変換します。
パラメーター
- {any primitive type}*: 必須。TIMESTAMP 型、DATETIME 型、TINYINT 型、SMALLINT 型、INT 型、または BIGINT 型のタイムスタンプ。値が TINYINT 型、SMALLINT 型、INT 型、または BIGINT 型の場合、時間単位はミリ秒単位まで正確です。
- timezone: 必須。現在時刻帯を変換する先のタイムゾーン。たとえば、このパラメーターを PST に設定できます。
  この関数は Asia/Shanghai タイムゾーンのみをサポートし、GMT+9 タイムゾーンはサポートしていません。
  UTC 時刻は UTC+0 タイムゾーンの時刻を指します。中国の上海は UTC+8 タイムゾーンにあります。
戻り値
TIMESTAMP 型の値が返されます。

例

-- 入力値の単位はミリ秒で、2017-08-01 04:24:00.0 が返されます。
    from_utc_timestamp(1501557840000, 'PST'); 

-- 戻り値は 1970-01-30 08:00:00.0 です。
    from_utc_timestamp('1970-01-30 16:00:00','PST'); 

-- 戻り値は 1970-01-29 16:00:00.0 です。
    from_utc_timestamp('1970-01-30','PST') ;

GETDATE

構文
```
datetime getdate()
```
説明
現在のシステム時刻を返します。
戻り値
現在の日付と時刻が返されます。これらは DATETIME 型です。

ISDATE

構文

boolean isdate(string <date>, string <format>)

説明
日付文字列を指定された形式の日付値に変換できるかどうかを判断します。日付文字列を指定された形式の日付値に変換できる場合、true が返されます。それ以外の場合、false が返されます。
パラメーター
- date: 必須。STRING 型の値。入力値が BIGINT 型、DOUBLE 型、DECIMAL 型、または DATETIME 型の場合、計算前に値は暗黙的に STRING 型の値に変換されます。入力値が別のデータ型の場合、エラーが返されます。
- format: 必須。STRING 型の定数。このパラメーターは EDTF をサポートしていません。入力値が別のデータ型の場合、エラーが返されます。format に冗長な形式文字列が存在する場合、この関数は最初の形式文字列に対応する日付文字列を日付値に変換します。他の文字列は区切り文字と見なされます。
戻り値
BOOLEAN 型の値が返されます。入力パラメーターが NULL に設定されている場合、NULL が返されます。

例

-- 戻り値は true です。
isdate("1234-yyyy", "yyyy-yyyy");

TO_DATE

構文

datetime to_date(string <date>, string <format>)

説明
文字列を指定された format の date 値に変換します。
パラメーター
- date: 必須。STRING 型の値。このパラメーターは、変換する日付文字列を指定します。入力値が BIGINT 型、DOUBLE 型、DECIMAL 型、または DATETIME 型の場合、計算前に暗黙的に STRING 型の値に変換されます。入力値が別のデータ型または空の文字列の場合、エラーが返されます。
- format: 必須。STRING 型の定数。このパラメーターは、日付形式を指定します。入力値が別のデータ型の場合、エラーが返されます。format は EDTF をサポートしていません。他の文字は、解析中に無効な文字として省略されます。
  format の値には yyyy が含まれている必要があります。それ以外の場合、NULL が返されます。format に冗長な形式文字列が存在する場合、この関数は最初の形式文字列に対応する日付文字列を日付値に変換します。他の文字列は区切り文字と見なされます。たとえば、to_date("1234-2234", "yyyy-yyyy") は 1234-01-01 00:00:00 を返します。
  format は、さまざまな日付コンポーネントで構成されます。yyyy は 4 桁の年を示します。mm は 2 桁の月を示します。dd は 2 桁の日を示します。hh は 24 時間制に基づく時間を示します。mi は 2 桁の分を示します。ss は 2 桁の秒を示します。ff3 は 3 桁のミリ秒を示します。
戻り値
DATETIME 型の値が返されます。戻り値は yyyy-mm-dd hh:mi:ss 形式です。入力パラメーターが NULL に設定されている場合、NULL が返されます。

例

-- 戻り値は 2010-12-03 00:00:00 です。
    to_date('Test 2010-12*03', 'Test yyyy-mm*dd');

-- 戻り値は 2008-07-18 00:00:00 です。
    to_date('20080718', 'yyyymmdd');

-- 戻り値は 2008-07-18 20:30:00 です。
    to_date('200807182030','yyyymmddhhmi');

-- '2008718' は標準の日付値に変換できず、エラーが返されます。値は '20080718' として記述する必要があります。
    to_date('2008718', 'yyyymmdd');

-- 'Test2010-12*3' は標準の日付値に変換できず、エラーが返されます。値は 'Test 2010-12*03' として指定する必要があります。
    to_date('Test 2010-12*3', 'Test yyyy-mm*dd');

--'2010-24-01' は標準の日付値に変換できず、エラーが返されます。値は '2010-01-24' として指定する必要があります。
    to_date('2010-24-01', 'yyyy');

-- 戻り値は 2018-10-30 15:13:12 です。
    to_date('20181030 15-13-12.345','yyyymmdd hh-mi-ss.ff3');

TO_CHAR

構文

string to_char(datetime <date>, string <format>)

説明
DATETIME 型の date 値を、指定された format の文字列に変換します。
パラメーター
- date: 必須。DATETIME 型の日付値。このパラメーターは、変換する日付値を指定します。入力値が STRING 型の場合、計算前に値は暗黙的に DATETIME 型の値に変換されます。入力値が別のデータ型の場合、エラーが返されます。
- format: 必須。STRING 型の定数。このパラメーターは、日付形式を指定します。値が定数でない場合、または STRING 型でない場合、エラーが返されます。format パラメーターでは、日付形式部分は関連データに置き換えられ、他の文字は出力で変更されません。
戻り値
STRING 型の値が返されます。入力パラメーターが NULL に設定されている場合、NULL が返されます。

例

-- 戻り値は 20080718 です。
    to_char(datetime'2008-07-18 00:00:00', 'yyyymmdd');

--'Test 2010-12*3' は標準の日付値に変換できず、エラーが返されます。値は 'Test 2010-12*03' として指定する必要があります。
    to_char(datetime'Test 2010-12*3', 'Test yyyy-mm*dd');

-- '2010-24-01' は標準の日付値に変換できず、エラーが返されます。値は '2010-01-24' として指定する必要があります。
    to_char(datetime'2010-24-01', 'yyyy');

-- '2008718' は標準の日付値に変換できず、エラーが返されます。値は '20080718' として指定する必要があります。
    to_char(datetime'2008718', 'yyyymmdd');

UNIX_TIMESTAMP

構文
```
bigint unix_timestamp(datetime <date>)
```
説明
date 値を整数である UNIX タイムスタンプに変換します。
パラメーター
date: 必須。DATETIME 型の値。入力値が STRING 型の場合、計算前に値は暗黙的に DATETIME 型の値に変換されます。入力値が別のデータ型の場合、エラーが返されます。新しいデータ型を有効にすると、暗黙的な変換は失敗します。この場合、CAST 関数を呼び出してデータ型を変換する必要があります。例: unix_timestamp(cast(... as datetime))。
戻り値
BIGINT 型の UNIX タイムスタンプが返されます。入力パラメーターが NULL の場合、NULL が返されます。

例

-- 戻り値は 1237518660 です。
    unix_timestamp(datetime'2009-03-20 11:11:00');

LAST_DAY

構文
```
string last_day(string <date>)
```
説明
日付値が属する月の最終日を返します。
パラメーター
date: 必須。STRING 型の値。日付値の形式には、少なくとも yyyy-mm-dd が含まれている必要があります。それ以外の場合、NULL が返されます。
戻り値
STRING 型の値が返されます。戻り値は yyyy-mm-dd 形式です。

例

-- 戻り値は 2017-03-31 です。
    last_day('2017-03-04');

-- 戻り値は 2017-07-31 です。
    last_day('2017-07-04 11:40:00');

-- 戻り値は NULL です。
    last_day('20170304');

STRING 型と DATETIME 型の間の変換

STRING 型と DATETIME 型の間で変換を実行する場合、yyyy-mm-dd hh:mi:ss 形式が使用されます。

時間単位	文字列 (大文字と小文字は区別されません)	有効な値
年	yyyy	0001 ～ 9999
月	mm	01 ～ 12
日	dd	01 ～ 28\|29\|30\|31
時	hh	00 ～ 23
分	mi	00 ～ 59
秒	ss	00 ～ 59

説明

各時間単位の値の範囲の最初の桁が 0 の場合、0 を省略することはできません。たとえば、2014-1-9 12:12:12 は無効な DATETIME 形式であり、STRING 型から DATETIME 型に変換できません。2014-01-09 12:12:12 と記述する必要があります。
上記の形式要件を満たす STRING 型のみを DATETIME 型に変換できます。たとえば、CAST("2013-12-31 02:34:34" AS DATETIME) は、STRING 型の 2013-12-31 02:34:34 を DATETIME 型に変換します。同様に、DATETIME 型の値を STRING 型の値に変換する場合、変換後の値は自動的に yyyy-mm-dd hh:mi:ss 形式で表されます。