$dateFromParts (agregação)

Esta versão da documentação foi arquivada e não é mais suportada. Para atualizar seu sistema do 5.0, consulte osprocedimentos de atualização do MongoDB 6.0 .

Definição

$dateFromParts

Novidade na versão 3.6.

Constrói e retorna um objeto de data, dadas as propriedades constituintes da data.

A expressão $dateFromParts tem a seguinte sintaxe:

{
    $dateFromParts : {
        'year': <year>, 'month': <month>, 'day': <day>,
        'hour': <hour>, 'minute': <minute>, 'second': <second>,
        'millisecond': <ms>, 'timezone': <tzExpression>
    }
}

Você também pode especificar seus campos de data constituintes no formato de data semanal ISO usando a seguinte sintaxe:

{
    $dateFromParts : {
        'isoWeekYear': <year>, 'isoWeek': <week>, 'isoDayOfWeek': <day>,
        'hour': <hour>, 'minute': <minute>, 'second': <second>,
        'millisecond': <ms>, 'timezone': <tzExpression>
    }
}

O $dateFromParts pega um documento com os seguintes campos:

Importante

Não é possível combinar o uso de datas de calendário e campos de data da semana ISO ao criar o documento de entrada $dateFromParts.

Campo	Obrigatório/Opcional	Descrição
`year`	Obrigatório se não estiver usando `isoWeekYear`	Ano do calendário. Pode ser qualquerexpressão avaliada como um número. Intervalo de valor: `1`-`9999` Se o número especificado estiver fora deste intervalo, erros`$dateFromParts` do. O limite inferior para este valor é `1`.
`isoWeekYear`	Obrigatório se não estiver usando `year`	Semana Data Ano ISO. Pode ser qualquer expressão que seja avaliada como um número. Intervalo de valor: `1`-`9999` Se o número especificado estiver fora deste intervalo, erros`$dateFromParts` do. O limite inferior para este valor é `1`.
`month`	Opcional. Só pode ser usado com `year`.	Mês. Pode ser qualquer expressão avaliada como um número. Padrão é `1`. Intervalo de valor: `1`-`12` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`isoWeek`	Opcional. Só pode ser usado com `isoWeekYear`.	Semana do ano. Pode ser qualquer expressão que seja avaliada como um número. Padrão é `1`. Intervalo de valor: `1`-`53` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`day`	Opcional. Só pode ser usado com `year`.	Dia do mês. Pode ser qualquer expressão que seja avaliada como um número. Padrão é `1`. Intervalo de valor: `1`-`31` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`isoDayOfWeek`	Opcional. Só pode ser usado com `isoWeekYear`.	Dia da semana (de segunda `1` a domingo,`7`). Pode ser qualquer expressão que avalia para um número. Padrão é `1`. Intervalo de valor: `1`-`7` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`hour`	Opcional	Hora. Pode ser qualquer expressão que seja avaliada como um número. Padrão é `0`. Intervalo de valor: `0`-`23` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`minute`	Opcional	Minuto. Pode ser qualquer expressão que seja avaliada como um número. Padrão é `0`. Intervalo de valor: `0`-`59` Se o número especificado estiver fora desta faixa, incorpora a diferença no cálculo de`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`second`	Opcional	Segundo. Pode ser qualquer expressão que seja avaliada como um número. Padrão é `0`. Intervalo de valor: `0`-`59` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`millisecond`	Opcional	Milissegundo. Pode ser qualquer expressão que seja avaliada como um número. Padrão é `0`. Intervalo de valor: `0`-`999` Se o número especificado estiver fora desse intervalo, incorporará a diferença no cálculo da`$dateFromParts` data. Consulte Intervalo de Valores para obter exemplos.
`timezone`	Opcional	`<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 Expressões.

Comportamento

Faixa de valor

O intervalo de valores permitido para year e isoWeekYear é 1-9999.

Se o valor especificado para campos diferentes de year, isoWeekYear e timezone estiver fora do intervalo válido, $dateFromParts transportará ou subtrairá a diferença de outras partes da data para calcular a data.

O valor é maior que o intervalo

Considere a seguinte expressão $dateFromParts em que o valor do campo month é 14, que é 2 meses maior que o valor máximo de 12 meses (ou 1 ano):

{ $dateFromParts: { 'year' : 2017, 'month' : 14, 'day': 1, 'hour' : 12  } }

A expressão calcula a data aumentando o year por 1 e definindo o month para 2 para retornar:

ISODate("2018-02-01T12:00:00Z")

O valor é menor que a faixa

Considere a seguinte expressão $dateFromParts em que o valor do campo month é 0, que é 1 mês a menos do que o valor mínimo de 1 mês:

{ $dateFromParts: { 'year' : 2017, 'month' : 0, 'day': 1, 'hour' : 12  } }

A expressão calcula a data diminuindo o year por 1 e definindo o month para 12 para retornar:

ISODate("2016-12-01T12:00:00Z")

Fuso horário

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

A seguinte agregação utiliza $dateFromParts para construir três objetos de data a partir dos campos de entrada fornecidos:

db.sales.aggregate([
{
   $project: {
      date: {
         $dateFromParts: {
            'year' : 2017, 'month' : 2, 'day': 8, 'hour' : 12
         }
      },
      date_iso: {
         $dateFromParts: {
            'isoWeekYear' : 2017, 'isoWeek' : 6, 'isoDayOfWeek' : 3, 'hour' : 12
         }
      },
      date_timezone: {
         $dateFromParts: {
            'year' : 2016, 'month' : 12, 'day' : 31, 'hour' : 23,
            'minute' : 46, 'second' : 12, 'timezone' : 'America/New_York'
         }
      }
   }
}])

A operação retorna o seguinte resultado:

{
  "_id" : 1,
  "date" : ISODate("2017-02-08T12:00:00Z"),
  "date_iso" : ISODate("2017-02-08T12:00:00Z"),
  "date_timezone" : ISODate("2017-01-01T04:46:12Z")
}

Voltar

$dateDiff

$dateFromString