No MongoDB, o
$isoWeekYear
operador de pipeline de agregação retorna o ano de numeração de semana ISO para um determinado valor de data. Este é o número do ano no formato ISO 8601. Ao usar o
$isoWeekYear
operador, você pode especificar opcionalmente um fuso horário a ser usado para o resultado. O
$isoWeekYear
O operador aceita uma data (como Date, Timestamp ou ObjectId) ou um documento que especifica a data e o fuso horário a serem usados. Exemplo
Suponha que tenhamos uma coleção chamada
cats
com o seguinte documento:{ "_id" : ObjectId("6008c9a5c8eb4369cf6ad9cc"), "name" : "Scratch", "born" : ISODate("2021-01-03T23:30:15.123Z") }
Podemos executar o seguinte código para extrair o ano ISO do
born
campo nesse documento. db.cats.aggregate(
[
{
$project:
{
_id: 0,
birthIsoWeekYear: { $isoWeekYear: "$born" }
}
}
]
)
Resultado:
{ "birthIsoWeekYear" : NumberLong(2020) }
Podemos ver que o ano ISO é na verdade 2020, mesmo que a data especifique 2021. Isso ocorre porque o ano ISO não termina até que a última semana termine. E neste caso, a semana começou no final do ano anterior e ainda não terminou. É assim que os anos ISO funcionam.
Aqui, usei
birthIsoWeekYear
como o nome do campo a ser retornado, mas pode ser qualquer coisa (como isoWeekYear
, isoYear
, etc). O
_id
campo é retornado por padrão ao usar projeções no MongoDB, mas neste exemplo eu escondi explicitamente o _id
campo usando _id: 0
. Especificar um fuso horário
Você pode especificar um fuso horário a ser usado para a saída do
$isoWeekYear
operador. Quando você faz isso, o argumento é passado para
$isoWeekYear
deve ter a seguinte forma:{ date: <dateExpression>, timezone: <tzExpression> }
Onde
<dateExpression>
é a data a ser usada e <tzExpression>
é o fuso horário a ser usado. O fuso horário pode ser especificado usando o identificador de fuso horário Olson (por exemplo,
"Europe/London"
, "GMT"
) ou o deslocamento UTC (por exemplo, "+02:30"
, "-1030"
). Identificador de fuso horário Olson
Aqui está um exemplo que gera o ano ISO em dois fusos horários diferentes, cada um usando os IDs de fuso horário Olson:
db.cats.aggregate(
[
{
$project: {
_id: 0,
honolulu: {
$isoWeekYear: { date: "$born", timezone: "Pacific/Honolulu" }
},
auckland: {
$isoWeekYear: { date: "$born", timezone: "Pacific/Auckland" }
}
}
}
]
)
Resultado:
{ "honolulu" : NumberLong(2020), "auckland" : NumberLong(2021) }
Nesse caso, a data avança para o próximo ano ISO ao usar o
Pacific/Auckland
fuso horário. Deslocamento UTC
Aqui está o mesmo exemplo, exceto que desta vez usamos o deslocamento UTC.
db.cats.aggregate(
[
{
$project: {
_id: 0,
"utcOffset-1000": {
$isoWeekYear: { date: "$born", timezone: "-1000" }
},
"utcOffset+1200": {
$isoWeekYear: { date: "$born", timezone: "+1200" }
}
}
}
]
)
Resultado:
{ "utcOffset-1000" : NumberLong(2020), "utcOffset+1200" : NumberLong(2021) }
Retorne o ano ISO de um ObjectId
Você pode usar
$isoWeekYear
para retornar a parte do ano ISO de um ObjectId. Os valores ObjectId são valores hexadecimais de 12 bytes que consistem em:
- Um valor de carimbo de data/hora de 4 bytes, representando a criação do ObjectId, medido em segundos desde a época do Unix.
- Um valor de 5 bytes é aleatório
- Um contador de incremento de 3 bytes, inicializado com um valor aleatório.
Para recapitular, nosso documento se parece com isso:
{ "_id" : ObjectId("6008c9a5c8eb4369cf6ad9cc"), "name" : "Scratch", "born" : ISODate("2021-01-03T23:30:15.123Z") }
Este documento contém um ObjectId. Podemos, portanto, usar
$isoWeekYear
para retornar o ano ISO em que nosso documento foi criado (ou mais especificamente, quando o _id
valor ObjectId do campo foi criado). Exemplo:
db.cats.aggregate(
[
{
$project:
{
"timeStamp": { $toDate: "$_id"},
"isoWeekYear": { $isoWeekYear: "$_id" }
}
}
]
).pretty()
Resultado:
{ "_id" : ObjectId("6008c9a5c8eb4369cf6ad9cc"), "timeStamp" : ISODate("2021-01-21T00:24:05Z"), "isoWeekYear" : NumberLong(2021) }
Podemos ver que o documento foi criado no ano ISO 2021.
Nesse caso, também usei o
$toDate
operador de pipeline de agregação para retornar a parte de carimbo de data/hora do ObjectId. Sobre o sistema de datas semanais ISO
O sistema de data da semana ISO é um sistema de calendário que faz parte do padrão de data e hora ISO 8601 emitido pela International Organization for Standardization (ISO). O sistema especifica um ano da semana em cima do calendário gregoriano, definindo uma notação para semanas ordinais do ano.
Os anos de numeração de semanas ISO têm 52 ou 53 semanas completas. Isso significa que há 364 ou 371 dias no ano, em vez dos 365 ou 366 dias usuais.
As semanas ISO começam na segunda-feira. O ano de cada semana ISO é o ano gregoriano em que a quinta-feira cai. Os números da semana ISO começam em
1
com a semana que contém a primeira quinta-feira do ano.