$dateFromParts (aggregation)

On this page本页内容

Definition定义

$dateFromParts

New in version 3.6.版本3.6中的新功能。

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

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 week date格式指定组成日期字段：

{
    $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描述
year Required 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. 如果指定的数字超出此范围，$dateFromParts出错。Starting in MongoDB 4.4, the lower bound for this value is 1. 从MongoDB 4.4开始，该值的下限为1。In previous versions of MongoDB, the lower bound was 0.在以前版本的MongoDB中，下限为0。

isoWeekYear Required if not using year如果不使用year，则需要

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

Value range: 取值范围： 1-9999

If the number specified is outside this range, $dateFromParts errors. 如果指定的数字超出此范围，$dateFromParts出错。Starting in MongoDB 4.4, the lower bound for this value is 1. 从MongoDB 4.4开始，该值的下限为1。In previous versions of MongoDB, the lower bound was 0.在以前版本的MongoDB中，下限为0。

month Optional.可选。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

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

isoWeek Optional.可选。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

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

day Optional.可选。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

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

isoDayOfWeek Optional.可选。Can only be used with isoWeekYear.只能与isoWeekYear一起使用。

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

Defaults to 1.默认值为1。

Value range: 取值范围：1-7

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

hour Optional可选

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

Defaults to 0.默认值为0。

Value range: 取值范围： 0-23

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

minute Optional可选

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

Defaults to 0.默认值为0。

Value range: 取值范围：0-59 Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

second Optional可选

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

Defaults to 0.默认值为0。

Value range: 取值范围：0-59

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

millisecond Optional可选

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

Defaults to 0.默认值为0。

Value range: 取值范围： 0-999

Starting in MongoDB 4.0, if the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 从MongoDB 4.0开始，如果指定的数字超出此范围，$dateFromParts将在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。

timezone Optional可选

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

  • 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，或者
    • +/-[hh][mm], e.g. ，例如："-0530", or，或者
    • +/-[hh], e.g. ，例如："+03".。

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

Behavior行为

Value Range值范围

Starting in MongoDB 4.4, the supported value range for year and isoWeekYear is 1-9999. 从MongoDB 4.4开始，year和isoWeekYear支持的值范围为1-9999。In prior versions of MongoDB, the lower bound for these values was 0 and the supported value range was 0-9999.在早期版本的MongoDB中，这些值的下限为0，支持的值范围为0-9999。

Starting in MongoDB 4.0, 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.从MongoDB 4.0开始，如果为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>字段中使用奥尔森时区标识符时，MongoDB会在适用于指定时区的情况下应用DST偏移量。

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

{
   "_id" : 1,
   "item" : "abc",
   "price" : 20,
   "quantity" : 5,
   "date" : ISODate("2017-05-20T10:24:51.303Z")
}

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
}

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")
}