Database Manual / Reference / Query Language / Expressions

$dateToString (aggregation operator)（聚合运算符）

Definition定义

$dateToString

Converts a date object to a string according to a user-specified format.根据用户指定的格式将日期对象转换为字符串。

The $dateToString expression has the following operator expression syntax:$dateToString表达式具有以下运算符表达式语法：

You can use $dateToString for deployments hosted in the following environments:您可以将$dateToString用于在以下环境中托管的部署：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务
  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

The $dateToString expression has the following operator expression syntax:$dateToString表达式具有以下运算符表达式语法：

{ $dateToString: {
    date: <dateExpression>,
    format: <formatString>,
    timezone: <tzExpression>,
    onNull: <expression>
} }
Field字段Description描述
dateThe date to convert to string. 要转换为字符串的日期。<dateExpression> must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID.<dateExpression>必须是解析为Date、Timestamp或ObjectID的有效表达式。
format

Optional. 可选。The date format specification. <formatString> can be any string literal, containing zero or more format specifiers. 日期格式规范。<formatString>可以是任何字符串文字，包含零个或多个格式说明符。For a list of specifiers available, see Format Specifiers.有关可用说明符的列表，请参阅格式说明符。

If unspecified and the timezone is specified and set to a non UTC timezone, then $dateToString uses "%Y-%m-%dT%H:%M:%S.%L" as the default format.如果未指定，并且指定了timezone并将其设置为非UTC时区，则$dateToString将使用"%Y-%m-%dT%H:%M:%S.%L"作为默认格式。

If unspecified and the timezone is unspecified or explicitly specified as UTC, then $dateToString uses "%Y-%m-%dT%H:%M:%S.%LZ" as the default format.如果未指定，并且timezone未指定或明确指定为UTC，则$dateToString使用"%Y-%m-%dT%H:%M:%S.%LZ"作为默认格式。

timezone

Optional. 可选。The timezone of the operation result. 操作结果的时区。<tzExpression> must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If no timezone is provided, the result is in UTC.必须是解析为奥尔森时区标识符或UTC偏移格式的字符串的有效表达式。如果没有提供timezone，则结果为UTC。

Format格式Examples示例
Olson Timezone Identifier奥尔森时区标识符
"America/New_York"
"Europe/London"
"GMT"
UTC OffsetUTC偏移
+/-[hh]:[mm], e.g. "+04:45"
+/-[hh][mm], e.g. "-0530"
+/-[hh], e.g. "+03"
onNull

Optional. 可选。The value to return if the date is null or missing. The arguments can be any valid expression.如果date为空或缺失，则返回的值。参数可以是任何有效的表达式。

If unspecified, $dateToString returns null if the date is null or missing.如果未指定，如果日期为null或缺失，$dateToString将返回null。

Tip

Format Specifiers格式说明符

The following format specifiers are available for use in the <formatString>:以下格式说明符可用于<formatString>：

Specifiers标志成分Description描述Possible Values可能的值
%bAbbreviated month name (3 letters)缩写月份名称（3个字母）

New in version 7.0.在版本7.0中新增。

jan-dec

%BFull month name完整月份名称

New in version 7.0.在版本7.0中新增。

january-december

%dDay of month (2 digits, zero padded)月份中的第几天（2位数字，零填充）01-31
%GYear in ISO 8601 formatISO 8601格式的年份0000-9999
%HHour (2 digits, zero padded, 24-hour clock)小时（2位数字，加零，24小时制）00-23
%jDay of year (3 digits, zero padded)一年中的第几天（3位数字，零填充）001-366
%LMillisecond (3 digits, zero padded)毫秒（3位数字，零填充）000-999
%mMonth (2 digits, zero padded)月份（2位数字，零填充）01-12
%MMinute (2 digits, zero padded)分钟（2位数字，加零）00-59
%SSecond (2 digits, zero padded)秒（2位数字，零填充）00-60
%uDay of week number in ISO 8601 format (1-Monday, 7-Sunday)ISO 8601格式的星期几编号（1-星期一，7-星期日）1-7
%UWeek of year (2 digits, zero padded)一年中的星期（2位数字，零填充）00-53
%VWeek of Year in ISO 8601 formatISO 8601格式的一年中的一周01-53
%wDay of week (1-Sunday, 7-Saturday)一周中的某一天（1-周日，7-周六）1-7
%YYear (4 digits, zero padded)年份（4位数字，零填充）0000-9999
%zThe timezone offset from UTC.UTC的时区偏移。+/-[hh][mm]
%ZThe minutes offset from UTC as a number. For example, if the timezone offset (+/-[hhmm]) was +0445, the minutes offset is +285.UTC的分钟偏移量为数字。例如，如果时区偏移量（+/-[hhmm]）为+0445，则分钟偏移量为+285。+/-mmm
%%Percent Character as a Literal百分比字符作为文字%

Example示例

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

 db.sales.insertOne(
  {
   "_id" : 1,
   "item" : "abc",
   "price" : 10,
   "quantity" : 2,
   "date" : ISODate("2014-01-01T08:15:39.736Z")
  }
)

The following aggregation uses $dateToString to return the date field as formatted strings:以下聚合使用$dateToString以格式化字符串的形式返回date字段：

db.sales.aggregate(
   [
     {
       $project: {
          yearMonthDayUTC: { $dateToString: { format: "%Y-%m-%d", date: "$date" } },
          timewithOffsetNY: { $dateToString: { format: "%H:%M:%S:%L%z", date: "$date", timezone: "America/New_York"} },
          timewithOffset430: { $dateToString: { format: "%H:%M:%S:%L%z", date: "$date", timezone: "+04:30" } },
          minutesOffsetNY: { $dateToString: { format: "%Z", date: "$date", timezone: "America/New_York" } },
          minutesOffset430: { $dateToString: { format: "%Z", date: "$date", timezone: "+04:30" } },
          abbreviated_month: { $dateToString: {format: "%b", date: "$date", timezone: "+04:30" } },
          full_month: { $dateToString: { format: "%B", date: "$date", timezone: "+04:30" } }
       }
     }
   ]
)

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

{
   "_id" : 1,
   "yearMonthDayUTC" : "2014-01-01",
   "timewithOffsetNY" : "03:15:39:736-0500",
   "timewithOffset430" : "12:45:39:736+0430",
   "minutesOffsetNY" : "-300",
   "minutesOffset430" : "270",
   "abbreviated_month": "Jan",
   "full_month": "January"
}