$year (Obter Ano)

Última atualização: 2026-10-09

$year (Obter Ano)

$year retorna o ano completo de uma data (ex.: 2026) — o extrator de data mais básico. Frequentemente combina com $month ou $week em chaves de agrupamento de múltiplos níveis, ou serve para arquivamento anual e análises ano a ano. Retorna um inteiro. Observe a diferença para $isoWeekYear, que retorna o ano da semana ISO e pode diferir em semanas que atravessam anos — prefira-o para estatísticas semanais.

📝 Sintaxe

{ $year: { date: <expressão de data>, timezone: <fuso horário> } }

⚙️ Parâmetros

Retorno：O ano como inteiro; null se date for null.

▶ Exemplo

Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):

// $year: totais de pedidos por ano
db.orders.aggregate([
  { $group: {
      _id: { $year: { date: '$orderDate' } },
      total: { $sum: '$amount' }
  } }
])

Saída：

{ "_id": 2026, "total": 892000 }
{ "_id": 2025, "total": 764000 }

📌 Notas

• Retorna o ano completo de quatro dígitos
• Registros com data null caem em um bucket null ao agrupar
• Use $isoWeekYear, não $year, para estatísticas de semanas que atravessam anos

🏷️ Tags Relacionados

💡 Casos Relacionados

📚 Tutoriais Relacionados

❓ Perguntas Frequentes

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós