$dateFromString（聚合）

在此页面上

定义

行为
格式描述符
示例

MongoDB5.0 已于 10 月2024 结束生命周期。不再支持此版本的文档。要升级5.0 部署，请参阅 MongoDB6 。0 升级程序。

定义

$dateFromString

版本 3.6 中的新增功能。

将日期/时间字符串转换为日期对象。

$dateFromString 表达式的语法如下：

{ $dateFromString: {
     dateString: <dateStringExpression>,
     format: <formatStringExpression>,
     timezone: <tzExpression>,
     onError: <onErrorExpression>,
     onNull: <onNullExpression>
} }

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

字段	说明
`dateString`	要转换为日期对象的日期/时间string 。有关日期/时间格式的更多信息，请参阅日期。如果为该操作符指定 `timezone` 选项，请勿在 `dateString` 中包含时区信息。
`format`	可选。的日期格式规范。`dateString` `format`可以是任何计算结果为字符串文字的表达式，并包含0 或更多格式说明符。有关可用说明符的列表，请参阅格式说明符。如果未指定，`$dateFromString` 会使用`"%Y-%m-%dT%H:%M:%S.%LZ"` 作为默认格式，但也接受各种格式，并在可能的情况下尝试解析`dateString` 。
`timezone`	可选。用于设置日期格式的时区。如果 `dateString` 参数的格式类似于“2017-02-08T12:10:40.787Z”，其中末尾的“Z”表示祖鲁时间（UTC 时区），则无法指定 `timezone` 参数。 `<timezone>` 允许使用以下选项以及对其进行计算的表达式： Olson 时区标识符，例如`"Europe/London"` 或`"America/New_York"` ，或者 UTC 偏移量，格式如下： `+/-[hh]:[mm]`，例如 `"+04:45"` ，或 `+/-[hh][mm]`，例如 `"-0530"` ，或 `+/-[hh]`，例如 `"+03"` ，或字符串 `"Z"`、`"UTC"` 或 `"GMT"` 有关表达式的更多信息，请参阅表达式。
`onError`	可选。如果`$dateFromString` 在解析给定`dateString` 时遇到错误，则会输出所提供`onError` 表达式的结果值。此结果值可以是任何类型。如果未指定`onError` ，`$dateFromString` 将在无法解析`dateString` 时引发错误。
`onNull`	可选。如果提供给`dateString` 的`$dateFromString` 为`null` 或缺失，则输出所提供的`onNull` 表达式的结果值。此结果值可以是任何类型。如果未指定 `onNull`且为`dateStringnull` 或缺失，则`$dateFromString` 输出`null` 。

提示

另请参阅：

行为

例子

结果

{ $dateFromString: {
    dateString: "2017-02-08T12:10:40.787"
} }

ISODate("2017-02-08T12:10:40.787Z")

{ $dateFromString: {
     dateString: "2017-02-08T12:10:40.787",
     timezone: "America/New_York"
} }

ISODate("2017-02-08T17:10:40.787Z")

{ $dateFromString: {
     dateString: "2017-02-08"
} }

ISODate("2017-02-08T00:00:00Z")

{ $dateFromString: {
     dateString: "06-15-2018",
     format: "%m-%d-%Y"
} }

ISODate("2018-06-15T00:00:00Z")

{ $dateFromString: {
     dateString: "15-06-2018",
     format: "%d-%m-%Y"
} }

ISODate("2018-06-15T00:00:00Z")

{ $dateFromString: {
     dateString: "WED jan 31 12:05:28 +03:30 1996"
} }

ISODate("1996-01-31T08:35:28.000Z")

格式描述符

<formatString> 中可使用以下格式说明符：

说明符	说明	Possible Values
`%d`	月中的某一天（2 位数字，补零）	`01`-`31`
`%G`	ISO 8601 格式的年份	`0000`-`9999`
`%H`	小时（2 位数字，填充零，24 小时时钟）	`00`-`23`
`%L`	毫秒（3 位数字，填充零）	`000`-`999`
`%m`	月份（2 位数字，补零）	`01`-`12`
`%M`	分钟（2 位数字，填充零）	`00`-`59`
`%S`	第二（2 位数字，补零）	`00`-`60`
`%u`	一周中每天的编号（采用 ISO 8601 格式，1-星期一，7-星期日）	`1`-`7`
`%V`	ISO 8601 格式的年中的某一周	`1`-`53`
`%Y`	年份（4 位数字，补零）	`0000`-`9999`
`%z`	与 UTC 的时区偏移。	`+/-[hh][mm]`
`%Z`	从 UTC 开始偏移的分钟数。例如，如果时区偏移 (`+/-[hhmm]`) 为 `+0445`，则分钟偏移为 `+285`。	`+/-mmm`
`%%`	作为文本的百分比字符	`%`

