TIMESTAMPDIFF (SQL)

指定された日付部分における 2 つのタイムスタンプ間の差異を示す整数値を返すスカラ日付/時刻関数です。

Synopsis

{fn TIMESTAMPDIFF(interval,startDate,endDate)}

概要

{fn TIMESTAMPDIFF(interval,startDate,endDate)} は、指定された日付部分の間隔 (秒、日、週など) における開始タイムスタンプと終了タイムスタンプとの差異 (startDate - endDate) を返します。この関数は、2 つのタイムスタンプ間の間隔数を表す INTEGER 値を返します。endDate が startDate より前の場合、TIMESTAMPDIFF は負の INTEGER 値を返します。
以下の文は、後者のタイムスタンプが、前者のタイムスタンプよりも 12 日大きいので、12 を返します。どちらのタイムスタンプも既定時刻は 00:00:00 です。
```
SELECT {fn TIMESTAMPDIFF(SQL_TSI_DAY,'2022-4-1','2022-4-13')}
```
例：タイムスタンプ間の差異の計算

引数

interval

返されるタイムスタンプの差異が表す時刻間隔または日付間隔のタイプ。以下のいずれかのタイムスタンプ間隔として指定します。

SQL_TSI_FRAC_SECOND — 秒の小数部で表した間隔
SQL_TSI_SECOND — 秒で表した間隔
SQL_TSI_MINUTE — 分で表した間隔
SQL_TSI_HOUR — 時間で表した間隔
SQL_TSI_DAY — 日で表した間隔
SQL_TSI_WEEK — 週で表した間隔
SQL_TSI_MONTH — 月で表した間隔
SQL_TSI_YEAR — 年で表した間隔

startDate、endDate

比較する開始日と終了日を表すタイムスタンプ値の式。以下のいずれかの値として指定します。

%Library.TimeStampOpens in a new tab データ型形式 (yyyy-mm-dd hh:mm:ss.ffff)
%Library.PosixTimeOpens in a new tab データ型形式 (エンコードされた 64 ビットの符号付き整数)

これらのタイムスタンプ間隔は、引用符なしで、または一重引用符か二重引用符で囲んで指定できます。大文字と小文字は区別されません。

startDate または endDate のいずれかで %Library.TimeStampOpens in a new tab 形式を使用する場合、以下のルールが適用されます。

一方のタイムスタンプ式で時刻値のみが指定されており、interval で日付間隔 (日、週、月、または年) が指定されている場合、結果の間隔数の計算前に、タイムスタンプの欠けている日付部分は、既定で '1900–01–01' になります。
一方のタイムスタンプ式で日付値のみが指定されており、interval で時刻間隔 (時、分、秒、秒の小数部) が指定されている場合、結果の間隔数の計算前に、タイムスタンプの欠けている時刻部分は、既定で '00:00:00.000' になります。
任意の桁数の精度の秒の小数部を含めることができます。省略してもかまいません。SQL_TSI_FRAC_SECOND は、秒の小数部の差異を 1000 分の 1 秒 (3 桁の精度) 単位の整数として返します。%Library.PosixTimeOpens in a new tab 値には、常に 6 桁の精度が含まれます。

例

タイムスタンプ間の差異の計算

以下の文は、後者のタイムスタンプ (2021/12/20 12:00:00) が、前者のタイムスタンプよりも 7 か月分大きいので、7 を返します。

SELECT {fn TIMESTAMPDIFF(SQL_TSI_MONTH,
     '2021-5-19 00:00:00','2021-12-20 12:00:00')}

以下の文は、後者のタイムスタンプ (12:00:00) が、前者のタイムスタンプ (02:34:12) よりも 566 分大きいので、566 を返します。

SELECT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,'02:34:12','12:00:00')}

以下の文は、後者のタイムスタンプが前者のタイムスタンプよりも値が 1 日 (1440 分) 小さいので -1440 を返します。

SELECT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,'2021-12-06','2021-12-05')}

制約

TIMESTAMPDIFF は、ODBC スカラ関数としてのみ使用できます。そのため、{ } 括弧構文が必要です。タイムスタンプに対して同様の日時比較演算を実行するには、DATEDIFF 関数を使用します。

詳細

範囲と値のチェック

差異の計算を実行する前に、TIMESTAMPDIFF は入力値に対して以下のチェックを実行します。

startDate および endDate の指定された部分がすべて有効である。時刻値は、全体または一部を省略できます。startDate または endDate で不完全な時刻が指定されている場合、TIMESTAMPDIFF は、指定されていない部分に 0 を指定します。
日付文字列が完全であると同時に、要素数、各要素の桁数、および該当する区切り文字に適切な形式が使用されている。年は 4 桁で指定される必要があります。無効な日付値を指定すると、SQLCODE -8 エラーになります。
日付値が有効な範囲内にある。年は 0001 から 9999、月は 1 から 12、日は 1 から 31、時間は 00 から 23、分は 0 から 59、秒は 0 から 59 がそれぞれ有効範囲です。月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02-29' が有効なのは、指定された年がうるう年の場合のみです。無効な日付値を指定すると、SQLCODE -8 エラーになります。
日付値にキャノニック形式の整数値のみが含まれている。例外：月または日の値が 10 (10 月または 10 日) 未満の場合、先頭に 0 を含めることができます。したがって、07 または 7 は有効な日の値ですが、007、7.0、または 7a は無効です。
10 未満の時間値の先頭に 0 が含まれている。この先頭の 0 を省略すると、SQLCODE -8 エラーになります。