$dateFromParts (aggregation)

On this page本页内容

Definition定义

$dateFromParts

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

{
    $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. 如果指定的数字超出此范围，$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。
isoWeekYearRequired 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。
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

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.有关示例，请参阅值范围。
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

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.有关示例，请参阅值范围。
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

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.有关示例，请参阅值范围。
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.

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.有关示例，请参阅值范围。
hourOptional可选

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.有关示例，请参阅值范围。
minuteOptional可选

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.有关示例，请参阅值范围。

secondOptional可选

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.有关示例，请参阅值范围。
millisecondOptional可选

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.有关示例，请参阅值范围。
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
    • +/-[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")
}
←  $dateDiff (aggregation)$dateFromString (aggregation) →