$dateAdd (Adicionar a uma Data)
Última atualização: 2026-10-09
$dateAdd (Adicionar a uma Data)
$dateAdd adiciona uma quantidade especificada de uma unidade de tempo a uma data e retorna a nova data — o operador essencial para datas relativas em pipelines (datas de vencimento, datas de renovação, prazos). A unidade suporta year (ano), month (mês), week (semana), day (dia), hour (hora), minute (minuto), second (segundo) e millisecond (milissegundo); o valor de amount pode ser negativo, equivalendo a subtração. Com timezone, você pode calcular usando o calendário de um fuso horário específico para limites precisos de mês/ano. Funciona em $project, $addFields, $set e expressões aninhadas.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 5.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dateAdd: { startDate: <expressão de data>, unit: <unidade>, amount: <número>, timezone: <fuso horário> } }⚙️ Parâmetros
| startDate | A data a modificar; um Date, timestamp ou expressão que resolva para data. |
|---|---|
| unit | A unidade: year, month, week, day, hour, minute, second ou millisecond. |
| amount | A quantidade a adicionar; positiva soma, negativa subtrai; fora do intervalo de inteiro de 64 bits lança erro. |
| timezone | Fuso horário opcional para o cálculo; nome IANA (ex.: Asia/Shanghai) ou deslocamento UTC. |
Retorno：A nova data (BSON Date); null se startDate for null ou estiver ausente.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $dateAdd: a data de vencimento é 30 dias após a criação (horário de Pequim)
db.orders.aggregate([
{ $project: {
dueDate: { $dateAdd: { startDate: '$createdAt', unit: 'day', amount: 30, timezone: 'Asia/Shanghai' } }
} }
])Saída：
{ "_id": 1, "dueDate": ISODate("2026-10-25T00:00:00Z") }
{ "_id": 2, "dueDate": ISODate("2026-11-15T00:00:00Z") }📌 Notas
- Apenas as 8 unidades acima são suportadas; amount além do intervalo de int64 gera erro
- startDate null/ausente resulta em null — proteja com $ifNull
- A aritmética de meses trunca para os dias do mês resultante (31 de janeiro mais 1 mês = último dia de fevereiro)
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
