$dateDiff (aggregation operator)（聚合运算符）

No Fractional Units无分数单位

The $dateDiff expression returns the integer difference between the startDate and endDate measured in the specified units. Durations are measured by counting the number of times a unit boundary is passed. For example, two dates that are 18 months apart would return 1 year difference instead of 1.5 years.$dateDiff表达式返回以指定units测量的startDate和endDate之间的整数差。通过计算通过单位边界的次数来测量持续时间。例如，相隔18个月的两个日期将返回1年的差值，而不是1.5年。

Start Of Week本周开始

The start of the week is Sunday unless modified by the startOfWeek parameter. 除非被startOfWeek参数修改，否则一周的开始是Sunday。Any week that begins between the startDate and endDate on the specified day will be counted. The week count is not bounded by calendar month or calendar year.从指定日期的startDate和endDate之间开始的任何一周都将被计算在内。周计数不受日历月或日历年的限制。

Time Zone时区

When using an Olson Timezone Identifier in the <timezone> field, MongoDB applies the DST offset if applicable for the specified timezone.在<Timezone>字段中使用Olson时区标识符时，MongoDB会应用DST偏移（如果适用于指定的时区）。

For example, consider a sales collection with the following document:例如，考虑具有以下文档的sales集合：

 db.sales.insertOne(
  {
   "_id" : 1,
   "item" : "abc",
   "price" : 10,
   "quantity" : 2,
   "date" : ISODate("2014-01-01T08:15:39.736Z")
  }
)

The following aggregation illustrates how MongoDB handles the DST offset for the Olson Timezone Identifier. 以下聚合说明了MongoDB如何处理Olson时区标识符的DST偏移。The example uses the $hour and $minute operators to return the corresponding portions of the date field:该示例使用$hour和$minute运算符返回日期字段的相应部分：

db.sales.aggregate([
{
   $project: {
      "nycHour": {
         $hour: { date: "$date", timezone: "-05:00" }
       },
       "nycMinute": {
          $minute: { date: "$date", timezone: "-05:00" }
       },
       "gmtHour": {
          $hour: { date: "$date", timezone: "GMT" }
       },
       "gmtMinute": {
          $minute: { date: "$date", timezone: "GMT" } },
       "nycOlsonHour": {
          $hour: { date: "$date", timezone: "America/New_York" }
       },
       "nycOlsonMinute": {
          $minute: { date: "$date", timezone: "America/New_York" }
       }
   }
}])

The operation returns the following result:该操作返回以下结果：

{
   "_id": 1,
   "nycHour" : 5,
   "nycMinute" : 24,
   "gmtHour" : 10,
   "gmtMinute" : 24,
   "nycOlsonHour" : 6,
   "nycOlsonMinute" : 24
}

Additional Details附加细节

The algorithm calculates the date difference using the Gregorian calendar.该算法使用公历计算日期差。

Leap years and daylight savings time are accounted for but not leap seconds.闰年和夏令时被考虑在内，但不包括闰秒。

The difference returned can be negative.返回的差值可能为负数。

Elapsed Time已用时间

Create a collection of customer orders:创建客户orders集合：

db.orders.insertMany(
   [
      {
         custId: 456,
         purchased: ISODate("2020-12-31"),
         delivered: ISODate("2021-01-05")
      },
      {
         custId: 457,
         purchased: ISODate("2021-02-28"),
         delivered: ISODate("2021-03-07")
      },
      {
         custId: 458,
         purchased: ISODate("2021-02-16"),
         delivered: ISODate("2021-02-18")
      }
   ]
)

The following example:以下示例：

• Returns the average number of days for a delivery.返回交货的平均天数。
• Uses dateDiff to calculate the difference between the purchased date and the delivered date.使用dateDiff计算purchased（购买）日期和delivered（交付）日期之间的差异。

 db.orders.aggregate(
    [
       {
          $group:
             {
                 _id: null,
                 averageTime:
                    {
                       $avg:
                          {
                             $dateDiff:
                                {
                                    startDate: "$purchased",
                                    endDate: "$delivered",
                                    unit: "day"
                                }
                           }
                    }
             }
       },
       {
          $project:
             {
                _id: 0,
                numDays:
                   {
                      $trunc:
                         [ "$averageTime", 1 ]
                   }
             }
        }
    ]
)

