$dateFromString (Analisar String para Data)
Última atualização: 2026-10-09
$dateFromString (Analisar String para Data)
$dateFromString analisa uma string em uma data usando um formato fornecido — a inversa de $dateToString, útil para converter strings de data importadas ou vindas do front-end em Date BSON. format usa os mesmos marcadores de $dateToString (%Y, %m, %d...); sem ele, assume-se ISO 8601. onError fornece um valor de substituição quando a análise falha, onNull quando a entrada é null. timezone decide qual zona se aplica quando a string não traz informação de zona.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dateFromString: { dateString: <string>, format: <formato>, timezone: <fuso horário>, onError: <padrão>, onNull: <padrão> } }⚙️ Parâmetros
| dateString | Obrigatório; a string de data a analisar. |
|---|---|
| format | Padrão de formato opcional; o padrão é ISO 8601. |
| timezone | Fuso horário opcional aplicado quando a string não tem informação de fuso. |
| onError / onNull | Fallbacks opcionais para falha de análise e entrada null. |
Retorno：O BSON Date analisado; onError em caso de falha (lança por padrão), onNull para entrada null (null por padrão).
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $dateFromString: analisar timestamps de log importados (horário de Pequim)
db.imports.aggregate([
{ $project: {
createdAt: { $dateFromString: { dateString: '$ts', format: '%Y-%m-%d %H:%M', timezone: 'Asia/Shanghai' } }
} }
])Saída：
{ "_id": 1, "createdAt": ISODate("2026-09-25T08:30:00Z") }
{ "_id": 2, "createdAt": ISODate("2026-09-25T09:00:00Z") }📌 Notas
- Sem format, assume-se ISO 8601; marcadores como %z analisam offsets de zona
- Falha de análise gera erro por padrão — sempre defina onError em produção
- Strings sem informação de zona seguem timezone, que tem UTC como padrão
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QComo analisar strings com formatos variados?
ASem format, tenta-se ISO 8601; quando o formato é fixo, passe format explicitamente.
QA falha de análise gera erro?
ASim, a menos que onError forneça um valor de substituição.
QQual é a diferença para $toDate?
A$toDate é uma conversão de tipo flexível; $dateFromString controla formato e fuso horário com precisão.
