Database Manual / Reference / Query Language / Expressions

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

Definition定义

$dateFromParts

Constructs and returns a Date object given the date's constituent properties.根据日期的组成属性构造并返回Date对象。

The $dateFromParts expression has the following syntax:$dateFromParts表达式具有以下语法：

{
    $dateFromParts : {
        'year': <year>, 'month': <month>, 'day': <day>,
        'hour': <hour>, 'minute': <minute>, 'second': <second>,
        'millisecond': <ms>, 'timezone': <tzExpression>
    }
}

You can also specify your constituent date fields in ISO week date format using the following syntax:您还可以使用以下语法以ISO周日期格式指定组成日期字段：

{
    $dateFromParts : {
        'isoWeekYear': <year>, 'isoWeek': <week>, 'isoDayOfWeek': <day>,
        'hour': <hour>, 'minute': <minute>, 'second': <second>,
        'millisecond': <ms>, 'timezone': <tzExpression>
    }
}

The $dateFromParts takes a document with the following fields:$dateFromParts接受具有以下字段的文档：

Important

You cannot combine the use of calendar dates and ISO week date fields when constructing your $dateFromParts input document.在构建$dateFromParts输入文档时，不能同时使用日历日期和ISO周日期字段。

Field字段Required/Optional必需/可选Description描述
yearRequired if not using isoWeekYear如果不使用isoWeekYear，则需要

Calendar year. Can be any expression that evaluates to a number.日历年。可以是任何计算结果为数字的表达式。

Value range: 取值范围：1-9999

If the number specified is outside this range, $dateFromParts errors. The lower bound for this value is 1.如果指定的数字超出此范围，$dateFromParts将出错。该值的下限为1。
isoWeekYearRequired if not using year如果不使用year，则需要

ISO Week Date Year. Can be any expression that evaluates to a number.ISO周日期年份。可以是任何计算结果为数字的表达式。

Value range: 取值范围： 1-9999

If the number specified is outside this range, $dateFromParts errors. The lower bound for this value is 1.如果指定的数字超出此范围，$dateFromParts将出错。该值的下限为1。
monthOptional. 可选。Can only be used with year.只能与year一起使用。

Month. Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 1.默认值为1。

Value range: 取值范围：1-12

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. See Value Range for examples.如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。有关示例，请参阅取值范围。
isoWeekOptional. 可选。Can only be used with isoWeekYear.只能与isoWeekYear一起使用。

Week of year. 一年中的一周。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 1.默认值为1。

Value range: 取值范围：1-53

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。
dayOptional. 可选。Can only be used with year.只能与year一起使用。

Day of month. 月份的第几天。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 1.默认值为1。

Value range: 取值范围： 1-31

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。
isoDayOfWeekOptional. 可选。Can only be used with isoWeekYear.只能与isoWeekYear一起使用。

Day of week (Monday 1 - Sunday 7). 一周中的某一天（周一1 - 周日7）。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 1.默认值为1。

Value range: 取值范围：1-7

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。
hourOptional可选

Hour. 小时。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 0.默认值为0。

Value range: 取值范围： 0-23

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。
minuteOptional可选

Minute. 分钟。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 0.默认为0。

Value range: 取值范围： 0-59 If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。

secondOptional可选

Second. 秒。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 0.默认值为0。

Value range: 取值范围：0-59

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。
millisecondOptional可选

Millisecond. 毫秒。Can be any expression that evaluates to a number.可以是任何计算结果为数字的表达式。

Defaults to 0.默认值为0。

Value range: 取值范围： 0-999

If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 如果指定的数字在此范围之外，$dateFromParts会将差异合并到日期计算中。See Value Range for examples.有关示例，请参阅取值范围。
timezoneOptional可选

<timezone> can be any expression that evaluates to a string whose value is either:可以是任何计算结果为字符串的表达式，该字符串的值为：

  • an Olson Timezone Identifier, such as "Europe/London" or "America/New_York", or奥尔森时区标识符，如"Europe/London"或"America/New_York"，或

  • a UTC offset in the form:UTC偏移量，格式为：

    • +/-[hh]:[mm], e.g. "+04:45", or，例如"+04:45"，或者
    • +/-[hh][mm], e.g. "-0530", or，例如"-0530"，或者
    • +/-[hh], e.g. "+03".，例如"+03"。

For more information on expressions, see Expressions.有关表达式的详细信息，请参阅表达式。

Behavior行为

Value Range数值范围

The supported value range for year and isoWeekYear is 1-9999.year和isoWeekYear的支持值范围为1-9999。

If the value specified for fields other than year, isoWeekYear, and timezone is outside the valid range, $dateFromParts carries or subtracts the difference from other date parts to calculate the date.如果为year、isoWeekYear和timezone以外的字段指定的值在有效范围之外，$dateFromParts将携带或减去其他日期部分的差值来计算日期。

Value is Greater than the Range值大于范围

Consider the following $dateFromParts expression where the month field value is 14, which is 2 months greater than the maximum value of 12 months(or 1 year):考虑以下$dateFromParts表达式，其中month字段值为14，比最大值12个月（或1年）大2个月：

{ $dateFromParts: { 'year' : 2017, 'month' : 14, 'day': 1, 'hour' : 12  } }

The expression calculates the date by increasing the year by 1 and setting the month to 2 to return:表达式通过将year加1并将month设置为2来计算日期：

ISODate("2018-02-01T12:00:00Z")

Value is Less than the Range值小于范围

Consider the following $dateFromParts expression where the month field value is 0, which is 1 month less than the minimum value of 1 month:考虑以下$dateFromParts表达式，其中month字段值为0，比最小值1个月小1个月：

{ $dateFromParts: { 'year' : 2017, 'month' : 0, 'day': 1, 'hour' : 12  } }

The expression calculates the date by decreasing the year by 1 and setting the month to 12 to return:表达式通过将year减1并将month设置为12来计算日期：

ISODate("2016-12-01T12:00:00Z")

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. The example uses the $hour and $minute operators to return the corresponding portions of the date field:以下聚合说明了MongoDB如何处理Olson时区标识符的DST偏移。该示例使用$hour和$minute运算符返回date字段的相应部分：

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
}

Example示例

The following aggregation uses $dateFromParts to construct three date objects from the provided input fields:以下聚合使用$dateFromParts从提供的输入字段构造三个日期对象：

db.sales.aggregate([
{
   $project: {
      date: {
         $dateFromParts: {
            'year' : 2017, 'month' : 2, 'day': 8, 'hour' : 12
         }
      },
      date_iso: {
         $dateFromParts: {
            'isoWeekYear' : 2017, 'isoWeek' : 6, 'isoDayOfWeek' : 3, 'hour' : 12
         }
      },
      date_timezone: {
         $dateFromParts: {
            'year' : 2016, 'month' : 12, 'day' : 31, 'hour' : 23,
            'minute' : 46, 'second' : 12, 'timezone' : 'America/New_York'
         }
      }
   }
}])

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

{
  "_id" : 1,
  "date" : ISODate("2017-02-08T12:00:00Z"),
  "date_iso" : ISODate("2017-02-08T12:00:00Z"),
  "date_timezone" : ISODate("2017-01-01T04:46:12Z")
}