$isoWeek (aggregation)
On this page
Definition
$isoWeek
New in version 3.4.
Returns the week number in ISO 8601 format, ranging from
1
to53
. Week numbers start at1
with the week (Monday through Sunday) that contains the year's first Thursday.The
$isoWeek
expression has the following operator expression syntax:{ $isoWeek: <dateExpression> } The argument can be:
An expression that resolves to a Date, a Timestamp, or an ObjectID.
A document with this format:
{ date: <dateExpression>, timezone: <tzExpression> } FieldDescriptiondate
The date to which the operator is applied.<dateExpression>
must be a valid expression that resolves to a Date, a Timestamp, or an ObjectID.timezone
Optional.
The timezone of the operation result.<tzExpression>
must be a valid expression that resolves to a string formatted as either an Olson Timezone Identifier or a UTC Offset. If notimezone
is provided, the result is displayed inUTC
.Note
Etc/ Timezones
Etc/*
timezones are supported starting in MongoDB 5.0.4. In earlier versions of MongoDB, use alternative timezone designations. For example, useUTC
instead ofEtc/UTC
.FormatExamplesOlson Timezone Identifier
"America/New_York" "Europe/London" "GMT" UTC Offset
+/-[hh]:[mm], e.g. "+04:45" +/-[hh][mm], e.g. "-0530" +/-[hh], e.g. "+03"
Behavior
Example | Result | ||||
---|---|---|---|---|---|
| 1 | ||||
| 53 | ||||
| 32 | ||||
| 45 | ||||
| 44 | ||||
| error | ||||
| error | ||||
| error |
Note
$isoWeek cannot take a string as an argument.
Example
A collection called deliveries
contains the following documents:
{ "_id" : 1, "date" : ISODate("2006-10-24T00:00:00Z"), "city" : "Boston" } { "_id" : 2, "date" : ISODate("2011-08-18T00:00:00Z"), "city" : "Detroit" }
The following operation returns the week number for each date
field.
db.deliveries.aggregate( [ { $project: { _id: 0, city: "$city", weekNumber: { $isoWeek: "$date" } } } ] )
The operation returns the following results:
{ "city" : "Boston", "weekNumber" : 43 } { "city" : "Detroit", "weekNumber" : 33 }