From 06a3e1a65f971ca015652def9dc33772a1ba7bdf Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Tue, 9 Sep 2014 15:03:48 -0400 Subject: [PATCH] DOCS-3168: mapReduce cleanup --- source/includes/parameters-map-reduce.rst | 67 +++++++++---------- source/reference/command/mapReduce-field.yaml | 12 ++-- source/reference/command/mapReduce.txt | 6 +- 3 files changed, 43 insertions(+), 42 deletions(-) diff --git a/source/includes/parameters-map-reduce.rst b/source/includes/parameters-map-reduce.rst index 063480bc6ef..8b09eb557ed 100644 --- a/source/includes/parameters-map-reduce.rst +++ b/source/includes/parameters-map-reduce.rst @@ -3,7 +3,9 @@ Requirements for the ``map`` Function ------------------------------------- -The ``map`` function has the following prototype: +The ``map`` function is responsible for transforming each input document into +zero or more documents. It can access the variables defined in the ``scope`` +parameter, and has the following prototype: .. code-block:: javascript @@ -12,7 +14,7 @@ The ``map`` function has the following prototype: emit(key, value); } -The ``map`` function exhibits the following behaviors: +The ``map`` function has the following requirements: - In the ``map`` function, reference the current document as ``this`` within the function. @@ -22,38 +24,32 @@ The ``map`` function exhibits the following behaviors: - The ``map`` function should be pure, or have *no* impact outside of the function (i.e. side effects.) -- The ``emit(key,value)`` function associates the ``key`` with a - ``value``. +- A single emit can only hold half of MongoDB's :ref:`maximum BSON + document size `. - - A single emit can only hold half of MongoDB's :ref:`maximum BSON - document size `. +- The ``map`` function may optionally call ``emit(key,value)`` any number of + times to create an output document associating ``key`` with ``value``. - - The ``map`` function can call ``emit(key,value)`` any number of - times, including 0, per each input document. +The following ``map`` function will call ``emit(key,value)`` either +0 or 1 times depending on the value of the input document's +``status`` field: - The following ``map`` function may call ``emit(key,value)`` either - 0 or 1 times depending on the value of the input document's - ``status`` field: - - .. code-block:: javascript - - function() { - if (this.status == 'A') - emit(this.cust_id, 1); - } +.. code-block:: javascript - The following ``map`` function may call ``emit(key,value)`` - multiple times depending on the number of elements in the input - document's ``items`` field: + function() { + if (this.status == 'A') + emit(this.cust_id, 1); + } - .. code-block:: javascript +The following ``map`` function may call ``emit(key,value)`` +multiple times depending on the number of elements in the input +document's ``items`` field: - function() { - this.items.forEach(function(item){ emit(item.sku, 1); }); - } +.. code-block:: javascript -- The ``map`` function can access the variables defined in the - ``scope`` parameter. + function() { + this.items.forEach(function(item){ emit(item.sku, 1); }); + } .. end-map @@ -98,7 +94,9 @@ properties need to be true: - the *type* of the return object must be **identical** to the type of the ``value`` emitted by the ``map`` - function to ensure that the following operations is + function. + +- the ``reduce`` function must be *associative*. The following statement must be true: .. code-block:: javascript @@ -112,10 +110,9 @@ properties need to be true: reduce( key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray ) -- the order of the elements in the - ``valuesArray`` should not affect the output of the - ``reduce`` function, so that the following statement is - true: +- the ``reduce`` function should be *commutative*: that is, the order of the + elements in the ``valuesArray`` should not affect the output of the + ``reduce`` function, so that the following statement is true: .. code-block:: javascript @@ -133,6 +130,9 @@ You can specify the following options for the ``out`` parameter: Output to a Collection ~~~~~~~~~~~~~~~~~~~~~~ +This option outputs to a new collection, and is not available on secondary +members of replica sets. + .. code-block:: javascript out: @@ -141,8 +141,7 @@ Output to a Collection with an Action ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This option is only available when passing ``out`` a collection that -already exists. This option is not available on secondary members of -replica sets. +already exists. It is not available on secondary members of replica sets. .. code-block:: javascript diff --git a/source/reference/command/mapReduce-field.yaml b/source/reference/command/mapReduce-field.yaml index 31717c37a40..85c4c1e6727 100644 --- a/source/reference/command/mapReduce-field.yaml +++ b/source/reference/command/mapReduce-field.yaml @@ -10,6 +10,8 @@ type: collection position: 0 description: | The name of the collection on which you want to perform map-reduce. + This collection will be filtered using ``query`` before being processed + by the ``map`` function. --- object: name: mapReduce @@ -51,11 +53,11 @@ name: out type: string or document position: 3 description: | - Specifies the location of the result of the map-reduce operation. - You can output to a collection, output to a collection with an - action, or output inline. You may output to a collection when - performing map reduce operations on the primary members of the set; - on :term:`secondary` members you may only use the ``inline`` output. + Specifies where to output the result of the map-reduce operation. You + can either output to a collection or return the result inline. On a + :term:`primary` member of a replica set you can output either to a collection + or inline, but on a :term:`secondary`, only inline output is + possible. See :ref:`mapReduce-out-cmd` for more information. --- diff --git a/source/reference/command/mapReduce.txt b/source/reference/command/mapReduce.txt index 41f8d54677b..6b98663bd7e 100644 --- a/source/reference/command/mapReduce.txt +++ b/source/reference/command/mapReduce.txt @@ -46,11 +46,11 @@ mapReduce db.runCommand( { - mapReduce: 'orders', + mapReduce: , map: mapFunction, reduce: reduceFunction, - out: { merge: 'map_reduce_results', db: 'test' }, - query: { ord_date: { $gt: new Date('01/01/2012') } } + out: { merge: }, + query: } )