$dateToParts (aggregation)

Definition定义

$dateToParts

Returns a document that contains the constituent parts of a given BSON Date value as individual properties. 返回一个文档，该文档包含作为单个属性的给定BSON日期值的组成部分。The properties returned are year, month, day, hour, minute, second and millisecond.返回的属性为year、month、day、hour、minute、second和millisecond。

You can set the iso8601 property to true to return the parts representing an ISO week date instead. 您可以将iso8601属性设置为true，以返回表示ISO周日期的成份。This will return a document where the properties are isoWeekYear, isoWeek, isoDayOfWeek, hour, minute, second and millisecond.这将返回一个文档，其中属性为isoWeekYear、isoWeek、isoDayOfWeek、hour、minute、second和millisecond。

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

{
    $dateToParts: {
        'date' : <dateExpression>,
        'timezone' : <timezone>,
        'iso8601' : <boolean>
    }
}

The $dateToParts takes a document with the following fields:$dateToParts获取一个包含以下字段的文档：

Field字段	Required/Optional必需/可选	Description描述
date	Required必要的	Changed in version 3.6.3.6版更改。 The input date for which to return parts. 返回零件的输入日期。<dateExpression> can be any expression that resolves to a Date, a Timestamp, or an ObjectID. 可以是解析为Date、Timestamp或ObjectID的任何表达式。For more information on expressions, see Expressions. 有关表达式的详细信息，请参阅表达式。
timezone	Optional可选的	The timezone to use to format the date. 用于设置日期格式的时区。By default, $dateToParts uses UTC.默认情况下，$dateToParts使用UTC。 <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. 有关表达式的详细信息，请参阅表达式。
iso8601	Optional可选的	If set to true, modifies the output document to use ISO week date fields. 如果设置为true，则修改输出文档以使用ISO周日期字段。Defaults to false.默认为false。

Behavior行为

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实例

Consider a sales collection with the following document:考虑一个带有以下文档的sales集合：

{
  "_id" : 2,
  "item" : "abc",
  "price" : 10,
  "quantity" : 2,
  "date" : ISODate("2017-01-01T01:29:09.123Z")
}

The following aggregation uses $dateToParts to return a document that contains the constituent parts of the date field.以下聚合使用$dateToParts返回包含date字段组成部分的文档。

 db.sales.aggregate([
 {
    $project: {
       date: {
          $dateToParts: { date: "$date" }
       },
       date_iso: {
          $dateToParts: { date: "$date", iso8601: true }
       },
       date_timezone: {
          $dateToParts: { date: "$date", timezone: "America/New_York" }
       }
    }
}])

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

{
   "_id" : 2,
   "date" : {
      "year" : 2017,
      "month" : 1,
      "day" : 1,
      "hour" : 1,
      "minute" : 29,
      "second" : 9,
      "millisecond" : 123
   },
   "date_iso" : {
      "isoWeekYear" : 2016,
      "isoWeek" : 52,
      "isoDayOfWeek" : 7,
      "hour" : 1,
      "minute" : 29,
      "second" : 9,
      "millisecond" : 123
   },
   "date_timezone" : {
      "year" : 2016,
      "month" : 12,
      "day" : 31,
      "hour" : 20,
      "minute" : 29,
      "second" : 9,
      "millisecond" : 123
   }
}