$dateToString (agregação)

Nesta página

Definição

Especificadores de formato
Exemplo

Definição

$dateToString

Converte um objeto de data em uma string de acordo com um formato especificado pelo usuário.

A expressão $dateToString tem a seguintesintaxe de expressão do operador :

Você pode utilizar o $dateToString para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

A expressão $dateToString tem a seguinte sintaxe de expressão do operador:

{ $dateToString: {
    date: <dateExpression>,
    format: <formatString>,
    timezone: <tzExpression>,
    onNull: <expression>
} }
     - The date to convert to string. ``<dateExpression>`` must be a
       valid :ref:`expression <aggregation-expressions>` that
       resolves to a :ref:`Date <document-bson-type-date>`, a
       :ref:`Timestamp <document-bson-type-timestamp>`, or an
       :ref:`ObjectID <document-bson-type-object-id>`.
* - Field
  - Description
     - Optional. The date format specification. ``<formatString>``
       can be any string literal, containing 0 or more format
       specifiers. For a list of specifiers available, see
       :ref:`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.
       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.
    The date to convert to string. ``<dateExpression>`` must be a
    valid :ref:`expression <aggregation-expressions>` that
    resolves to a :ref:`Date <document-bson-type-date>`, a
    :ref:`Timestamp <document-bson-type-timestamp>`, or an
    :ref:`ObjectID <document-bson-type-object-id>`.
* - ``format``
  - Optional. The date format specification. ``<formatString>`` can be any
    string literal, containing 0 or more format specifiers. For a
    list of specifiers available, see :ref:`format-specifiers`.
    If unspecified, :expression:`$dateToString` uses
    ``"%Y-%m-%dT%H:%M:%S.%LZ"`` as the default format.
       If unspecified, ``$dateToString`` returns null if the
       ``date`` is null or missing.

Dica

Veja também:

Especificadores de formato

Os seguintes especificadores de formato estão disponíveis para uso no <formatString>:

Especificadores	Descrição	Valores possíveis
`%b`	Nome do mês abreviado (3 letras) Novidades na versão 7.0.	`jan`-`dec`
`%B`	Nome do mês inteiro Novidades na versão 7.0.	`january`-`december`
`%d`	Dia do mês (2 dígitos, zero acolchoado)	`01`-`31`
`%G`	Ano no formato ISO 8601	`0000`-`9999`
`%H`	Hora (2 dígitos, zero acolchoado, relógio de 24 horas)	`00`-`23`
`%j`	Dia do ano (3 dígitos, zero preenchido)	`001`-`366`
`%L`	Milissegundo (3 dígitos, zero preenchido)	`000`-`999`
`%m`	Mês (2 dígitos, zero preenchido)	`01`-`12`
`%M`	Minuto (2 dígitos, zero preenchido)	`00`-`59`
`%S`	Segundo (2 dígitos, zero preenchido)	`00`-`60`
`%u`	Número do dia da semana no formato ISO 8601 (1-segunda, 7-domingo)	`1`-`7`
`%U`	Semana do ano (2 dígitos, zero preenchido)	`00`-`53`
`%V`	Semana do ano no formato ISO 8601	`01`-`53`
`%w`	Dia da semana (1-domingo, 7-sábado)	`1`-`7`
`%Y`	Ano (4 dígitos, zero preenchido)	`0000`-`9999`
`%z`	Deslocamento do fuso horário de UTC.	`+/-[hh][mm]`
`%Z`	Os minutos são compensados do UTC como um número. Por exemplo, se o deslocamento de fuso horário (`+/-[hhmm]`) foi `+0445`, o deslocamento de minutos é `+285`.	`+/-mmm`
`%%`	Caractere percentual como literal	`%`

Exemplo

Considere uma coleção sales com o seguinte documento:

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

A seguinte agregação utiliza $dateToString para retornar o campo date como strings formatadas:

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

A operação retorna o seguinte resultado:

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

Voltar

$dateToParts

$dateTrunc