$dateToString (Formatar Data)
Última atualização: 2026-10-09
$dateToString (Formatar Data)
$dateToString formata uma data em uma string usando um padrão de formato — a maneira padrão de exibir datas em pipelines de agregação. O padrão usa marcadores como %Y (ano), %m (mês), %d (dia), %H (hora), semelhante ao strftime. Quando a data é null ou está ausente, retorna null, a menos que onNull forneça um valor padrão.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 3.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dateToString: { format: <formato>, date: <expressão de data>, timezone: <fuso horário>, onNull: <padrão> } }▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $dateToString: formatar datas de pedidos
db.orders.aggregate([
{ $project: {
dateStr: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } }
} }
])Saída：
{ "_id": 1, "dateStr": "2026-09-25" }
{ "_id": 2, "dateStr": "2026-09-24" }📌 Notas
- Marcadores: %Y ano com 4 dígitos, %m mês, %d dia, %H hora, %M minuto, %S segundo
- timezone é opcional, o padrão é UTC; aceita deslocamentos como "+08:00" ou zonas IANA como "Asia/Shanghai"
- Quando a data é null: retorna onNull se definido, caso contrário null
- MongoDB 6.3+ adiciona um modo abreviado de formato
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QComo especifico um fuso horário?
AUse nomes IANA (ex.: "Asia/Shanghai") ou deslocamentos de UTC (ex.: "+08:00"). O padrão é UTC.
QQuais especificadores de formato o $dateToString suporta?
AOs mais comuns incluem %Y (ano), %m (mês), %d (dia), %H (hora), %M (minuto), %S (segundo), %L (milissegundo), %z (deslocamento de UTC) e %j (dia do ano). Consulte a documentação oficial para a lista completa.
QO que acontece se o campo de data não for uma Date?
AEle espera uma Date; caso contrário, retorna null ou gera erro (dependendo do modo estrito). Converta com $toDate antes, se necessário.
QEle consegue gerar o formato ISO 8601?
ASim. Combine %Y-%m-%dT%H:%M:%S.%LZ para produzir algo como 2026-10-01T08:30:00.000Z; alternativamente use a expressão $isoDate.
