$dateFromString (agregação)
Definição
$dateFromString
Converte uma string de data/hora em um objeto de data.
A expressão
$dateFromString
tem a seguinte sintaxe:{ $dateFromString: { dateString: <dateStringExpression>, format: <formatStringExpression>, timezone: <tzExpression>, onError: <onErrorExpression>, onNull: <onNullExpression> } } O
$dateFromString
pega um documento com os seguintes campos:CampoDescriçãodateString
A string de data/hora para converter para um objeto de data. Consulte
Date()
para obter mais informações sobre formatos de data/hora.Observação
Se especificar a opção
timezone
para o operador, não inclua informações de fuso horário nodateString
.format
Opcional. A especificação do formato de data do
dateString
. Oformat
pode ser qualquer expressão que avalia para uma string literal, contendo 0 ou mais especificadores de formato. Para obter uma lista de especificadores disponíveis, consulte Formatar especificadores.Se não for especificado,
$dateFromString
utiliza"%Y-%m-%dT%H:%M:%S.%LZ"
como o formato padrão, mas aceita uma variedade de formatos e tenta analisar odateString
se possível.timezone
Opcional. O fuso horário a ser usado para formatar a data.
Observação
Se o argumento
dateString
estiver formatado como "2017-02-08T12:10:40,787Z", no qual o "Z" no final indica a hora de Zulu (fuso horário UTC), você não poderá especificar o argumentotimezone
.<timezone>
permite as seguintes opções e expressões que avaliam para eles:um Identificador de fuso horário Olson, como
"Europe/London"
ou"America/New_York"
, ouum deslocamento UTC no formato:
+/-[hh]:[mm]
, e.g."+04:45"
ou+/-[hh][mm]
, e.g."-0530"
ou+/-[hh]
, e.g."+03"
ou
As strings
"Z"
,"UTC"
ou"GMT"
Para mais informações sobre expressões, consulte Operadores de Expressão.
onError
Opcional. Se
$dateFromString
encontrar um erro na análise dodateString
fornecido, ele vai gerar o valor do resultado da expressãoonError
fornecida. Esse valor gerado pode ser de qualquer tipo.Se você não especificar
onError
,$dateFromString
gerará um erro se não conseguir analisardateString
.onNull
Opcional. Se o
dateString
fornecido a$dateFromString
estivernull
ou ausente, produzirá o valor de resultado da expressãoonNull
fornecida. Esse valor de resultado pode ser de qualquer tipo.Se você não especificar
onNull
edateString
estivernull
ou ausente, então$dateFromString
entregaránull
.
Comportamento
Exemplo | Resultados | ||||
---|---|---|---|---|---|
| ISODate("2017-02-08T12:10:40.787Z") | ||||
| ISODate("2017-02-08T17:10:40.787Z") | ||||
| ISODate("2017-02-08T00:00:00Z") | ||||
| ISODate("2020-10-20T00:00:00.000Z") | ||||
| ISODate("2018-06-15T00:00:00Z") | ||||
| ISODate("2018-06-15T00:00:00Z") | ||||
| ISODate("1996-01-31T08:35:28.000Z") |
Especificadores de formato
Os seguintes especificadores de formato estão disponíveis para uso no <formatString>
:
Especificadores | Descrição | Valores possíveis |
---|---|---|
%b | Mês abreviado (3 letras) | jan , feb , mar , apr , may , jun , jul , aug , sep , oct , nov , dec |
%B | Nome do mês inteiro | 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 | 1 -53 |
%w | Dia da semana como número inteiro (0-domingo, 6-sábado) | 0 -6 |
%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 | % |
Exemplos
Convertendo datas
Considere uma coleção logmessages
que contenha os seguintes documentos com datas.
{ _id: 1, date: "2017-02-08T12:10:40.787", timezone: "America/New_York", message: "Step 1: Started" }, { _id: 2, date: "2017-02-08", timezone: "-05:00", message: "Step 1: Ended" }, { _id: 3, message: " Step 1: Ended " }, { _id: 4, date: "2017-02-09", timezone: "Europe/London", message: "Step 2: Started"}, { _id: 5, date: "2017-02-09T03:35:02.055", timezone: "+0530", message: "Step 2: In Progress"}
A seguinte agregação utiliza $dateFromString para converter o valor date
para um objeto de data:
db.logmessages.aggregate( [ { $project: { date: { $dateFromString: { dateString: '$date', timezone: 'America/New_York' } } } } ] )
A agregação acima retorna os seguintes documentos e converte cada campo date
para o fuso horário Fuso Horário Oriental (Eastern Time Zone):
{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") } { "_id" : 2, "date" : ISODate("2017-02-08T05:00:00Z") } { "_id" : 3, "date" : null } { "_id" : 4, "date" : ISODate("2017-02-09T05:00:00Z") } { "_id" : 5, "date" : ISODate("2017-02-09T08:35:02.055Z") }
O argumento timezone
também pode ser fornecido através de um campo de documento em vez de um argumento codificado. Por exemplo:
db.logmessages.aggregate( [ { $project: { date: { $dateFromString: { dateString: '$date', timezone: '$timezone' } } } } ] )
A agregação acima retorna os seguintes documentos e converte cada campo date
em suas respectivas representações UTC.
{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") } { "_id" : 2, "date" : ISODate("2017-02-08T05:00:00Z") } { "_id" : 3, "date" : null } { "_id" : 4, "date" : ISODate("2017-02-09T00:00:00Z") } { "_id" : 5, "date" : ISODate("2017-02-08T22:05:02.055Z") }
onError
Se a sua coleção contiver documentos com strings de data não analisáveis, $dateFromString
lançará um erro, a menos que você forneça uma expressão de agregação ao parâmetro onError
opcional.
Por exemplo, dada uma coleção dates
com os seguintes documentos:
{ "_id" : 1, "date" : "2017-02-08T12:10:40.787", timezone: "America/New_York" }, { "_id" : 2, "date" : "20177-02-09T03:35:02.055", timezone: "America/New_York" }
Você pode usar o parâmetro onError
para retornar a data inválida em seu formato de string original:
db.dates.aggregate( [ { $project: { date: { $dateFromString: { dateString: '$date', timezone: '$timezone', onError: '$date' } } } } ] )
Isso retorna os seguintes documentos:
{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") } { "_id" : 2, "date" : "20177-02-09T03:35:02.055" }
onNull
Se sua coleção contiver documentos com strings de data null
, $dateFromString
retornará null
, a menos que você forneça uma expressão de agregação ao parâmetro opcional onNull
.
Por exemplo, dada uma coleção dates
com os seguintes documentos:
{ "_id" : 1, "date" : "2017-02-08T12:10:40.787", timezone: "America/New_York" }, { "_id" : 2, "date" : null, timezone: "America/New_York" }
Você pode utilizar o parâmetro onNull
para que $dateFromString
retorne uma data que representa a Era UNIX em vez de null
:
db.dates.aggregate( [ { $project: { date: { $dateFromString: { dateString: '$date', timezone: '$timezone', onNull: new Date(0) } } } } ] )
Isso retorna os seguintes documentos:
{ "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") } { "_id" : 2, "date" : ISODate("1970-01-01T00:00:00Z") }