DATEADD (SQL)

datePart

日付または時刻の部分のフルネームまたは省略した名前です。datePart は大文字でも小文字でも指定できます。埋め込み SQL では、datePart をリテラル値またはホスト変数で指定します。日付と時刻の部分の有効な名前と省略形を以下の表に示します。また、その部分の 1 単位 (numUnits = 1) による日付のインクリメント量も示します。

日付部分をインクリメントまたはデクリメントすると、他の日付部分も適切に変更されます。例えば、時間のインクリメント結果が午前 0 時を超える場合、自動的に日がインクリメントされます。同様に、順次、月などがインクリメントされます。

DATEADD の動作は、datePart の指定で引用符を使用しているかどうかによってわずかに異なります。

• 引用符を使用している場合 ： DATEADD('month',1,'2022-02-25') ： datePart がリテラルとして扱われます。クエリを処理するときにリテラル置換が実行され、文字列 'month' が入力パラメータに置き換えられます。これにより、より一般的に使用できるクエリ・キャッシュが生成されます。

• 引用符を使用していない場合 ： DATEADD(month,1,'2022-02-25') ： datePart がキーワードとして扱われます。クエリの処理ではリテラル置換が実行されません。これにより、固有性が高いクエリ・キャッシュが生成されます。

datePart に無効なリテラル値を指定すると、SQLCODE -8 エラー・コードが発生します。一方、無効な datePart 値をホスト変数として指定すると、SQLCODE エラーは発行されず、datePart を解析するために呼び出された DATEPART 関数から NULL 値が返されます。

numUnits

date に対する加算または減算に適用する datePart 単位の値です。数値で指定します。DATEADD では numUnits が整数に切り捨てられます。numUnits に数値部分がない場合、またはその先頭が数値ではない場合、DATEADD によってこの値が 0 に切り詰められ、最初に指定した date が返されます。

date

加算または減算される日付または時刻の式です。InterSystems IRIS® の以下のいずれかのデータ型で指定します。

• %Date 論理値 (+$H)。$HOROLOG 形式とも呼ばれます。

• %PosixTime (%Library.PosixTimeOpens in a new tab) 論理値 (エンコードされた 64 ビットの符号付き整数)。

• %TimeStamp (%Library.TimeStampOpens in a new tab) 論理値 (YYYY-MM-DD HH:MM:SS.FFF)。ODBC 形式とも呼ばれます。

• %String または文字列互換の値。以下のいずれかの形式とします。

  $HOROLOG の日付と時刻の形式

  形式	例
  ddddd	SELECT DATEADD('yy',1,'66716')
  ddddd,sssss	SELECT DATEADD('yy',1,'66716.256')
  ddddd,sssss.fff	SELECT DATEADD('yy',1,'66716,256.467')

  各要素の内容は以下のとおりです。

  • ddddd ： 1840 年 12 月 31 日からの経過日数 (整数値)。

  • sssss ： 指定日の開始からの経過秒数 (整数値)。

  • fff ： 秒の小数部 (整数値)。秒の小数部を指定した場合は、DATEADD の返り値にも秒の小数部が記述されます。

  日付形式

  形式	例
  MM/DD/YY	SELECT DATEADD('year',1,'12/31/99')
  MM/DD/YYYY	SELECT DATEADD('year',1,'8/24/2022')
  MM-DD-YY	SELECT DATEADD('year',1,'12-31-99')
  MM-DD-YYYY	SELECT DATEADD('year',1,'8-24-2022')
  MM.DD.YY	SELECT DATEADD('year',1,'12.31.99')
  MM.DD.YYYY	SELECT DATEADD('year',1,'8.24.2022')
  Mmm DD YY	SELECT DATEADD('year',1,'Dec 30 92')
  Mmm DD YYYY	SELECT DATEADD('year',1,'January 23 2021')
  Mmm DD, YY	SELECT DATEADD('year',1,'Dec 30, 92')
  Mmm DD, YYYY	SELECT DATEADD('year',1,'January 23, 2021')

  各要素の内容は以下のとおりです。

  • MM ： 2 桁の月。

  • DD ： 月の 2 桁の日数。

  • Mmm ： スペルアウト表記の月名。最低 3 文字 (例 ： Mar) から完全な月名 (例 ： March) まで指定できます。

  • YY は 2 桁形式、YYYY は 4 桁形式の年です。

  date は日付と時刻の文字列を組み合わせて指定できます。以下に例を示します。

  SELECT DATEADD('hh',1,'12/22/2021 8:15:23')

  

  日付を指定せずに時刻を指定すると、DATEADD では既定で日付が 01/01/1900 になりす。

  時刻形式

  形式	例
  HH:	SELECT DATEADD('hour',1,'10:')
  HH:MM	SELECT DATEADD('mi',1,'10:30')
  HH:MM:SS	SELECT DATEADD('ss',1,'10:30:59')
  HH...SS.FFF	SELECT DATEADD('ms',1,'10:30:59.245')
  HH...[AM|PM]	SELECT DATEADD('mi',1,'10:30PM')

  各要素の内容は以下のとおりです。

  • HH ： 1 日での 2 桁の時間値。

  • MM ： 1 時間での 2 桁の分の値。

  • SS ： 1 分間での 2 桁の秒の値。

  • FFF ： 秒の小数部の値。

  date は日付と時刻の文字列を組み合わせて指定できます。以下に例を示します。

  SELECT DATEADD('hh',1,'12/22/2021 8:15:23')

  

  時刻を指定せずに日付を指定すると、DATEADD では既定で時刻が 00:00:00 になります。

