From a8f26f41a72bffdacb23c84dd17361ccc2dc210e Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 29 Jan 2013 20:10:30 -0500 Subject: [PATCH] DOC-988 latex errors with code block within params list --- source/includes/parameters-map-reduce.rst | 397 +++++++++--------- source/reference/command/mapReduce.txt | 42 +- .../method/db.collection.mapReduce.txt | 28 +- 3 files changed, 239 insertions(+), 228 deletions(-) diff --git a/source/includes/parameters-map-reduce.rst b/source/includes/parameters-map-reduce.rst index 002a4096385..8e4efc447ba 100644 --- a/source/includes/parameters-map-reduce.rst +++ b/source/includes/parameters-map-reduce.rst @@ -1,287 +1,306 @@ :param map: - A JavaScript function that associates or "maps" a value with a key. + A JavaScript function that associates or "maps" a ``value`` with a + ``key`` and emits the ``key`` and value ``pair``. - The ``map`` function has the following prototype: + The ``map`` function processes every input document for the map-reduce + operation. The map-reduce operation groups the emitted ``value`` + objects by the ``key`` and passes these groupings to the ``reduce`` + function. - .. code-block:: javascript +:param reduce: - function() { - ... - emit(key, value); - } + A JavaScript function that "reduces" to a single object all the + ``values`` associated with a particular ``key``. - The ``map`` function process every input document for the - map-reduce operation. All the ``key`` and ``value`` pairs emitted - by the map function. In map-reduce operations, the operation groups - the output from the map phase by the ``key`` value and passes these - groupings to the ``reduce`` function. + The ``reduce`` function accepts two arguments: ``key`` and + ``values``. The ``values`` argument is an array whose elements are + the ``value`` objects that are "mapped" to the ``key``. - .. note: +:param out: - - In the ``map`` function, reference the current document as - ``this`` within the function. + .. versionadded:: 1.8 - - The ``map`` function should *not* access the database for - any reason. + 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. - - The ``map`` function should be pure, or have *no* impact - outside of the function (i.e. side effects.) +:param query: - - The ``emit(key,value)`` function associates the ``key`` - with a ``value``. + Optional. Specifies the selection criteria using :doc:`query + operators ` for determining the documents + input to the ``map`` function. - - A single emit can only hold half of MongoDB's :ref:`maximum - BSON document size `. +:param sort: - - There is no limit to the number of times you may call the - ``emit`` function per document. + Optional. Sorts the *input* documents. This option is useful for + optimization. For example, specify the sort key to be the same as + the emit key so that there are fewer reduce operations. - - The ``map`` function can access the variables defined in - the ``scope`` parameter. +:param limit: -:param reduce: + Optional. Specifies a maximum number of documents to return from + the collection. - A JavaScript function that "reduces" to a single object all the - ``values`` associated with a particular ``key``. +:param finalize: - The ``reduce`` function has the following prototype: + Optional. A JavaScript function that follows the ``reduce`` + method and modifies the output. - .. code-block:: javascript + The ``finalize`` function receives two arguments: ``key`` and + ``reducedValue``. The ``reducedValue`` is the value returned from + the ``reduce`` function for the ``key``. - function(key, values) { - ... - return result; - } +:param document scope: - The ``reduce`` function accepts ``key`` and ``values`` - arguments. The elements of the ``values`` array are the - individual ``value`` objects emitted by the ```` function, - grouped by the ``key``. + Optional. Specifies global variables that are accessible in the + ``map`` , ``reduce`` and the ``finalize`` functions. - Be aware of the following behaviors: +:param Boolean jsMode: - - The ``reduce`` function should *not* access the database, - even to perform read operations. + .. versionadded:: 2.0 - - The ``reduce`` function should *not* affect the outside - system. + Optional. Specifies whether to convert intermediate data into BSON + format between the execution of the ``map`` and ``reduce`` + functions. - - MongoDB will **not** call the ``reduce`` function for a key - that has only a single value. + If ``false``: - - The ``reduce`` function can access the variables defined - in the ``scope`` parameter. + - Internally, MongoDB converts the JavaScript objects emitted + by the ``map`` + function to BSON objects. These BSON + objects are then converted back to JavaScript objects when + calling the ``reduce`` function. - Because it is possible to invoke the ``reduce`` function - more than once for the same key, the following - properties need to be true: + - The map-reduce operation places the intermediate BSON objects + in temporary, on-disk storage. This allows the map-reduce + operation to execute over arbitrarily large data sets. - - the *type* of the return object must be **identical** - to the type of the ``value`` emitted by the ```` - function to ensure that the following operations is - true: + If ``true``: - .. code-block:: javascript + - Internally, the JavaScript objects emitted during ``map`` + function remain as JavaScript objects. There is no need to + convert the objects for the ``reduce`` function, which + can result in faster execution. - reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce (key, [ C, A, B ] ) + - You can only use ``jsMode`` for result sets with fewer than + 500,000 distinct ``key`` arguments to the mapper's ``emit()`` + function. - - the ``reduce`` function must be *idempotent*. Ensure - that the following statement is true: + The ``jsMode`` defaults to false. - .. code-block:: javascript +:param Boolean verbose: - reduce( key, [ reduce(key, valuesArray) ] ) == reduce ( key, valuesArray ) + Optional. Specifies whether to include the ``timing`` information + in the result information. The ``verbose`` defaults to ``true`` to + include the ``timing`` information. + +.. stop-parameters-here - - the order of the elements in the - ``valuesArray`` should not affect the output of the - ``reduce`` function, so that the following statement is - true: +Requirements for the ``map`` Function +------------------------------------- - .. code-block:: javascript +The ``map`` function has the following prototype: - reduce ( key, [ A, B ] ) == reduce ( key, [ B, A ] ) +.. code-block:: javascript -:param out: + function() { + ... + emit(key, value); + } - .. versionadded:: 1.8 +The ``map`` function exhibits the following behaviors: - Specifies the location of the result of the map-reduce - operation. 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. +- In the ``map`` function, reference the current document as ``this`` + within the function. - You can specify the following options for the ``out`` parameter: +- The ``map`` function should *not* access the database for any reason. - - **Output to a collection**. +- The ``map`` function should be pure, or have *no* impact outside of + the function (i.e. side effects.) - .. code-block:: javascript +- The ``emit(key,value)`` function associates the ``key`` with a + ``value``. - { out: } + - A single emit can only hold half of MongoDB's :ref:`maximum BSON + document size `. - - **Output to a collection and specify one of the following - actions**. This option is only available when passing ``out`` - a collection that already exists. This option is not - available on secondary members of replica sets. + - There is no limit to the number of times you may call the ``emit`` + function per document. - .. code-block:: javascript +- The ``map`` function can access the variables defined in the + ``scope`` parameter. - { out: { : [, db: ][, sharded: ][, nonAtomic: ] } } +Requirements for the ``reduce`` Function +---------------------------------------- - - ````: Specify one of the following actions: +The ``reduce`` function has the following prototype: - - ``replace`` +.. code-block:: javascript - .. code-block:: javascript + function(key, values) { + ... + return result; + } - { out: { replace: } } +The ``map`` function exhibits the following behaviors: - Replace the contents of the ```` if the - collection with the ```` exists. +- The ``reduce`` function should *not* access the database, + even to perform read operations. - - ``merge`` +- The ``reduce`` function should *not* affect the outside + system. - .. code-block:: javascript +- MongoDB will **not** call the ``reduce`` function for a key + that has only a single value. - { out: { merge: } } +- The ``reduce`` function can access the variables defined + in the ``scope`` parameter. - Merge the new result with the existing result if the - output collection already exists. If an existing document - has the same key as the new result, *overwrite* that - existing document. +Because it is possible to invoke the ``reduce`` function +more than once for the same key, the following +properties need to be true: - - ``reduce`` +- 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 + true: - .. code-block:: javascript + .. code-block:: javascript - { out: { reduce: } } + reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce( key, [ C, A, B ] ) - Merge the new result with the existing result if the - output collection already exists. If an existing document - has the same key as the new result, apply the ```` - function to both the new and the existing documents and - overwrite the existing document with the result. +- the ``reduce`` function must be *idempotent*. Ensure + that the following statement is true: - - ``db``: + .. code-block:: javascript - Optional.The name of the database that you want the - map-reduce operation to write its output. By default - this will be the same database as the input collection. + reduce( key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray ) - - ``sharded``: +- the order of the elements in the + ``valuesArray`` should not affect the output of the + ``reduce`` function, so that the following statement is + true: - Optional. If ``true`` *and* you have enabled sharding on - output database, the map-reduce operation will shard the - output collection using the ``_id`` field as the shard key. + .. code-block:: javascript - - ``nonAtomic``: + reduce( key, [ A, B ] ) == reduce( key, [ B, A ] ) - .. versionadded:: 2.2 - Optional. Specify output operation as non-atomic and is - valid *only* for ``merge`` and ``reduce`` output modes which - may take minutes to execute. +``out`` Options +--------------- - If ``nonAtomic`` is ``true``, the post-processing step will - prevent MongoDB from locking the database; however, other - clients will be able to read intermediate states of the - output collection. Otherwise the map reduce operation must - lock the database during post-processing. +You can specify the following options for the ``out`` parameter: - - **Output inline**. Perform the map-reduce operation in memory - and return the result. This option is the only available - option for ``out`` on secondary members of replica sets. +Output to a Collection +~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: javascript +.. code-block:: javascript - { out: { inline: 1 } } + out: - The result must fit within the :ref:`maximum size of a BSON - document `. +Output to a Collection with an Action +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:param query: +This option is only available when passing ``out`` a collection that +already exists. This option is not available on secondary members of +replica sets. - Optional. Specifies the selection criteria using :doc:`query - operators ` for determining the documents - input to the ``map`` function. +.. code-block:: javascript -:param sort: + out: { : + [, db: ] + [, sharded: ] + [, nonAtomic: ] } - Optional. Sorts the *input* documents. This option is useful for - optimization. For example, specify the sort key to be the same as - the emit key so that there are fewer reduce operations. +When you output to a collection with an action, the ``out`` has the +following parameters: -:param limit: +- ````: Specify one of the following actions: - Optional. Specifies a maximum number of documents to return from - the collection. + - ``replace`` -:param finalize: + Replace the contents of the ```` if the + collection with the ```` exists. - Optional. A JavaScript function that follows the ```` - method and modifies the output and has the following prototype: + - ``merge`` - .. code-block:: javascript + Merge the new result with the existing result if the + output collection already exists. If an existing document + has the same key as the new result, *overwrite* that + existing document. - function(key, reducedValue) { - ... - return modifiedObject; - } + - ``reduce`` - The ```` function receives as its arguments a ``key`` - value and the ``reducedValue`` from the ```` function. Be - aware that: + Merge the new result with the existing result if the + output collection already exists. If an existing document + has the same key as the new result, apply the ``reduce`` + function to both the new and the existing documents and + overwrite the existing document with the result. - - The ``finalize`` function should *not* access the database for - any reason. +- ``db``: - - The ``finalize`` function should be pure, or have *no* impact - outside of the function (i.e. side effects.) + Optional.The name of the database that you want the + map-reduce operation to write its output. By default + this will be the same database as the input collection. - - The ``finalize`` function can access the variables defined in - the ``scope`` parameter. +- ``sharded``: -:param document scope: + Optional. If ``true`` *and* you have enabled sharding on + output database, the map-reduce operation will shard the + output collection using the ``_id`` field as the shard key. - Optional. Specifies global variables that are accessible in the - ``map`` , ``reduce`` and the ``finalize`` functions. +- ``nonAtomic``: -:param Boolean jsMode: + .. versionadded:: 2.2 - .. versionadded:: 2.0 + Optional. Specify output operation as non-atomic and is valid *only* + for ``merge`` and ``reduce`` output modes which may take minutes to + execute. - Optional. Specifies whether to convert intermediate data into BSON - format between the execution of the ``map`` and ``reduce`` - functions. + If ``nonAtomic`` is ``true``, the post-processing step will prevent + MongoDB from locking the database; however, other clients will be + able to read intermediate states of the output collection. Otherwise + the map reduce operation must lock the database during + post-processing. - If ``false``: +Output Inline +~~~~~~~~~~~~~~ - - Internally, MongoDB converts the JavaScript objects emitted - by the ``map`` - function to BSON objects. These BSON - objects are then converted back to JavaScript objects when - calling the ``reduce`` function. +Perform the map-reduce operation in memory and return the result. This +option is the only available option for ``out`` on secondary members of +replica sets. - - The map-reduce operation places the intermediate BSON objects - in temporary, on-disk storage. This allows the map-reduce - operation to execute over arbitrarily large data sets. +.. code-block:: javascript - If ``true``: + out: { inline: 1 } - - Internally, the JavaScript objects emitted during ``map`` - function remain as JavaScript objects. There is no need to - convert the objects for the ``reduce`` function, which - can result in faster execution. +The result must fit within the :ref:`maximum size of a BSON document +`. - - You can only use ``jsMode`` for result sets with fewer than - 500,000 distinct ``key`` arguments to the mapper's ``emit()`` - function. +Requirements for the ``finalize`` Function +------------------------------------------ - The ``jsMode`` defaults to false. +The ``finalize`` function has the following prototype: -:param Boolean verbose: + .. code-block:: javascript - Optional. Specifies whether to include the ``timing`` information - in the result information. The ``verbose`` defaults to ``true`` to - include the ``timing`` information. + function(key, reducedValue) { + ... + return modifiedObject; + } + +The ``finalize`` function receives as its arguments a ``key`` +value and the ``reducedValue`` from the ``reduce`` function. Be +aware that: + +- The ``finalize`` function should *not* access the database for + any reason. + +- The ``finalize`` function should be pure, or have *no* impact + outside of the function (i.e. side effects.) + +- The ``finalize`` function can access the variables defined in + the ``scope`` parameter. diff --git a/source/reference/command/mapReduce.txt b/source/reference/command/mapReduce.txt index ecdd33a3c17..d4effc8f9eb 100644 --- a/source/reference/command/mapReduce.txt +++ b/source/reference/command/mapReduce.txt @@ -18,7 +18,7 @@ mapReduce mapReduce: , map: , reduce: , - out: , + out: , query: , sort: , limit: , @@ -35,9 +35,10 @@ mapReduce parameters: .. include:: /includes/parameters-map-reduce.rst + :end-before: stop-parameters-here - Consider the following prototype map:dbcommand:`mapReduce` - operation: + The following is a prototype usage of the :dbcommand:`mapReduce` + command: .. code-block:: javascript @@ -49,34 +50,31 @@ mapReduce mapReduce: 'orders', map: mapFunction, reduce: reduceFunction, - out: { merge: 'map_reduce_results' }, + out: { merge: 'map_reduce_results', db: 'test' }, query: { ord_date: { $gt: new Date('01/01/2012') } } } ) - In the :program:`mongo`, the :method:`db.collection.mapReduce()` - method is a wrapper around the :dbcommand:`mapReduce` command. The - following examples use the :method:`db.collection.mapReduce()`: +.. include:: /includes/parameters-map-reduce.rst + :start-after: stop-parameters-here - .. include:: /includes/examples-map-reduce.rst - :start-after: map-reduce-document-prototype-begin - :end-before: map-reduce-document-prototype-end +Examples +-------- - - .. include:: /includes/examples-map-reduce.rst - :start-after: map-reduce-sum-price-begin - :end-before: map-reduce-sum-price-end +In the :program:`mongo` shell, the :method:`db.collection.mapReduce()` +method is a wrapper around the :dbcommand:`mapReduce` command. The +following examples use the :method:`db.collection.mapReduce()` method: - - .. include:: /includes/examples-map-reduce.rst - :start-after: map-reduce-counts-begin - :end-before: map-reduce-counts-end +.. include:: /includes/examples-map-reduce.rst + :start-after: map-reduce-document-prototype-begin - For more information and examples, see the :doc:`Map-Reduce - ` page. +For more information and examples, see the :doc:`Map-Reduce +` page. - .. seealso:: +.. seealso:: - - :term:`map-reduce` and :method:`db.collection.mapReduce()` + - :term:`map-reduce` and :method:`db.collection.mapReduce()` - - :doc:`/applications/aggregation` + - :doc:`/applications/aggregation` - .. slave-ok +.. slave-ok diff --git a/source/reference/method/db.collection.mapReduce.txt b/source/reference/method/db.collection.mapReduce.txt index b7f4918530a..787db73061e 100644 --- a/source/reference/method/db.collection.mapReduce.txt +++ b/source/reference/method/db.collection.mapReduce.txt @@ -12,8 +12,8 @@ db.collection.mapReduce() .. code-block:: javascript db.collection.mapReduce( - mapfunction, - reducefunction, + , + , { out: , query: , @@ -29,24 +29,18 @@ db.collection.mapReduce() :method:`db.collection.mapReduce()` takes the following parameters: .. include:: /includes/parameters-map-reduce.rst + :end-before: stop-parameters-here - .. include:: /includes/examples-map-reduce.rst - :start-after: map-reduce-document-prototype-begin - :end-before: map-reduce-document-prototype-end +.. include:: /includes/parameters-map-reduce.rst + :start-after: stop-parameters-here - - .. include:: /includes/examples-map-reduce.rst - :start-after: map-reduce-sum-price-begin - :end-before: map-reduce-sum-price-end +.. include:: /includes/examples-map-reduce.rst - - .. include:: /includes/examples-map-reduce.rst - :start-after: map-reduce-counts-begin - :end-before: map-reduce-counts-end - - For more information and examples, see the :doc:`Map-Reduce - ` page. +For more information and examples, see the :doc:`Map-Reduce +` page. - .. seealso:: +.. seealso:: - - :term:`map-reduce` and :dbcommand:`mapReduce` + - :term:`map-reduce` and :dbcommand:`mapReduce` command - - :doc:`/applications/aggregation` + - :doc:`/applications/aggregation`