$dateSubtract (Subtrair de uma Data)
Última atualização: 2026-10-09
$dateSubtract (Subtrair de uma Data)
$dateSubtract subtrai uma quantidade especificada de uma unidade de tempo de uma data e retorna a nova data — o espelho de $dateAdd. Ótimo para expiração de assinaturas, datas de início de cupons ou janelas de retenção. A unidade suporta year (ano), month (mês), week (semana), day (dia), hour (hora), minute (minuto), second (segundo) e millisecond (milissegundo); amount negativo equivale a adição. timezone é opcional e define o calendário usado. Como $dateAdd, funciona em $project, $set e outros estágios; data null/ausente resulta em null.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 5.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dateSubtract: { startDate: <expressão de data>, unit: <unidade>, amount: <número>, timezone: <fuso horário> } }⚙️ Parâmetros
| startDate | A data da qual subtrair; um Date, timestamp ou expressão de data. |
|---|---|
| unit | A unidade: year, month, week, day, hour, minute, second ou millisecond. |
| amount | A quantidade a subtrair; positiva subtrai, negativa soma; fora do intervalo int64 lança erro. |
| timezone | Fuso horário opcional para o cálculo. |
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):
// $dateSubtract: lembrar 3 dias antes do vencimento (UTC+8)
db.orders.aggregate([
{ $project: {
remindAt: { $dateSubtract: { startDate: '$dueDate', unit: 'day', amount: 3, timezone: '+08:00' } }
} }
])Saída：
{ "_id": 1, "remindAt": ISODate("2026-10-22T00:00:00Z") }
{ "_id": 2, "remindAt": ISODate("2026-11-12T00:00:00Z") }📌 Notas
- Parâmetros idênticos aos de $dateAdd, direção oposta
- A aritmética de meses também trunca para os dias do mês resultante
- Os resultados podem ser anteriores a 1970; a Date BSON suporta timestamps negativos
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QComo $dateSubtract e $dateAdd se relacionam?
AMesmos parâmetros, direção oposta; valores negativos os tornam equivalentes.
QO resultado pode ser anterior a 1970?
ASim — a Date BSON suporta timestamps negativos anteriores a 1970.
QQual é a diferença para $dateDiff?
A$dateSubtract retorna uma nova data; $dateDiff retorna uma diferença inteira.
