$isoWeekYear (Ano da Semana ISO)
Última atualização: 2026-10-09
$isoWeekYear (Ano da Semana ISO)
$isoWeekYear retorna o ano ao qual pertence a semana ISO de uma data, usado com $isoWeek. Como as semanas ISO podem atravessar anos (31 de dezembro pode cair na semana 1 do ano seguinte), o ano da semana pode diferir do ano de calendário — apenas $isoWeekYear dá a atribuição correta. Uso típico: construir uma chave de agrupamento ano-semana. timezone define o limite da semana.
| Categoria | Data |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $isoWeekYear: { 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：O ano da semana ISO; null se date for null.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $isoWeekYear + $isoWeek: agrupamento ano-semana
db.sales.aggregate([
{ $group: {
_id: { y: { $isoWeekYear: { date: '$soldAt' } }, w: { $isoWeek: { date: '$soldAt' } } },
total: { $sum: '$amount' }
} }
])Saída：
{ "_id": { "y": 2026, "w": 39 }, "total": 9800 }
{ "_id": { "y": 2026, "w": 40 }, "total": 10450 }📌 Notas
- Perto dos limites de ano, o ano da semana ISO pode diferir do ano de calendário em 1
- Use junto com $isoWeek; sozinho tem pouco valor
- O padrão é UTC — unifique o fuso horário antes das estatísticas
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença para $year?
A$year é o ano de calendário; $isoWeekYear é o ano ISO da semana — eles podem diferir em semanas que atravessam anos.
QQuando preciso dele?
APara agrupamento ano-semana, combine $isoWeekYear com $isoWeek como chave.
QÉ útil sozinho?
ANão muito — ele só expressa a atribuição da semana junto com $isoWeek.