The $avg accumulator in the $group stage uses $dateDiff on each document to get the time between the purchased and delivered dates. The resulting value is returned as averageTime.$group阶段中的$avg累加器在每个文档上使用$dateDiff来获取购买日期和交付日期之间的时间。结果值作为averageTime返回。

The decimal portion of the averageTime is truncated ($trunc) in the $project stage to produce output like this:在$project阶段，averageTime的小数部分被截断（$trunc），以产生如下输出：

{ "numDays" : 4.6 }

Result Precision结果精度

Create this collection with starting and ending dates for a subscription.使用订阅的开始和结束日期创建此集合。

db.subscriptions.insertMany(
   [
      {
         custId: 456,
         start: ISODate("2010-01-01"),
         end: ISODate("2011-01-01")
      },
      {
         custId: 457,
         start: ISODate("2010-01-01"),
         end: ISODate("2011-06-31")
      },
      {
         custId: 458,
         start: ISODate("2010-03-01"),
         end: ISODate("2010-04-30")
      }
   ]
)

The $dateDiff expression returns a time difference expressed in integer units. There are no fractional parts of a unit. For example, when counting in years there are no half years.$dateDiff表达式返回以整数units表示的时间差。一个单位没有分数部分。例如，在计算年份时，没有半年。

In this example, note how changing the unit changes the returned precision:在此示例中，请注意更改unit会如何更改返回的精度：

db.subscriptions.aggregate(
   [
      {
         $project:
            {
               Start: "$start",
               End: "$end",
               years:
                  {
                     $dateDiff:
                        {
                           startDate: "$start",
                           endDate: "$end",
                           unit: "year"
                        }
                  },
               months:
                  {
                     $dateDiff:
                        {
                           startDate: "$start",
                           endDate: "$end",
                           unit: "month"
                        }
                  },
               days:
                  {
                     $dateDiff:
                        {
                           startDate: "$start",
                           endDate: "$end",
                           unit: "day"
                        }
                  },
               _id: 0
            }
       }
   ]
 )

The results are summarized in this table:结果总结如下：

The count only increments when a new unit starts, so 18 months are reported as 1 year in the second row and 60 days are reported as one month in the third row.计数仅在新unit开始时递增，因此第二行将18个月报告为1年，第三行将60天报告为1个月。

Weeks Per Month每月周数

Create a collection of months:创建月份集合：

db.months.insertMany(
     [
        {
           month: "January",
           start: ISODate("2021-01-01"),
           end: ISODate("2021-01-31")
        },
        {
           month: "February",
           start: ISODate("2021-02-01"),
           end: ISODate("2021-02-28")
        },
        {
           month: "March",
           start: ISODate("2021-03-01"),
           end: ISODate("2021-03-31")
        },
     ]
   )

You can change the start of each week, and count the resulting number of weeks in each month with the following code:您可以更改每周的开始时间，并使用以下代码计算每月的周数：

db.months.aggregate(
   [
      {
         $project:
            {
               wks_default:
                  {
                     $dateDiff:
                        {
                           startDate: "$start",
                           endDate: "$end",
                           unit: "week"
                        }
                  },
               wks_monday:
                  {
                     $dateDiff:
                        {
                           startDate: "$start",
                           endDate: "$end",
                           unit: "week",
                           startOfWeek: "Monday"
                        }
                  },
               wks_friday:
                  {
                     $dateDiff:
                        {
                           startDate: "$start",
                           endDate: "$end",
                           unit: "week",
                           startOfWeek: "fri"
                        }
                  },
               _id: 0
            }
       }
   ]
 )

The results are summarized in this table:结果总结如下：

From the results:从结果来看：

• When the startOfWeek is Sunday, the 5th week in January, 2021 begins on the 31st.当startOfWeek是星期日时，2021年1月的第五周从31日开始。
• Because the 31st is a Sunday and it is between startDate and endDate, one week is added to the count.因为第31天是星期日，并且在startDate和endDate之间，所以计数中会增加一周。
• The week count is incremented even when a calendar week finishes after endDate or in the next calendar period.即使日历周在endDate之后或下一个日历期间结束，周计数也会递增。