$isoWeekYear (aggregation)¶

On this page

Definition¶

$isoWeekYear¶

New in version 3.4.

Returns the year number in ISO 8601 format. The year starts with the Monday of week 1 (ISO 8601) and ends with the Sunday of the last week (ISO 8601).

$isoWeekYear has the following operator expression syntax:

{ $isoWeekYear: <date expression> }

The argument can be any valid expression that resolves to a BSON ISODate object, a BSON Timestamp object, or a Date object.

Behavior¶

Example	Result
`{ $isoWeekYear: new Date("2016-01-01") }`	2015
`{ $isoWeekYear: new Date("2015-01-01") }`	2015
`{ $isoWeekYear: new Date("2016-01-04") }`	2016
`{ $isoWeekYear: "2016-01-01" }`	`error`

Note

$isoWeekYear cannot take a string as an argument.

Example¶

A collection called anniversaries contains the following documents:

{ "_id" : 1, "date" : ISODate("2016-01-01T00:00:00Z") }
{ "_id" : 2, "date" : ISODate("2016-01-04T00:00:00Z") }
{ "_id" : 3, "date" : ISODate("2015-01-01T00:00:00Z") }
{ "_id" : 4, "date" : ISODate("2014-04-21T00:00:00Z") }

The following operation returns the year number in ISO 8601 format for each date field.

db.anniversaries.aggregate( [
  {
    $project: {
      yearNumber: { $isoWeekYear: "$date" }
    }
  }
] )

The operation returns the following results:

{ "_id" : 1, "yearNumber" : 2015 }
{ "_id" : 2, "yearNumber" : 2016 }
{ "_id" : 3, "yearNumber" : 2015 }
{ "_id" : 4, "yearNumber" : 2014 }