$dateDiff (日付の差)
最終更新：2026-10-09
$dateDiff (日付の差)
$dateDiff は 2 つの日付の差を指定した単位の整数で計算します。年齢、契約期間、滞在時間などの計算に最適です。unit には year、month、week、day、hour、minute、second、millisecond を指定でき、結果は単位の境界で切り捨てられます（year は満年数のみを数えます）。startOfWeek は週の開始曜日を設定し、unit が week のときだけ適用されます。timezone は使用する暦を決定し、タイムゾーンをまたぐ場合は必ず設定してください。
| カテゴリ | 日付 |
|---|---|
| MongoDB バージョン | 5.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $dateDiff: { startDate: <date-expression>, endDate: <date-expression>, unit: <unit>, timezone: <timezone>, startOfWeek: <week-start> } }⚙️ パラメータ
| startDate / endDate | 必須。開始日と終了日。 |
|---|---|
| unit | 必須。差の単位（上記8つの単位）。 |
| timezone | 計算に使用する任意のタイムゾーン。 |
| startOfWeek | 任意。unit が week の場合のみ適用。Monday、Sunday などの値。 |
戻り値：整数の差（endDate から startDate を減算）。いずれかの日付が null の場合は null。
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $dateDiff: 年齢を年単位で計算
db.users.aggregate([
{ $project: {
ageYears: { $dateDiff: { startDate: '$birthDate', endDate: '$$NOW', unit: 'year' } }
} }
])出力：
{ "_id": 1, "ageYears": 28 }
{ "_id": 2, "ageYears": 31 }📌 注意事項
- 結果は endDate から startDate を引いた値で、負になることもある
- 大きい単位は完了した境界で切り捨てられる。year は満年のみを数える
- startOfWeek は unit が week のときだけ有効。値は Monday から Sunday
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q結果に小数は含まれますか？
Aいいえ。$dateDiff は整数を返し、単位の境界で切り捨てられます。
Q差は負になりますか？
Aはい。endDate が startDate より前だと負になります。
Q2 つの日付の間の日数を数えるには？
Aunit を day に設定します。タイムゾーンによって暦上の日の境界が変わる点に注意してください。
