$dateTrunc (Truncar Data)
Última atualização: 2026-10-09
$dateTrunc (Truncar Data)
$dateTrunc trunca uma data para o início de uma determinada unidade e retorna a nova data — perfeito para alinhar timestamps em intervalos de hora/dia/mês para estatísticas. A unidade suporta year (ano), quarter (trimestre), month (mês), week (semana), day (dia), hour (hora), minute (minuto) e second (segundo); binSize amplia o intervalo (ex.: intervalos de 3 horas). startOfWeek se aplica apenas a week. timezone conduz o calendário usado para a truncagem — defina-o explicitamente entre fusos. Introduzido no MongoDB 5.0.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 5.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dateTrunc: { date: <expressão de data>, unit: <unidade>, binSize: <número>, timezone: <fuso horário>, startOfWeek: <início da semana> } }⚙️ Parâmetros
| date | Obrigatório; a data a truncar. |
|---|---|
| unit | Obrigatório; unidade de truncamento: year, quarter, month, week, day, hour, minute, second. |
| binSize | Tamanho de bucket opcional que amplia a unidade. |
| timezone | Fuso horário opcional para o truncamento. |
| startOfWeek | Opcional; aplica-se apenas quando unit é week. |
Retorno：A data truncada (BSON Date); null se date for null ou estiver ausente.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $dateTrunc: agregar vendas por hora
db.sales.aggregate([
{ $group: {
_id: { $dateTrunc: { date: '$soldAt', unit: 'hour' } },
total: { $sum: '$amount' }
} }
])Saída：
{ "_id": ISODate("2026-09-25T08:00:00Z"), "total": 1250 }
{ "_id": ISODate("2026-09-25T09:00:00Z"), "total": 980 }📌 Notas
- O resultado é sempre um início de unidade: day dá 00:00, hour dá o início da hora
- binSize suporta minute, hour, day, week, month, quarter, year
- quarter divide o ano em 4; o resultado é o primeiro dia do trimestre
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença para $dateAdd?
A$dateTrunc apenas alinha a um início de unidade; $dateAdd move o horário.
QO que binSize significa?
AEle amplia a unidade em intervalos — binSize 3 com unidade hour dá intervalos de 3 horas.
QQue horário tem o resultado?
Aday dá 00:00 daquele dia; hour dá o início da hora.
