$dateDiff (Diferença de Datas)
Última atualização: 2026-10-09
$dateDiff (Diferença de Datas)
$dateDiff calcula a diferença entre duas datas em uma determinada unidade como um inteiro — ideal para idades, durações de assinaturas ou tempos de permanência. A unidade suporta year (ano), month (mês), week (semana), day (dia), hour (hora), minute (minuto), second (segundo) e millisecond (milissegundo); os resultados são truncados em limites de unidade completa (year conta apenas anos completos). startOfWeek define o início da semana e se aplica apenas quando a unidade é week. timezone conduz o calendário usado; sempre defina-o entre fusos.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 5.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dateDiff: { startDate: <expressão de data>, endDate: <expressão de data>, unit: <unidade>, timezone: <fuso horário>, startOfWeek: <início da semana> } }⚙️ Parâmetros
| startDate / endDate | Obrigatório; as datas de início e fim. |
|---|---|
| unit | Obrigatório; a unidade da diferença (as 8 unidades acima). |
| timezone | Fuso horário opcional para o cálculo. |
| startOfWeek | Opcional; aplica-se apenas quando unit é week; valores como Monday, Sunday. |
Retorno：A diferença inteira (endDate menos startDate); null se qualquer data for null.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $dateDiff: calcular a idade em anos
db.users.aggregate([
{ $project: {
ageYears: { $dateDiff: { startDate: '$birthDate', endDate: '$$NOW', unit: 'year' } }
} }
])Saída：
{ "_id": 1, "ageYears": 28 }
{ "_id": 2, "ageYears": 31 }📌 Notas
- O resultado é endDate menos startDate e pode ser negativo
- Unidades maiores truncam em limites completos: year conta apenas anos completos
- startOfWeek se aplica apenas à unidade week; valores de Monday a Sunday
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO resultado tem casas decimais?
ANão — $dateDiff retorna inteiros, truncados nos limites da unidade.
QA diferença pode ser negativa?
ASim — negativa quando endDate é anterior a startDate.
QComo contar dias entre duas datas?
ADefina a unidade como day; observe que timezone desloca os limites do dia de calendário.
