From 051f70f6ff35324b7877ef8e44a2b613c5a3f5b6 Mon Sep 17 00:00:00 2001
From: Andrew Aldridge <i80and@foxquill.com>
Date: Tue, 21 Oct 2014 10:23:39 -0400
Subject: [PATCH] DOCS-3576: Timezone offset in aggregation example

---
 config/htaccess.yaml                          |  7 ++
 source/includes/toc-aggregation-examples.yaml |  4 +
 source/tutorial/aggregation-time-zone.txt     | 74 +++++++++++++++++++
 source/tutorial/model-time-data.txt           |  2 +
 4 files changed, 87 insertions(+)
 create mode 100644 source/tutorial/aggregation-time-zone.txt

diff --git a/config/htaccess.yaml b/config/htaccess.yaml
index 690103f2b52..3b8a2245f1a 100644
--- a/config/htaccess.yaml
+++ b/config/htaccess.yaml
@@ -4799,6 +4799,13 @@ code: 301
 outputs:
   - 'before-v2.4'
 ---
+from: '/tutorial/aggregation-time-zone'
+to: '/applications/aggregation'
+type: 'redirect'
+code: 301
+outputs:
+  - 'before-v2.4'
+---
 from: '/reference/method/db.getCmdLineOpts'
 to: '/reference/method/js-database'
 type: 'redirect'
diff --git a/source/includes/toc-aggregation-examples.yaml b/source/includes/toc-aggregation-examples.yaml
index c2260b023d9..2d74d302933 100644
--- a/source/includes/toc-aggregation-examples.yaml
+++ b/source/includes/toc-aggregation-examples.yaml
@@ -26,4 +26,8 @@ description: |
 file: /tutorial/troubleshoot-reduce-function
 description: |
   Steps to troubleshoot the ``reduce`` function.
+---
+file: /tutorial/aggregation-time-zone
+description: |
+  Apply time zone offsets in aggregation for time zone-aware grouping.
 ...
diff --git a/source/tutorial/aggregation-time-zone.txt b/source/tutorial/aggregation-time-zone.txt
new file mode 100644
index 00000000000..8916fa94db4
--- /dev/null
+++ b/source/tutorial/aggregation-time-zone.txt
@@ -0,0 +1,74 @@
+===========================
+Time Zones with Aggregation
+===========================
+
+.. default-domain:: mongodb
+
+When aggregating over time data in MongoDB, you must apply time zone offsets
+in your aggregation pipeline if you need time zone-aware results.
+
+Data Model
+----------
+
+Consider a factory that tracks its product sales using MongoDB, and wishes to
+create year-end reports of total sales by month. To accomplish this, they model their
+time data within a ``sales`` collection as discussed in :ref:`model-time-data`.
+
+Each document in this collection has the following form:
+
+.. code-block:: javascript
+
+   {
+     "_id": ObjectId("54456e0f713543c11e4fb6b5"),
+     "time": ISODate("2014-10-21T18:46:01.537Z"),
+     "offset": 240,
+     "qty": 2
+   }
+
+The ``_id`` field is an automatically-generated ObjectId.
+
+The ``time`` field holds the date and time in which this sale occurred, in UTC.
+
+The ``offset`` field holds the offset from UTC in minutes in which this sale occurred.
+
+The ``qty`` field holds the number of products sold in this transaction.
+
+All of the following examples use the :method:`aggregate()
+<db.collection.aggregate()>` helper in the :program:`mongo`
+shell. :method:`aggregate() <db.collection.aggregate()>` provides a
+wrapper around the :dbcommand:`aggregate` database command. See the
+documentation for your :doc:`driver </applications/drivers>` for a
+more idiomatic interface for data aggregation operations.
+
+Year-End Report
+---------------
+
+To generate a summary of sales by month, use the following query:
+
+.. code-block:: javascript
+
+   db.sales.aggregate(
+       [ { $project: { _id: 1,
+                       time: { $add : [ "$time",
+                                        { $multiply: [ -60000, "$offset" ] } ] } } },
+         { $group : { _id : { $month : "$time" }, count : { $sum : 1 } } } ] )
+
+This query's :pipeline:`projection <$project>` stage converts the ``offset``
+field into hours, and subtracts it from the ``time`` field. This handles the
+case where a customer makes a purchase after the month cutoff in UTC, but in
+the previous month within the customer's time zone.
+
+For example, in the following document, ``time`` represents a date in the month
+of November. However, after applying the offset, it becomes a date in October.
+
+.. code-block:: javascript
+
+   {
+     "_id": ObjectId("54456e0f713543c11e4fb6b5"),
+     "time": ISODate("2014-11-01T02:00:00.000Z"),
+     "offset": 240,
+     "qty": 2
+   }
+
+Without adjusting for time zone, a local business's report of monthly sales
+would have grouped this sale into the next month's transactions.
diff --git a/source/tutorial/model-time-data.txt b/source/tutorial/model-time-data.txt
index 1899d50b755..40dffe8f165 100644
--- a/source/tutorial/model-time-data.txt
+++ b/source/tutorial/model-time-data.txt
@@ -1,3 +1,5 @@
+.. _model-time-data:
+
 ===============
 Model Time Data
 ===============