示例

转换日期

以一个包含以下文档（附带日期）的集合 logmessages 为例。

{ _id: 1, date: "2017-02-08T12:10:40.787", timezone: "America/New_York", message:  "Step 1: Started" },
{ _id: 2, date: "2017-02-08", timezone: "-05:00", message:  "Step 1: Ended" },
{ _id: 3, message:  " Step 1: Ended " },
{ _id: 4, date: "2017-02-09", timezone: "Europe/London", message: "Step 2: Started"},
{ _id: 5, date: "2017-02-09T03:35:02.055", timezone: "+0530", message: "Step 2: In Progress"}

以下聚合使用 $dateFromString 将 date 值转换为日期对象：

db.logmessages.aggregate( [ {
   $project: {
      date: {
         $dateFromString: {
            dateString: '$date',
            timezone: 'America/New_York'
         }
      }
   }
} ] )

上述聚合会返回以下文档，并将每个 date 字段转换为东部时区：

{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") }
{ "_id" : 2, "date" : ISODate("2017-02-08T05:00:00Z") }
{ "_id" : 3, "date" : null }
{ "_id" : 4, "date" : ISODate("2017-02-09T05:00:00Z") }
{ "_id" : 5, "date" : ISODate("2017-02-09T08:35:02.055Z") }

timezone 参数也可以通过文档字段提供，而不是硬编码参数。例如：

db.logmessages.aggregate( [ {
   $project: {
      date: {
         $dateFromString: {
            dateString: '$date',
            timezone: '$timezone'
         }
      }
   }
} ] )

上述聚合返回以下文档，并将每个 date 字段转换为其各自的 UTC 表示。

{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") }
{ "_id" : 2, "date" : ISODate("2017-02-08T05:00:00Z") }
{ "_id" : 3, "date" : null }
{ "_id" : 4, "date" : ISODate("2017-02-09T00:00:00Z") }
{ "_id" : 5, "date" : ISODate("2017-02-08T22:05:02.055Z") }

`onError`

如果集合包含带有不可解析日期字符串的文档，则除非您为可选的 onError 参数提供聚合表达式，否则 $dateFromString 会引发错误。

例如，假设有一个包含以下文档的集合 dates：

{ "_id" : 1, "date" : "2017-02-08T12:10:40.787", timezone: "America/New_York" },
{ "_id" : 2, "date" : "20177-02-09T03:35:02.055", timezone: "America/New_York" }

您可以使用 onError 参数以原始字符串形式返回无效的日期：

db.dates.aggregate( [ {
   $project: {
      date: {
         $dateFromString: {
            dateString: '$date',
            timezone: '$timezone',
            onError: '$date'
         }
      }
   }
} ] )

这将返回以下文档：

{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") }
{ "_id" : 2, "date" : "20177-02-09T03:35:02.055" }

`onNull`

如果您的集合包含 null 日期字符串的文档，$dateFromString 将返回 null，除非您为可选的 onNull 参数提供了聚合表达式。

例如，假设有一个包含以下文档的集合 dates：

{ "_id" : 1, "date" : "2017-02-08T12:10:40.787", timezone: "America/New_York" },
{ "_id" : 2, "date" : null, timezone: "America/New_York" }

您可以使用 onNull 参数让 $dateFromString 返回一个代表 unix 纪元的日期，而不使用 null：

db.dates.aggregate( [ {
   $project: {
      date: {
         $dateFromString: {
            dateString: '$date',
            timezone: '$timezone',
            onNull: new Date(0)
         }
      }
   }
} ] )

这将返回以下文档：

{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") }
{ "_id" : 2, "date" : ISODate("1970-01-01T00:00:00Z") }

后退

$dateFromParts

来年

$dateSubtract