$dateToParts (agregação)

Definição

$dateToParts

Retorna um documento que contém as partes constituintes de um determinado valor de data BSON como propriedades individuais. As propriedades retornadas são year, month, day, hour, minute, second e millisecond.

Você pode definir a iso8601 propriedade como true para retornar as partes que representam uma data semanal ISO no lugar. Isso retornará um documento em que as propriedades são isoWeekYear, isoWeek, isoDayOfWeek, hour, minute, second e millisecond.

A expressão $dateToParts tem a seguinte sintaxe:

{
    $dateToParts: {
        'date' : <dateExpression>,
        'timezone' : <timezone>,
        'iso8601' : <boolean>
    }
}

O $dateToParts pega um documento com os seguintes campos:

Campo	Obrigatório/Opcional	Descrição
date	Obrigatório	A data de entrada para a qual as partes serão devolvidas. <dateExpression> pode ser qualquer expressão que resolva para Date, Timestamp ou ObjectID. Para mais informações sobre expressões, consulte Operadores de expressão.
timezone	Opcional	O fuso horário a utilizar para formatar a data. Por padrão, usa$dateToParts UTC. <timezone> pode ser qualquer expressão avaliada como uma string cujo valor seja: um Identificador de fuso horário Olson, como "Europe/London" ou "America/New_York", ou um deslocamento UTC no formato: +/-[hh]:[mm], e.g. "+04:45" ou +/-[hh][mm], e.g. "-0530" ou +/-[hh], e.g. "+03". Para mais informações sobre expressões, consulte Operadores de Expressão.
iso8601	Opcional	Se definido como true, modifica o documento de saída para usar campos de data semanal ISO. O padrão é false.

Comportamento

Ao usar um identificador de fuso horário Olson no campo <timezone>, o MongoDB aplica a compensação de horário de verão, se aplicável ao fuso horário especificado.

Por exemplo, considere uma collection sales com o seguinte documento:

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

A seguinte agregação ilustra como o MongoDB lida com o deslocamento DST para o Identificador de fuso horário Olson. O exemplo utiliza os operadores $hour e $minute para retornar as partes correspondentes do campo 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" }
       }
   }
}])

A operação retorna o seguinte resultado:

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

Exemplo

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

{
  "_id" : 2,
  "item" : "abc",
  "price" : 10,
  "quantity" : 2,
  "date" : ISODate("2017-01-01T01:29:09.123Z")
}

A agregação a seguir usa $dateToParts para retornar um documento que contém as partes constituintes do campo date.

 db.sales.aggregate([
 {
    $project: {
       date: {
          $dateToParts: { date: "$date" }
       },
       date_iso: {
          $dateToParts: { date: "$date", iso8601: true }
       },
       date_timezone: {
          $dateToParts: { date: "$date", timezone: "America/New_York" }
       }
    }
}])

A operação retorna o seguinte resultado:

{
   "_id" : 2,
   "date" : {
      "year" : 2017,
      "month" : 1,
      "day" : 1,
      "hour" : 1,
      "minute" : 29,
      "second" : 9,
      "millisecond" : 123
   },
   "date_iso" : {
      "isoWeekYear" : 2016,
      "isoWeek" : 52,
      "isoDayOfWeek" : 7,
      "hour" : 1,
      "minute" : 29,
      "second" : 9,
      "millisecond" : 123
   },
   "date_timezone" : {
      "year" : 2016,
      "month" : 12,
      "day" : 31,
      "hour" : 20,
      "minute" : 29,
      "second" : 9,
      "millisecond" : 123
   }
}