Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

$dateFromString (agregação)

Nesta página

  • Definição
  • Comportamento
  • Especificadores de formato
  • Exemplos
$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:

Campo
Descrição
dateString

A string de data/hora para converter para um objeto de data. Consulte Date() para obter mais informações sobre formatos de data/hora.

Se especificar a opção timezone para o operador, não inclua informações de fuso horário no dateString.

format

Opcional. A especificação do formato de data do dateString. O format 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 o dateString se possível.

timezone

Opcional. O fuso horário a ser usado para formatar a data.

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 argumento timezone.

<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", ou

  • um 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 do dateString fornecido, ele vai gerar o valor do resultado da expressão onError fornecida. Esse valor gerado pode ser de qualquer tipo.

Se você não especificar onError, $dateFromString gerará um erro se não conseguir analisar dateString.

onNull

Opcional. Se o dateString fornecido a $dateFromString estiver null ou ausente, produzirá o valor de resultado da expressão onNull fornecida. Esse valor de resultado pode ser de qualquer tipo.

Se você não especificar onNull e dateString estiver null ou ausente, então $dateFromString entregará null.

Dica

Veja também:

Exemplo
Resultados
{ $dateFromString: {
dateString: "2017-02-08T12:10:40.787"
} }
ISODate("2017-02-08T12:10:40.787Z")
{ $dateFromString: {
dateString: "2017-02-08T12:10:40.787",
timezone: "America/New_York"
} }
ISODate("2017-02-08T17:10:40.787Z")
{ $dateFromString: {
dateString: "2017-02-08"
} }
ISODate("2017-02-08T00:00:00Z")
{ $dateFromString: {
dateString: "oct 20 2020"
} }
ISODate("2020-10-20T00:00:00.000Z")
{ $dateFromString: {
dateString: "06-15-2018",
format: "%m-%d-%Y"
} }
ISODate("2018-06-15T00:00:00Z")
{ $dateFromString: {
dateString: "15-06-2018",
format: "%d-%m-%Y"
} }
ISODate("2018-06-15T00:00:00Z")
{ $dateFromString: {
dateString: "WED jan 31 12:05:28 +03:30 1996"
} }
ISODate("1996-01-31T08:35:28.000Z")

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
%

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

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

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

Voltar

$dateFromParts