$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 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	Alterado na versão 3.6. A data de entrada para a qual retornar peças. <dateExpression> pode ser qualquerexpressão que resolva para uma Date, um Timestamp ou um ObjectID. Para mais informações sobre expressões, consulte Expressões.
timezone	Opcional	O fuso horário a utilizar na formatação da data. Por padrão, $dateToParts utiliza 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], por exemplo, "+03". Para mais informações sobre expressões, consulte Expressões.
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 o deslocamento de horáriode verão , se aplicável, para o 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
   }
}