date 引数の制限事項と動作は以下のとおりです。

• 日付文字列は完全であると同時に、要素数、各要素の桁数、および区切り文字に適切な形式が使用されている必要があります。年は 4 桁で指定される必要があります。入力値の日付部分を省略すると、DATEADD では既定で日付が '1900-01-01' になります。

• 日付と時刻の値は、以下の有効な範囲内にあることが必要です。

  • 年 — 0001 から 9999

  • 月 — 1 から 12

  • 日 — 1 から 31

  • 時間 — 00 から 23

  • 分 — 0 から 59

  • 秒 — 0 から 59

  月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02-29' が有効なのは、指定された年がうるう年の場合のみです。

• 10 (月および日) 未満の日付値では、先頭のゼロを省略してもかまいません。その他の非標準的な整数値は許可されません。例えば、Day の値として '07' と '7' は有効ですが、'007'、'7.0'、'7a' は無効です。

• 時刻値は省略してもかまいません。date に不完全な時刻を指定すると、指定していない部分には 0 が使用されます。

• 10 よりも小さい時間値の先頭の 0 は記載する必要があります。

さまざまな時間単位の日付への加算

以下の文は、指定された日付に 1 週を加算します。1 週の加算は 7 日の加算になるので、2022-03-05 00:00:00 が返されます。DATEADD では時刻部分が省略されます。

SELECT DATEADD('week',1,'2022-02-26') AS NewDate

以下の文は、指定されたタイムスタンプに 5 か月を加算し、2022-04-26 12:00:00 を返します。5 か月を加算すると年もインクリメントされるので、DATEADD では月と年の両方が変更されます。

SELECT DATEADD(MM,5,'2021-11-26 12:00:00') AS NewDate

以下の文も、タイムスタンプに 5 か月を加算し、2021-06-30 12:00:00 を返します。月のみをインクリメントすると無効な日付である 6 月 31 日になるので、DATEADD では日と月の両方が変更されます。

SELECT DATEADD('mm',5,'2021-01-31 12:00:00') AS NewDate

以下の文は、タイムスタンプに 45 分を加算し、2022-02-26 12:45:00 を返します。

SELECT DATEADD(MI,45,'2022-02-26 12:00:00') AS NewTime

以下の文も、タイムスタンプに 45 分を加算しますが、この場合は日がインクリメントされ、さらに月もインクリメントされます。その結果、2022-03-01 00:15:00 が返されます。

SELECT DATEADD('mi',45,'2022-02-28 23:30:00') AS NewTime

以下の文は元のタイムスタンプを 45 分デクリメントし、2021-12-31 23:25:00 を返します。

SELECT DATEADD(N,-45,'2022-01-01 00:10:00') AS NewTime

以下の文は、現在の日付に 60 日を加算し、各月の総日数に合わせて結果を調整します。

SELECT DATEADD(D,60,CURRENT_DATE) AS NewDate

以下の文で最初の DATEADD は、指定された日に 92 日を加算し、2022-03-22 00:00:00 を返します。2 番目の DATEADD は、指定された日付に 1 四半期を加算し、2022-03-20 00:00:00 を返します。四半期のインクリメントを実行すると、月フィールドが 3 インクリメントされます。必要に応じて、DATEADD は年フィールドもインクリメントし、指定された月の総日数に合わせて結果を調整します。

SELECT DATEADD('dd',92,'2021-12-20') AS NewDateD,
       DATEADD('qq',1,'2021-12-20') AS NewDateQ

上記の文はすべて日付部分に省略形を使用していますが、完全な名前で指定することもできます。例えば、以下の文は日付に 92 日を加算し、2022-03-22 00:00:00 を返します。

SELECT DATEADD('day',92,'2021-12-20') AS NewDate

以下の埋め込み SQL コードは、ホスト変数を使用して前述の SQL 文と同じ DATEADD 処理を実行します。

  set datePart = "day"
  set numUnits = 92
  set dateIn = "2021-12-20"

  &sql(SELECT DATEADD(:datePart,:numUnits,:dateIn) INTO :dateOut)

  write "in: ",dateIn,!,"out: ",dateOut