MongoDB provides various options for extracting date parts from a date.

This article presents 3 ways to return the week portion from a date in MongoDB.

Sample Data

Suppose we have a collection called cats with the following documents:

{ "_id" : 1, "name" : "Scratch", "born" : ISODate("2021-01-03T23:30:15.123Z") }
{ "_id" : 2, "name" : "Meow", "born" : ISODate("2019-12-08T04:00:12Z") }
{ "_id" : 3, "name" : "Fluffy", "born" : ISODate("2020-09-24T10:30:00Z") }

The following examples demonstrate various options for returning the week portion from the born field of those documents.

The $week Operator

The $week operator returns the week of the year for a date as a number between 0 and 53.

We can therefore run the following code to return the week from the born field in the above document.

db.cats.aggregate(
  [
    {
      $project:
        {
          _id: 0,
          birthWeek: { $week: "$born" }
        }
    }
  ]
)

Result:

{ "birthWeek" : 1 }
{ "birthWeek" : 49 }
{ "birthWeek" : 38 }

You can also specify the timezone when using the $week operator.

See MongoDB $week for more information and examples.

The $dateToString Operator

The $dateToString operator converts a date object to a string according to a user-specified format. The user can therefore specify that just the week portion is returned if required.

There are format specifiers for each date part. With regards to the week portion of the date, the %U format specifier returns the week of the year, and the %V format specifier returns the week of the year in ISO 8601 format.

Example:

db.cats.aggregate(
   [
     {
       $project: {
         _id: 0,
          birthWeek: { $dateToString: { format: "%U", date: "$born" } },
          birthWeekISO: { $dateToString: { format: "%V", date: "$born" } }
       }
     }
   ]
)

Result:

{ "birthWeek" : "01", "birthWeekISO" : "53" }
{ "birthWeek" : "49", "birthWeekISO" : "49" }
{ "birthWeek" : "38", "birthWeekISO" : "39" }

See MongoDB $dateToString for more information and examples.

Also see MongoDB $dateToString Format Specifiers for a list of format specifiers that can be used with this operator.

The $isoWeek Operator

If you need to return the week in ISO 8601 format, use $isoWeek. The ISO 8601 year starts with the Monday of week 1 and ends with the Sunday of the last week.

Example:

db.cats.aggregate(
  [
    {
      $project:
        {
          _id: 0,
          birthIsoWeek: { $isoWeek: "$born" }
        }
    }
  ]
)

Result:

{ "birthIsoWeek" : 53 }
{ "birthIsoWeek" : 49 }
{ "birthIsoWeek" : 39 }

This result is different to when we used the $week operator.

Here’s an example that shows the difference.

db.cats.aggregate(
  [
    {
      $project:
        {
          _id: 0,
          birthWeek: { $week: "$born" },
          birthIsoWeek: { $isoWeek: "$born" }
        }
    }
  ]
)

Result:

{ "birthWeek" : 1, "birthIsoWeek" : 53 }
{ "birthWeek" : 49, "birthIsoWeek" : 49 }
{ "birthWeek" : 38, "birthIsoWeek" : 39 }