Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB Manual

$dateFromParts（聚合）

在此页面上

  • 定义
  • 行为
  • 例子

定义

$dateFromParts

版本 3.6 中的新增功能。

根据日期的组成属性，构造并返回日期对象。

$dateFromParts表达式采用以下语法：

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

您还可以在 ISO week date 中指定组成日期字段。 使用以下语法格式化：

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

$dateFromParts接受包含以下字段的文档：

重要

在构建$dateFromParts输入文档时，不能同时使用日历日期和 ISO 周日期字段。

字段
必需/可选
说明
year
必填字段，前提是不使用 isoWeekYear

日历年。可以是任何计算结果为数字的表达式。

值范围：1-9999

如果指定的数字超出此范围，则$dateFromParts 出错。此值的下限为1 。
isoWeekYear
必填字段，前提是不使用 year

ISO 周日期年。可以是任何计算结果为数字的表达式。

值范围：1-9999

如果指定的数字超出此范围，则$dateFromParts 出错。此值的下限为1 。
month
可选。只能与 year 一起使用。

月。可以是任何计算结果为数字的表达式。

默认值为 1。

值范围：1-12

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
isoWeek
可选。只能与 isoWeekYear 一起使用。

一年中的一周。可以是任何计算结果为数字的表达式。

默认值为 1。

值范围：1-53

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
day
可选。只能与 year 一起使用。

一个月中的某一天。可以是任何计算结果为数字的表达式。

默认值为 1。

值范围：1-31

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
isoDayOfWeek
可选。只能与 isoWeekYear 一起使用。

一周中的某一天（星期一 1 - 星期日 7）。可以是任何计算结果为数字的表达式。

默认值为 1。

值范围：1-7

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
hour
Optional

小时。可以是任何计算结果为数字的表达式。

默认值为 0。

值范围：0-23

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
minute
Optional

分钟。可以是任何计算结果为数字的表达式。

默认值为 0。

值范围： 0 - 59如果指定的数字超出此范围， $dateFromParts则会将差值纳入日期计算。有关示例，请参阅值范围。

second
Optional

秒。可以是任何计算结果为数字的表达式。

默认值为 0。

值范围：0-59

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
millisecond
Optional

毫秒。可以是任何计算结果为数字的表达式。

默认值为 0。

值范围：0-999

如果指定的数字超出此范围，$dateFromParts 则会将差值纳入日期计算。有关示例，请参阅 值范围 。
timezone
Optional

<timezone> 可以是任何计算结果为字符串的表达式，其值为：

  • Olson 时区标识符 ，例如"Europe/London" 或"America/New_York" ，或者

  • UTC 偏移量，格式如下：

    • +/-[hh]:[mm]，例如 "+04:45" ，或

    • +/-[hh][mm]，例如 "-0530" ，或

    • +/-[hh]，例如"+03"。

有关表达式的更多信息，请参阅表达式。

行为

数值范围

year和isoWeekYear支持的值范围是1-9999 。

如果为year 、 isoWeekYear和timezone以外的字段指定的值超出有效范围， $dateFromParts将通过进位或与其他日期部分减去差值来计算日期。

值大于范围

考虑以下$dateFromParts表达式，其中month字段值为14 ，比最大值12个月（或1年）大2个月：

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

该表达式通过将 year 增加 1 并将 month 设置为 2 来计算日期，返回：

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

值小于范围

考虑以下$dateFromParts表达式，其中month字段值为0 ，比1月的最小值小1个月：

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

该表达式通过将 year 减少 1 并将 month 设置为 12 来计算日期，返回：

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

时区

在 <timezone> 字段中使用 Olson 时区标识符时，如果适用于指定的时区，MongoDB 会应用 DST 偏移量。

例如，考虑包含以下文档的 sales 集合：

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

以下聚合说明了 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" }
       }
   }
}])

操作返回以下结果：

{
   "_id": 1,
   "nycHour" : 5,
   "nycMinute" : 24,
   "gmtHour" : 10,
   "gmtMinute" : 24,
   "nycOlsonHour" : 6,
   "nycOlsonMinute" : 24
}

例子

以下聚合使用$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'
         }
      }
   }
}])

操作返回以下结果：

{
  "_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（聚合）
$dateFromString（聚合） →

在此页面上