TIMESTAMPDIFF

TIMESTAMPDIFF 関数は、2 つのタイム・スタンプの差に基づいて、最初の引数によって定義されたタイプの間隔の見積数を戻します。


>>-TIMESTAMPDIFF--(--numeric-expression--,--string-expression--)-><

numeric-expression

最初の引数は、INTEGER または SMALLINT のいずれかの組み込みデータ・タイプでなければなりません。この値は、2 つのタイム・スタンプの間の差を判別するのに使用する間隔を指定します。間隔の有効な値は、以下のとおりです。

表 1. 2 つのタイム・スタンプの間の差を判別するのに使用する numeric-expression およびそれに相当する間隔に対する有効値
numeric-expression に対する有効値	相当する間隔
1	マイクロ秒
2	秒
4	分
8	時間
16	日
32	週
64	月
128	四半期
256	年

string-expression

ストリング式は、2 つのタイム・スタンプを減算し、その結果を長さ 22 のストリングに変換したものです。 string-expression の小数点の右側が 6 桁を超える場合、ストリングは 6 桁になるよう切り捨てられます。引数は、組み込み文字ストリングまたはグラフィック・ストリングの値を戻す式でなければなりません。

正または負の符号が付いている場合、それがそのストリングの最初の文字になります。下表は、文字ストリングによる期間を表すエレメントを説明しています。

表 2. TIMESTAMPDIFF ストリング・エレメント
ストリング・エレメント	有効値	小数点からの文字位置 (負は左方向)
年	1 から 9998 またはブランク	-14 から -11
月	0 から 11 またはブランク	-10 から -9
日	0 から 30 またはブランク	-8 から -7
時間	0 から 24 またはブランク	-6 から -5
分	0 から 59 またはブランク	-4 から -3
秒	0 から 59	-2 から -1
小数点	ピリオド	0
マイクロ秒	000000 から 999999	1 から 6

この関数の結果は、string-expression と同じ符号の整数になります。引数のどちらかが NULL になる可能性がある場合は、結果も NULL になる可能性があります。引数のどちらかが NULL である場合は、結果は NULL 値になります。

戻り値は、それぞれの間隔に関して以下の表に示されているように決定されます。

表 3. TIMESTAMPDIFF の計算方法
結果の間隔	期間エレメントを使用した計算
年	年
四半期	(月 + (年 *12))/3 の整数値部分
月	月 + (年 *12)
週	((日 + (月 30))/7) + (年 52) の整数値部分
日	日 + (月 30) + (年 365)
時間	時間 + ((日 + (月 30) + (年 365))*24)
分 (期間の絶対値が 40850913020759.999999 を超えることはできません)	分 + (時間 + ((日 + (月 30) + (年 365))24))60
秒 (期間の絶対値が 680105031408.000000 より小さくなければなりません)	秒 + (分 + (時間 + ((日 + (月 30) + (年 365))24))60 )*60
マイクロ秒 (期間の絶対値が 3547.483648 より小さくなければなりません)	マイクロ秒 + (秒 + (分 60))1000000

エレメント値を、要求された間隔タイプに変換する際、以下の前提事項が使用されます。

1 年は 365 日。
1 年は 52 週。
1 年は 12 カ月。
四半期は 3 カ月。
1 カ月は 30 日。
1 週は 7 日。
1 日は 24 時間。
1 時間は 60 分。
1 分は 60 秒。
1 秒は 1000000 マイクロ秒。

こうした前提事項を使用することにより、結果値の中には間隔が概数になる場合があります。以下の例について考えてみます。

1 カ月が 30 日に満たない場合の差。
```
TIMESTAMPDIFF(16, CHAR(TIMESTAMP('1997-03-01-00.00.00') - TIMESTAMP('1997-02-01-00.00.00') ) )
```
このタイム・スタンプ算術計算の結果は、期間 00000100000000.000000、つまり 1 カ月になります。TIMESTAMPDIFF 関数が間隔引数 16 (日) で呼び出されると、1 カ月は 30 日であるという前提が適用されて、結果は 30 になります。
30 日に満たない月の場合における、1 カ月より 1 日短いときの差。
```
TIMESTAMPDIFF(16, CHAR(TIMESTAMP('1997-03-01-00.00.00') - TIMESTAMP('1997-02-02-00.00.00') ) )
```
このタイム・スタンプ算術計算の結果は、期間 00000027000000.000000、つまり 27 日になります。TIMESTAMPDIFF 関数が間隔引数 16 (日) で呼び出されると、結果は 27 になります。
31 日ある月の場合における、1 カ月より 1 日短いときの差。
```
TIMESTAMPDIFF(64, CHAR(TIMESTAMP('1997-09-01-00.00.00') - TIMESTAMP('1997-08-02-00.00.00') ) )
```
このタイム・スタンプ算術計算の結果は、期間 00000030000000.000000、つまり 30 日になります。TIMESTAMPDIFF 関数が間隔引数 64 (月) で呼び出されると、結果は 0 になります。この期間の日部分は 30 ですが、指定された間隔が月なのでこれは無視されます。

例

以下のステートメントでは月単位で従業員の年齢を見積もり、その値を AGE_IN_MONTHS として戻します。

SELECT 
    TIMESTAMPDIFF(64,
    CAST(CURRENT_TIMESTAMP-CAST(BIRTHDATE AS TIMESTAMP) AS CHAR(22))) 
      AS AGE_IN_MONTHS
  FROM EMPLOYEE