$dateSubtract (日付からの減算)
最終更新：2026-10-09
$dateSubtract (日付からの減算)
$dateSubtract は日付から指定した時間単位の量を減算し、新しい日付を返します。$dateAdd の鏡像にあたる演算子です。会員の有効期限、クーポンの開始日、リテンション期間の計算に最適です。unit には year、month、week、day、hour、minute、second、millisecond を指定でき、amount が負の場合は加算と同等になります。timezone は任意で、使用する暦を定義します。$dateAdd と同様に $project、$set などのステージで使えます。date が null・欠落だと null を返します。
| カテゴリ | 日付 |
|---|---|
| MongoDB バージョン | 5.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $dateSubtract: { startDate: <date-expression>, unit: <unit>, amount: <number>, timezone: <timezone> } }⚙️ パラメータ
| startDate | 減算の対象となる日付。Date、timestamp、または日付式。 |
|---|---|
| unit | 単位: year、month、week、day、hour、minute、second、または millisecond。 |
| amount | 減算する量。正は減算、負は加算。int64 の範囲を超えると例外を送出します。 |
| timezone | 計算に使用する任意のタイムゾーン。 |
戻り値：新しい日付（BSON Date）。startDate が null または欠落している場合は null。
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $dateSubtract: 期限日の 3 日前にリマインド（UTC+8）
db.orders.aggregate([
{ $project: {
remindAt: { $dateSubtract: { startDate: '$dueDate', unit: 'day', amount: 3, timezone: '+08:00' } }
} }
])出力：
{ "_id": 1, "remindAt": ISODate("2026-10-22T00:00:00Z") }
{ "_id": 2, "remindAt": ISODate("2026-11-12T00:00:00Z") }📌 注意事項
- パラメータは $dateAdd と同じで、方向だけが逆
- 月の加減算も結果の月の日数に切り詰められる
- 結果が 1970 年より前になることもある。BSON Date は負のタイムスタンプをサポート
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q$dateSubtract と $dateAdd の関係は？
Aパラメータは同じで方向が逆です。負の amount を使えば両者は同等になります。
Q結果が 1970 年より前になることはありますか？
Aはい。BSON Date は 1970 年より前の負のタイムスタンプをサポートしています。
Q$dateDiff との違いは？
A$dateSubtract は新しい日付を返します。$dateDiff は整数の差分を返します。
