Docs Home → MongoDB Manual

$dateToString (aggregation)

On this page本页内容

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表达式具有以下运算符表达式语法：

{ $dateToString: {
    date: <dateExpression>,
    format: <formatString>,
    timezone: <tzExpression>,
    onNull: <expression>
} }

The $dateToString takes a document with the following fields:$dateToString接受一个具有以下字段的文档：

Field字段Description描述
dateChanged in version 3.6.3.6版更改。
The date to convert to string. 要转换为字符串的日期。<dateExpression> must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID. 必须是解析为Date、Timestamp或ObjectID的有效表达式。
formatOptional.可选的。The date format specification. 日期格式规范。<formatString> can be any string literal, containing 0 or more format specifiers. 可以是任何字符串文字，包含0个或多个格式说明符。For a list of specifiers available, see Format Specifiers.有关可用说明符的列表，请参阅格式说明符。
If unspecified, $dateToString uses "%Y-%m-%dT%H:%M:%S.%LZ" as the default format. 如果未指定，$dateToString将使用"%Y-%m-%dT%H:%M:%S.%LZ"作为默认格式。
timezoneOptional. 可选。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. 必须是一个有效的表达式，该表达式解析为格式为Olson时区标识符或UTC偏移的字符串。If no timezone is provided, the result is displayed in UTC. 如果没有提供timezone，结果将以UTC显示。
Format格式Examples示例
Olson Timezone IdentifierOlson时区标识符 
"America/New_York"
"Europe/London"
"GMT"
UTC OffsetUTC偏移 
+/-[hh]:[mm], e.g. "+04:45"
+/-[hh][mm], e.g. "-0530"
+/-[hh], e.g. "+03"
onNullOptional.可选的。The value to return if the date is null or missing. 如果date为null或缺少，则返回的值。The arguments can be any valid expression.参数可以是任何有效的表达式。
If unspecified, $dateToString returns null if the date is null or missing. 如果未指定，如果日期为null或缺少，$dateToString将返回null。
Tip

See also: 另请参阅：

Format Specifiers格式规范

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

Specifiers标志成分Description描述Possible Values可能的值
%bAbbreviated month (3 letters)缩写月份（3个字母）jan-dec
%BFull month name完整月份名称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 (0-Sunday, 6-Saturday)星期几（0周日，6周六）0-6
%YYear (4 digits, zero padded)年份（4位，零填充）0000-9999
%zThe timezone offset from UTC.时区与UTC的偏移量。+/-[hh][mm]
%ZThe minutes offset from UTC as a number. 从UTC偏移的分钟数。For example, if the timezone offset (+/-[hhmm]) was +0445, the minutes offset is +285.例如，如果时区偏移量（+/-hhmm]）为+0445，则分钟偏移量为+285。+/-mmm
%%Percent Character as a Literal文字字符百分比%

Example实例

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

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

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"
}