In MongoDB, the $isoDayOfWeek aggregation pipeline operator returns the weekday number in ISO 8601 format, ranging from 1 (for Monday) to 7 (for Sunday).

You can optionally specify a timezone to use for the result.

The $isoDayOfWeek operator accepts either a date (as either a Date, a Timestamp, or an ObjectId), or a document that specifies the date and timezone to use.

Example

Suppose we have a collection called pets with the following document:

{
	"_id" : ObjectId("600631c7c8eb4369cf6ad9c8"),
	"name" : "Fetch",
	"born" : ISODate("2020-12-31T23:30:15.123Z")
}

We can run the following code to extract the ISO day of the week from the born field in that document.

db.pets.aggregate(
  [
    {
      $project:
        {
          _id: 0,
          birthIsoDayOfWeek: { $isoDayOfWeek: "$born" }
        }
    }
  ]
)

Result:

{ "birthIsoDayOfWeek" : 4 } 

In this case we get a result of 4, which is a different result to what I get when using the $dayOfWeek operator against the same document.

Here, I used birthIsoDayOfWeek as the field name to return, but this could have been anything (such as isoDayOfWeek, day, etc).

The _id field is returned by default when using projections in MongoDB, but in this example I explicitly hid the _id field using _id: 0.

Specify a Timezone

You can specify a timezone to use for the output of the $isoDayOfWeek operator.

When you do this, the argument passed to $isoDayOfWeek must be of the following form:

{ date: <dateExpression>, timezone: <tzExpression> }

Where <dateExpression> is the date to use, and <tzExpression> is the timezone to use.

The timezone can be specified using either the Olson timezone identifier (e.g. "Europe/London", "GMT") or the UTC offset (e.g. "+02:30", "-1030").

Olson Timezone Identifier

Here’s an example that outputs the day in two different timezones, each using the Olson timezone IDs:

db.pets.aggregate(
  [
    {
      $project: {
          _id: 0,
          honolulu: { 
            $isoDayOfWeek: { date: "$born", timezone: "Pacific/Honolulu" }
            },
          auckland: { 
            $isoDayOfWeek: { date: "$born", timezone: "Pacific/Auckland" }
            }
        }
    }
  ]
)

Result:

{ "honolulu" : 4, "auckland" : 5 }

UTC Offset

Here’s the same example, except this time we use the UTC offset.

db.pets.aggregate(
  [
    {
      $project: {
          _id: 0,
          "utcOffset-1000": { 
            $isoDayOfWeek: { date: "$born", timezone: "-1000" }
            },
          "utcOffset+1200": { 
            $isoDayOfWeek: { date: "$born", timezone: "+1200" }
            }
        }
    }
  ]
)

Result:

{ "utcOffset-1000" : 4, "utcOffset+1200" : 5 }

Return the Week Day from an ObjectId

You can use $isoDayOfWeek to return the ISO week day portion from an ObjectId.

ObjectId values are 12 byte hexadecimal values that consist of:

• A 4 byte timestamp value, representing the ObjectId’s creation, measured in seconds since the Unix epoch.
• A 5 byte is a random value
• A 3 byte incrementing counter, initialised to a random value.

To recap, our document looks like this:

{
	"_id" : ObjectId("600631c7c8eb4369cf6ad9c8"),
	"name" : "Fetch",
	"born" : ISODate("2020-12-31T23:30:15.123Z")
}

This document contains an ObjectId. We can therefore use $isoDayOfWeek to return the ISO day of the week that our document was created (or more specifically, when the _id field’s ObjectId value was created).

Example:

db.pets.aggregate(
  [
    {
      $project:
        {
          "timeStamp": { $toDate: "$_id"},
          "isoDayOfWeek": { $isoDayOfWeek: "$_id" }
        }
    }
  ]
).pretty()

Result:

{
	"_id" : ObjectId("600631c7c8eb4369cf6ad9c8"),
	"timeStamp" : ISODate("2021-01-19T01:11:35Z"),
	"isoDayOfWeek" : 2
}

We can see that the document was created on the 2nd day of the week when using the ISO 8601 format.

In this case, I also used the $toDate aggregation pipeline operator to return the timestamp portion of the ObjectId.