指定されたタイムスタンプに、特定タイプの間隔の数を加えることで計算された、新しいタイムスタンプを返すスカラ数値関数です。
Synopsis
{fn TIMESTAMPADD(interval-type,integer-exp,timestamp-exp)}
同様の日付/時刻変更の演算は、
DATEADD 汎用関数を使用して、タイムスタンプで実行できます。
タイムスタンプ間隔をインクリメントまたはディクリメントすると、他の間隔も適切に変更されます。例えば、時間のインクリメント結果が午前 0 時を超える場合、自動的に日がインクリメントされます。同様に、順次、月などがインクリメントされます。
TIMESTAMPADD は、各月の日数やうるう年を考慮に入れて、常に有効な日付を返します。例えば、1 月 31 日に 1 か月をインクリメントすると 2 月 28 日 (該当月の有効な最終日付) が返されますが、指定された年がうるう年の場合は 2 月 29 日が返されます。
TIMESTAMPADD は、入力値に対して以下のチェックを実行します。値がチェックに失敗した場合は、NULL 文字列が返されます。
-
日付文字列は完全であると同時に、要素数、各要素の桁数、および区切り文字に適切な形式が使用されている必要があります。年は 4 桁で指定される必要があります。
-
日付値は、有効な範囲内にある必要があります。年は 1841 から 9999、月は 1 から 12、日は 1 から 31、時間は 0 から 23、分は 0 から 59、秒は 0 から 59 がそれぞれ有効範囲です。
-
インクリメント結果として返される年は、1841 から 9999 までの範囲内にある必要があります。この範囲を超えると、<null> が返されます。
-
月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02–29' が有効なのは、指定された年がうるう年の場合のみです。
-
10 よりも小さい日付値の先頭のゼロは、記載、省略のどちらでもかまいません。その他の非標準的な整数値は許可されません。例えば、'07' または '7' は有効な日値ですが、'007'、'7.0'、または '7a' は無効です。
以下の例は、元のタイムスタンプに 1 週間を加算します。
SELECT DISTINCT {fn TIMESTAMPADD(SQL_TSI_WEEK,1,'2003-12-20 12:00:00')}
FROM Sample.Person
1 週の加算は 7 日の加算になるので、上記の例は 2003-12-27 12:00:00 を返します。
以下の例は、元のタイムスタンプに 5 か月を加算します。
SELECT DISTINCT {fn TIMESTAMPADD(SQL_TSI_MONTH,5,'1999-12-20 12:00:00')}
FROM Sample.Person
この例は 5 か月を加算すると年がインクリメントされるので、2000-05-20 12:00:00 を返します。
以下の例も、元のタイムスタンプに 5 か月を加算します。
SELECT DISTINCT {fn TIMESTAMPADD(SQL_TSI_MONTH,5,'1999-01-31 12:00:00')}
FROM Sample.Person
上記の例は 1999-06-30 12:00:00 を返します。この
TIMESTAMPADD は、月だけでなく日の値も変更します。これは単純に月をインクリメントすると、無効な日付の 6 月 31 日となるためです。
以下の例は、元のタイムスタンプに 45 分をインクリメントします。
SELECT DISTINCT {fn TIMESTAMPADD(SQL_TSI_MINUTE,45,'1999-12-20 00:00:00')}
FROM Sample.Person
上記の例は 1999-12-20 00:45:00 を返します。
以下の例は、元のタイムスタンプに 45 分をディクリメントします。
SELECT DISTINCT {fn TIMESTAMPADD(SQL_TSI_MINUTE,-45,'1999-12-20 00:00:00')}
FROM Sample.Person
上記の例は 1999-12-19 23:15:00 を返します。この場合、時刻をディクリメントすると、日もディクリメントされる点に注意してください。