dayOfYear.txt

========================
$dayOfYear (aggregation)
========================

.. default-domain:: mongodb

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

Definition
----------

.. expression:: $dayOfYear

   Returns the day of the year for a date as a number between 1 and 366.

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

   .. code-block:: javascript

      { $dayOfYear: <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

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

     - 1

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

          { $dayOfYear: { date: new Date("Jan 7, 2003") } }

     - 7

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

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

     - 226

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

          { $dayOfYear: ISODate("1998-11-07T00:00:00Z") }

     - 311

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

          { $dayOfYear: {
              date: ISODate("1998-11-07T00:00:00Z"),
              timezone: "-0400"
          } }

     - 310

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

          { $dayOfYear: "March 28, 1976" }

     - ``error``

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

          { $dayOfYear: Date("2016-01-01") }

     - ``error``

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

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

     - ``error``

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

Example
-------

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

.. class:: copyable-code
.. 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:`$dayOfYear` and other date
expressions to break down the ``date`` field:

.. class:: copyable-code
.. code-block:: javascript
   :emphasize-lines: 13

   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
   }