$dayOfYear (Obter Dia do Ano)
Última atualização: 2026-10-09
$dayOfYear (Obter Dia do Ano)
$dayOfYear retorna o dia do ano de uma data (1 a 366) — útil para progresso anual, análise sazonal ou cálculos de dias restantes. A contagem começa em 1; um ano comum termina em 365, um ano bissexto em 366. Ele calcula em UTC ou no fuso horário informado, e o limite muda entre fusos, então passe timezone explicitamente. Combine com o marcador %j de $dateToString para uma string de três dígitos com zero à esquerda.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $dayOfYear: { date: <expressão de data>, timezone: <fuso horário> } }⚙️ Parâmetros
| date | Obrigatório; a expressão de data. |
|---|---|
| timezone | Fuso horário opcional; o padrão é UTC. |
Retorno：Dia do ano (1-366) como inteiro; null se date for null.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $dayOfYear: dia do ano dos eventos
db.events.aggregate([
{ $project: {
doy: { $dayOfYear: '$eventDate' },
label: { $dateToString: { format: '%j', date: '$eventDate' } }
} }
])Saída：
{ "_id": 1, "doy": 268, "label": "268" }
{ "_id": 2, "doy": 1, "label": "001" }📌 Notas
- 1º de janeiro é 1; 31 de dezembro é 365 em ano comum, 366 em ano bissexto
- Use %j para uma string de três dígitos com zero à esquerda
- Os limites seguem UTC/fuso horário como $week — unifique fusos antes das estatísticas
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é o máximo anual?
A365 em um ano comum, 366 em um ano bissexto.
QQual é a diferença para $dayOfMonth?
A$dayOfMonth é o dia dentro do mês; $dayOfYear é o dia dentro do ano.
QComo obter uma string de três dígitos?
AUse o marcador %j de $dateToString, que preenche com zeros.
