Docs Home → MongoDB Manual

$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 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描述
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. 值范围：1-9999如果指定的数字超出此范围，则$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. Starting in MongoDB 4.4, the lower bound for this value is 1. 值范围：1-9999如果指定的数字超出此范围，则$dateFromParts错误。从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 If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 值范围：1-12如果指定的数字在此范围之外，$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 If the number specified is outside this range, $dateFromParts incorporates the difference in the date calculation. 值范围：1-53如果指定的数字在此范围之外，$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. 值范围：1-31。如果指定的数字在此范围之外，$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. 值范围：1-7如果指定的数字在此范围之外，$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. 值范围：0-23。如果指定的数字在此范围之外，$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. 值范围：0-59。如果指定的数字在此范围之外，$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. 值范围：0-59。如果指定的数字在此范围之外，$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. 值范围：0-999。如果指定的数字在此范围之外，$dateFromParts会在日期计算中包含差异。See Value Range for examples.有关示例，请参阅值范围。
timezoneOptional可选的<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-999。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。

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集合：

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