DOCS-686 incorporate comments from antoine and add the troubleshoot page

Author: kay-kim

source/applications/map-reduce.txt

@@ -4,37 +4,47 @@ Map-Reduce
 
 .. default-domain:: mongodb
 
-Map-reduce operations can handle complex aggregation
-tasks. [#simple-aggregation-use-framework]_ To perform map-reduce operations,
-MongoDB provides the :dbcommand:`mapReduce` command and, in the
-:program:`mongo` shell, the wrapper :method:`db.collection.mapReduce()`
-method.
+Map-reduce operations can handle complex aggregation tasks. To perform
+map-reduce operations, MongoDB provides the :dbcommand:`mapReduce`
+command and, in the :program:`mongo` shell, the
+:method:`db.collection.mapReduce()` wrapper method.
 
-This overview will cover:
+.. contents:: This overview will cover: 
+   :backlinks: none
+   :local:
+   :depth: 1
 
-- :ref:`map-reduce-method`
+For many simple aggregation tasks, see the :doc:`aggregation framework
+</applications/aggregation>`.
 
-- :ref:`map-reduce-examples`
-
-- :ref:`map-reduce-incremental`
-
-- :ref:`map-reduce-sharded-cluster`
+.. _map-reduce-examples:
 
-- :ref:`map-reduce-additional-references`
+Map-Reduce Examples
+-------------------
 
-.. _map-reduce-method:
+This section provides some map-reduce examples in the :program:`mongo`
+shell using the :method:`db.collection.mapReduce()` method:
 
-mapReduce()
------------
+.. code-block:: javascript
 
-.. include:: /reference/method/db.collection.mapReduce.txt
-   :start-after: mongodb
-   :end-before: mapReduce-syntax-end
+   db.collection.mapReduce(
+                            <map>,
+                            <reduce>,
+                            {
+                              <out>,
+                              <query>,
+                              <sort>,
+                              <limit>,
+                              <finalize>,
+                              <scope>,
+                              <jsMode>,
+                              <verbose>
+                            }
+                          )
+
+For more information on the parameters, see the
+:method:`db.collection.mapReduce()` reference page .
 
-.. _map-reduce-examples:
-
-Map-Reduce Examples
--------------------
 .. include:: /includes/examples-map-reduce.rst
    :start-after: map-reduce-examples-begin
    :end-before: map-reduce-sum-price-wrapper-end
@@ -140,10 +150,10 @@ each day and can be simulated as follows:
 
       var finalizeFunction = function (key, reducedValue) {
 
-                                 if (reducedValue.count > 0)
-                                     reducedValue.avg_time = reducedValue.total_time / reducedValue.count;
+                                if (reducedValue.count > 0)
+                                    reducedValue.avg_time = reducedValue.total_time / reducedValue.count;
 
-                                 return reducedValue;
+                                return reducedValue;
                              };
 
 #. Perform map-reduce on the ``session`` collection using the
@@ -154,26 +164,24 @@ each day and can be simulated as follows:
 
    .. code-block:: javascript
 
-      db.runCommand(
-                     {
-                        mapreduce: "sessions",
-                        map: mapFunction,
-                        reduce:reduceFunction,
-                        out: { reduce: "session_stat" },
-                        finalize: finalizeFunction
-                     }
-                   );
+      db.sessions.mapReduce( mapFunction,
+                             reduceFunction,
+                             {
+                               out: { reduce: "session_stat" },
+                               finalize: finalizeFunction
+                             }
+                           )
 
 **Subsequent Incremental Map-Reduce**
 
 Assume the next day, the ``sessions`` collection grows by the following documents:
 
    .. code-block:: javascript
 
-      db.session.save( { userid: "a", ts: ISODate('2011-11-05 14:17:00'), length: 100 } );
-      db.session.save( { userid: "b", ts: ISODate('2011-11-05 14:23:00'), length: 115 } );
-      db.session.save( { userid: "c", ts: ISODate('2011-11-05 15:02:00'), length: 125 } );
-      db.session.save( { userid: "d", ts: ISODate('2011-11-05 16:45:00'), length: 55 } );
+      db.sessions.save( { userid: "a", ts: ISODate('2011-11-05 14:17:00'), length: 100 } );
+      db.sessions.save( { userid: "b", ts: ISODate('2011-11-05 14:23:00'), length: 115 } );
+      db.sessions.save( { userid: "c", ts: ISODate('2011-11-05 15:02:00'), length: 125 } );
+      db.sessions.save( { userid: "d", ts: ISODate('2011-11-05 16:45:00'), length: 55 } );
 
 5. At the end of the day, perform incremental map-reduce on the
    ``sessions`` collection but use the ``query`` field to select only the
@@ -183,15 +191,14 @@ Assume the next day, the ``sessions`` collection grows by the following document
 
    .. code-block:: javascript
 
-      db.runCommand( { 
-                       mapreduce: "sessions", 
-                       map: mapFunction, 
-                       reduce:reduceFunction,
-                       query: { ts: { $gt: ISODate('2011-11-05 00:00:00') } },
-                       out: { reduce: "session_stat" }, 
-                       finalize:finalizeFunction 
-                     }
-                   );
+      db.sessions.mapReduce( mapFunction,
+                             reduceFunction,
+                             {
+                               query: { ts: { $gt: ISODate('2011-11-05 00:00:00') } },
+                               out: { reduce: "session_stat" },
+                               finalize: finalizeFunction
+                             }
+                           );
 
 .. _map-reduce-temporay-collection:
 
@@ -277,12 +284,9 @@ Additional References
 
 .. seealso::
 
+   - :doc:`/tutorial/troubleshoot-map-reduce`
+
    - :wiki:`Map-Reduce Concurrency
      <How+does+concurrency+work#Howdoesconcurrencywork-MapReduce>` 
 
    - `MapReduce, Geospatial Indexes, and Other Cool Features <http://www.slideshare.net/mongosf/mapreduce-geospatial-indexing-and-other-cool-features-kristina-chodorow>`_ - Kristina Chodorow at MongoSF (April 2010) 
-
-   - :wiki:`Troubleshooting MapReduce`
-
-.. [#simple-aggregation-use-framework] For many simple aggregation tasks, see the
-   :doc:`aggregation framework </applications/aggregation>`.

source/includes/examples-map-reduce.rst

@@ -29,6 +29,8 @@ Perform map-reduce operation on the ``orders`` collection to group by
 the ``cust_id``, and for each ``cust_id``, calculate the sum of the
 ``price`` for each ``cust_id``:
 
+   .. map-reduce-map-function-begin
+
 #. Define the ``<map>`` function to process each document in the
    map-reduce process:
 
@@ -44,6 +46,8 @@ the ``cust_id``, and for each ``cust_id``, calculate the sum of the
                              emit(this.cust_id, this.price);
                          };
 
+   .. map-reduce-map-function-end
+
 #. Define the corresponding ``<reduce>`` function with two arguments
    ``keyCustId`` and ``valuesPrices``:
 

source/includes/parameters-map-reduce.rst

@@ -31,8 +31,8 @@
           - The ``emit(key,value)`` function associates the ``key``
             with a ``value``.
 
-            - Each "emit" is limited to half the MongoDB :limit:`BSON
-              document size`. 
+            - Each "emit" is limited to half the MongoDB :ref:`maximum
+              BSON document size <limit-bson-document-size>`.
 
             - There is no limit to the number of times you may call the
               ``emit`` function per document.
@@ -68,11 +68,32 @@
           - The ``<reduce>`` function should *not* affect the outside
             system.
 
+          - The ``<reduce>`` function is *idempotent*; i.e. the
+            following behavior holds: 
+
+            .. code-block:: javascript
+
+               reduce( key, [ reduce(key, valuesArray) ] ) == reduce ( key, valuesArray )
+
+            Additionally, the order of the elements in the
+            ``valuesArray`` does not affect the result:
+
+            .. code-block:: javascript
+
+               reduce ( key, [ A, B ] ) == reduce ( key, [ B, A ] )
+
           - Because it is possible to invoke the ``<reduce>`` function
             more than once for the same key, the *type* of the return
             object must be **identical** to the type of the ``value``
-            emitted by the ``<map>`` function.
-
+            emitted by the ``<map>`` function to ensure that:
+            
+            .. code-block:: javascript
+            
+               reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce (key, [ C, A, B ] )
+
+          - The ``<reduce>`` function is **not** invoked for a key
+            that has only a single value.
+            
           - The ``<reduce>`` function can access the variables defined
             in the ``<scope>`` parameter if the ``<scope>`` parameter
             is defined for the map-reduce operation.
@@ -151,12 +172,15 @@
 
                 .. versionadded:: 2.1
 
-                Optional. Specify output operation as non-atomic. If
-                ``true``, the post processing step will not execute
-                inside of a database lock so that partial results will
-                be visible during processing . ``nonAtomic`` is valid
-                *only* for ``merge`` and ``reduce`` output operations
-                where post-processing may be a long-running operation.
+                Optional. Specify output operation as non-atomic and is
+                valid *only* for ``merge`` and ``reduce`` output modes.
+                Post-processing for ``merge`` and ``reduce`` output
+                modes may take a long time (e.g. minutes). During this
+                time, the entire database is locked for both reads and
+                writes. If ``nonAtomic`` is ``true``, the post
+                processing step will prevent the locking of the
+                database; however, partial results will be visible as
+                they are processed.
 
        - **Output inline**. Perform the map-reduce operation in memory
          and return the result. This option is the only available
@@ -246,8 +270,10 @@
        - Can only work for result sets with less than 500,000 distinct
          ``key`` arguments to the mapper's ``emit()`` function.
 
-       The ``<jsMode>`` defaults to true.
+       The ``<jsMode>`` defaults to false.
 
 :param Boolean verbose: 
 
-       Optional. Provides statistics on job execution times.
+       Optional. Specifies whether to include the ``timing``
+       information in the result information. The ``<verbose>``
+       defaults to ``true`` to include the ``timing`` information.