doc: add map/reduce example (as well as section for migrating existing examples to new doc system)

doc/examples/index.rst

@@ -0,0 +1,19 @@
+Examples
+========
+
+The examples in this section are intended to give in depth overviews
+of how to accomplish specific tasks with MongoDB and PyMongo.
+
+Unless otherwise noted, all examples assume that a MongoDB instance is
+running on the default host and port. Assuming you have `downloaded
+and installed <http://www.mongodb.org/display/DOCS/Getting+Started>`_
+MongoDB, you can start it like so:
+
+.. code-block:: bash
+
+  $ mongod
+
+.. toctree::
+   :maxdepth: 2
+
+   map_reduce

doc/examples/map_reduce.rst

@@ -0,0 +1,83 @@
+Map/Reduce
+==========
+
+This example shows how to use the
+:meth:`~pymongo.collection.Collection.map_reduce` method to perform
+map/reduce style aggregations on your data.
+
+Setup
+-----
+To start, we'll insert some example data which we can perform
+map/reduce queries on::
+
+  >>> from pymongo import Connection
+  >>> db = Connection().map_reduce_example
+  >>> db.things.insert({"x": 1, "tags": ["dog", "cat"]})
+  ObjectId('...')
+  >>> db.things.insert({"x": 2, "tags": ["cat"]})
+  ObjectId('...')
+  >>> db.things.insert({"x": 3, "tags": ["mouse", "cat", "dog"]})
+  ObjectId('...')
+  >>> db.things.insert({"x": 4, "tags": []})
+  ObjectId('...')
+
+Basic Map/Reduce
+----------------
+Now we'll define our **map** and **reduce** functions. In this case
+we're performing the same operation as in the `MongoDB Map/Reduce
+documentation <http://www.mongodb.org/display/DOCS/MapReduce>`_ -
+counting the number of occurrences for each tag in the ``tags`` array,
+across the entire collection.
+
+Our **map** function just emits a single `(key, 1)` pair for each tag in
+the array::
+
+  >>> from pymongo.code import Code
+  >>> map = Code("function () {"
+  ...            "  this.tags.forEach(function(z) {"
+  ...            "    emit(z, 1);"
+  ...            "  });"
+  ...            "}")
+
+The **reduce** function sums over all of the emitted values for a given key::
+
+  >>> reduce = Code("function (key, values) {"
+  ...               "  var total = 0;"
+  ...               "  for (var i = 0; i < values.length; i++) {"
+  ...               "    total += values[i];"
+  ...               "  }"
+  ...               "  return total;"
+  ...               "}")
+
+.. note:: We can't just return ``values.length`` as the **reduce** function
+   might be called iteratively on the results of other reduce steps.
+
+Finally, we call :meth:`~pymongo.collection.Collection.map_reduce` and
+iterate over the result collection::
+
+  >>> result = db.things.map_reduce(map, reduce)
+  >>> for doc in result.find():
+  ...   print doc
+  ...
+  {u'_id': u'cat', u'value': 3.0}
+  {u'_id': u'dog', u'value': 2.0}
+  {u'_id': u'mouse', u'value': 1.0}
+
+Advanced Map/Reduce
+-------------------
+
+PyMongo's API supports all of the features of MongoDB's map/reduce engine. One interesting feature is the ability to get more detailed results when desired, by passing `full_response=True` to :meth:`~pymongo.collection.Collection.map_reduce`. This returns the full response to the map/reduce command, rather than just the result collection::
+
+  >>> db.things.map_reduce(map, reduce, full_response=True)
+  {u'counts': {u'input': 4L, u'emit': 6L, u'output': 3L}, u'timeMillis': ..., u'ok': 1.0, u'result': u'...'}
+
+All of the optional map/reduce parameters are also supported, simply pass them as keyword arguments. In this example we use the `query` parameter to limit the documents that will be mapped over::
+
+  >>> result = db.things.map_reduce(map, reduce, query={"x": {"$lt": 3}})
+  >>> for doc in result.find():
+  ...   print doc
+  ...
+  {u'_id': u'cat', u'value': 2.0}
+  {u'_id': u'dog', u'value': 1.0}
+
+.. seealso:: The full list of options for MongoDB's `map reduce engine <http://www.mongodb.org/display/DOCS/MapReduce>`_

doc/index.rst

@@ -14,6 +14,9 @@ Overview
 :doc:`tutorial`
   Start here for a quick overview.
 
+:doc:`examples/index`
+  Examples of how to perform specific tasks.
+
 :doc:`faq`
   Some questions that come up often.
 
@@ -51,6 +54,7 @@ Full Contents Tree
 
    installation
    tutorial
+   examples/index
    faq
    api/index
    tools