month.txt

====================
$month (aggregation)
====================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. expression:: $month

   Returns the month of a date as a number between 1 and 12.

   The :expression:`$month` expression has the following
   :ref:`operator expression syntax <aggregation-expressions>`:

   .. code-block:: javascript

      { $month: <dateExpression> }

   .. include:: /includes/fact-iso-date-objects.rst

Behavior
--------

.. list-table::
   :header-rows: 1
   :widths: 90 10
   :class: border-table

   * - Example
     - Result

   * - .. code-block:: javascript
          :copyable: false

          { $month: new Date("2016-01-01") }

     - 1

   * - .. code-block:: javascript
          :copyable: false

          { $month: { date: new Date("Nov 7, 2003") } }

     - 11

   * - .. code-block:: javascript
          :copyable: false

          { $month: ISODate("2000-01-01T00:00:00Z") }

     - 1

   * - .. code-block:: javascript
          :copyable: false

          { $month: {
              date: new Date("August 14, 2011"),
              timezone: "America/Chicago"
          } }

     - 8


   * - .. code-block:: javascript
          :copyable: false

          { $month: {
              date: ISODate("2000-01-01T00:00:00Z"),
              timezone: "-0500"
          } }

     - 12

   * - .. code-block:: javascript
          :copyable: false

          { $month: "March 28, 1976" }

     - ``error``

   * - .. code-block:: javascript
          :copyable: false

          { $month: {
              date: Date("2016-01-01"),
              timezone: "-0500"
          } }

     - ``error``

   * - .. code-block:: javascript
          :copyable: false

          { $month: "2009-04-09" }

     - ``error``

.. note:: ``$month`` cannot take a string as an argument.

Example
-------

Consider a ``sales`` collection with the following document:


.. code-block:: javascript

   {
     "_id" : 1,
     "item" : "abc",
     "price" : 10,
     "quantity" : 2,
     "date" : ISODate("2014-01-01T08:15:39.736Z")
   }

The following aggregation uses the :expression:`$month` and other
date operators to break down the ``date`` field:


.. code-block:: javascript
   :emphasize-lines: 7

   db.sales.aggregate(
      [
        {
          $project:
            {
              year: { $year: "$date" },
              month: { $month: "$date" },
              day: { $dayOfMonth: "$date" },
              hour: { $hour: "$date" },
              minutes: { $minute: "$date" },
              seconds: { $second: "$date" },
              milliseconds: { $millisecond: "$date" },
              dayOfYear: { $dayOfYear: "$date" },
              dayOfWeek: { $dayOfWeek: "$date" },
              week: { $week: "$date" }
            }
        }
      ]
   )

The operation returns the following result:

.. code-block:: javascript

   {
     "_id" : 1,
     "year" : 2014,
     "month" : 1,
     "day" : 1,
     "hour" : 8,
     "minutes" : 15,
     "seconds" : 39,
     "milliseconds" : 736,
     "dayOfYear" : 1,
     "dayOfWeek" : 4,
     "week" : 0
   }