$dateAdd (日付への加算)
最終更新：2026-10-09
$dateAdd (日付への加算)
$dateAdd は日付に指定した時間単位の量を加算し、新しい日付を返します。パイプライン内で期限日、更新日、締め切りなど相対日付を求める定番の演算子です。unit には year、month、week、day、hour、minute、second、millisecond を指定でき、amount は負の値も可能で、その場合は減算と同等になります。timezone を指定すると、そのタイムゾーンの暦に基づいて計算され、月や年の境界を正確に扱えます。$project、$addFields、$set やネストした式の中で使えます。
| カテゴリ | 日付 |
|---|---|
| MongoDB バージョン | 5.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $dateAdd: { startDate: <date-expression>, unit: <unit>, amount: <number>, timezone: <timezone> } }⚙️ パラメータ
| startDate | 変更する日付。Date、timestamp、または日付に解決される式。 |
|---|---|
| unit | 単位: year、month、week、day、hour、minute、second、または millisecond。 |
| amount | 加算する量。正は加算、負は減算。64 ビット整数の範囲を超えると例外を送出します。 |
| timezone | 計算に使用する任意のタイムゾーン。IANA 名（例: Asia/Shanghai）または UTC オフセット。 |
戻り値：新しい日付（BSON Date）。startDate が null または欠落している場合は null。
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $dateAdd: 期限日は作成から 30 日後（北京時間）
db.orders.aggregate([
{ $project: {
dueDate: { $dateAdd: { startDate: '$createdAt', unit: 'day', amount: 30, timezone: 'Asia/Shanghai' } }
} }
])出力：
{ "_id": 1, "dueDate": ISODate("2026-10-25T00:00:00Z") }
{ "_id": 2, "dueDate": ISODate("2026-11-15T00:00:00Z") }📌 注意事項
- 対応する単位は上記 8 種類のみ。amount が int64 の範囲を超えるとエラーになる
- startDate が null・欠落だと null になる（$ifNull で保護）
- 月の加算は結果の月の日数に切り詰められる（1 月 31 日 + 1 か月 = 2 月の末日）
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q$dateAdd で複数の単位を同時に加算できますか？
A1 回の呼び出しで 1 単位のみです。複数の単位を加えるには呼び出しをネストするか、$dateAdd を複数つなげます。
Qamount は負の値をサポートしていますか？
Aはい。負の値は減算になります。$dateSubtract を使っても構いません。
Qタイムゾーンはどう指定しますか？
AAsia/Shanghai のような IANA 名か、+08:00 のようなオフセットを使います。既定は UTC です。
