2 つのタイムスタンプ間の間隔を指定されたタイプの整数値で返す、スカラ数値関数です。
Synopsis
{fn TIMESTAMPDIFF(interval-type,startdate,enddate)}
TIMESTAMPDIFF 関数は、指定された間隔 (秒、日、週など) に対して、与えられた 2 つのタイムスタンプの差を返します (つまり、一方のタイムスタンプからもう一方を引きます)。返される値は、2 つのタイムスタンプ間の間隔数を示す INTEGER です (
enddate が
startdate より前の場合、
TIMESTAMPDIFF は負の INTEGER 値を返します)。1000 分の 1 秒 (0.001) でカウントして、小秒数の間隔を返すことができます。
タイムスタンプ・パラメータ値には、同じ論理形式と外部形式があります。文字列の形式は 'yyyy-mm-dd hh:mm:ss' です。
-
一方のタイムスタンプ式が TIME 値で、
interval-type が日付 (日、週、月、年) を指定する場合、式の日付部分は、結果のタイムスタンプが計算される前は '1900–01–01' に設定されます。
-
一方のタイムスタンプ式が DATE 値で、
interval-type が時刻 (秒、分、時) を指定する場合、式の時刻の部分は結果のタイムスタンプが計算される前は '00:00:00' に設定されます。
-
TIMESTAMPDIFF は { } 括弧構文による ODBC スカラ関数としてのみ使用できる点に注意してください。同様の日付/時刻の比較の演算は、
DATEDIFF 汎用関数を使用して、タイムスタンプで実行できます。
TIMESTAMPDIFF は、入力値に対して以下のチェックを実行します。値がチェックに失敗した場合は、NULL 文字列が返されます。
-
有効な
startdate または
enddate は、日付文字列 (yyyy-mm-dd)、時刻文字列 (hh:mm:ss)、または日付/時刻文字列 (yyyy-mm-dd hh:mm:ss) で構成されます。日付と時刻の両方が指定されている場合は、両方が有効でなければなりません。例えば、時刻文字列が指定されていない場合は年数値を返すことができますが、無効な時刻文字列が指定されている場合は年数値を返すことができません。
-
日付文字列は完全であると同時に、要素数、各要素の桁数、および区切り文字に適切な形式が使用されている必要があります。例えば、日の値が省略されている場合、年数値を返すことはできません。年は 4 桁で指定される必要があります。入力値の日付部分を省略した場合、
TIMESTAMPDIFF は既定で '1900–01–01' になります。
-
時刻文字列は、適切な区切り文字で適切にフォーマットされている必要があります。時刻要素の値はゼロの場合もあるため、1 つ以上の時刻要素を省略でき (区切り文字はそのまま残す場合と省略する場合がある)、これらの要素はゼロ値として返されます。したがって、'hh:mm:ss.nnn'、'hh:mm:ss'、'hh:mm:'、'hh:mm'、'hh::ss'、'hh::'、'hh'、':::' は、すべて有効です。時間 (Hour) 要素を省略するには、日付式に文字列の日付部分がないことと、少なくとも 1 つの区切り文字 (:) があることが必要です。
-
日付/時刻値は、有効な範囲内にある必要があります。年は 1841 から 9999、月は 1 から 12、日は 1 から 31、時間は 0 から 23、分は 0 から 59、秒は 0 から 59 がそれぞれ有効範囲です。
-
月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02–29' が有効なのは、指定された年がうるう年の場合のみです。
-
日付値または時刻値が 10 よりも小さい場合、そのほとんどの先頭のゼロは、記載、省略のどちらでもかまいません。ただし、10 よりも小さい時間 (Hour) 値が日付/時刻文字列の一部の場合は、その先頭にゼロを付ける必要があります。その他の非標準的な整数値は許可されません。例えば、'07' または '7' は有効な日値ですが、'007'、'7.0'、または '7a' は無効です。
以下の例は、後者のタイムスタンプ (1999-12-20 12:00:00) が、前者のタイムスタンプよりも 7 か月分大きいので、7 を返します。
SELECT DISTINCT {fn TIMESTAMPDIFF(SQL_TSI_MONTH,
'1999-5-19 00:00:00','1999-12-20 12:00:00')}
FROM Sample.Person
以下の例は、後者のタイムスタンプ ('12:00:00') が、前者のタイムスタンプ (02:34:12) よりも 566 分大きいので、566 を返します。
SELECT DISTINCT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,
'02:34:12','12:00:00')}
FROM Sample.Person