Browse files

reorg map-reduce, aggregation, crud, serverside javascript, replicati…

…on (write concern/read pref)
  • Loading branch information...
1 parent 913af19 commit 6ffe52f7acb16c88e7d86064cf70c1b4bf0713a2 @kay-kim kay-kim committed with tychoish Apr 4, 2013
Showing with 1,719 additions and 1,690 deletions.
  1. +3 −3 source/administration/production-notes.txt
  2. +3 −3 source/aggregation.txt
  3. +9 −4 source/applications.txt
  4. +0 −601 source/applications/map-reduce.txt
  5. +1 −1 source/applications/optimization.txt
  6. +6 −786 source/applications/replication.txt
  7. +0 −164 source/applications/server-side-javascript.txt
  8. 0 source/{applications → core}/aggregation.txt
  9. +4 −4 source/{applications → core}/create.txt
  10. 0 source/{applications → core}/delete.txt
  11. +4 −4 source/core/document.txt
  12. +2 −2 source/core/import-export.txt
  13. +159 −0 source/core/map-reduce.txt
  14. +2 −2 source/core/operational-segregation.txt
  15. +4 −4 source/core/read-operations.txt
  16. +581 −0 source/core/read-preference.txt
  17. 0 source/{applications → core}/read.txt
  18. +1 −1 source/core/replication-internals.txt
  19. +54 −0 source/core/server-side-javascript.txt
  20. +2 −2 source/{applications → core}/update.txt
  21. +216 −0 source/core/write-concern.txt
  22. +4 −4 source/core/write-operations.txt
  23. +4 −4 source/crud.txt
  24. +2 −3 source/data-center-awareness.txt
  25. +2 −2 source/faq/developers.txt
  26. +1 −1 source/includes/admonitions-eval.rst
  27. +10 −12 source/includes/fact-group-map-reduce-where-limitations-in-24.rst
  28. +1 −1 source/index.txt
  29. +4 −4 source/installation.txt
  30. +1 −1 source/reference/aggregation.txt
  31. +2 −2 source/reference/command/aggregate.txt
  32. +1 −1 source/reference/command/eval.txt
  33. +2 −2 source/reference/command/getLastError.txt
  34. +1 −1 source/reference/command/group.txt
  35. +10 −5 source/reference/command/mapReduce.txt
  36. +1 −1 source/reference/configuration-options.txt
  37. +1 −1 source/reference/connection-string.txt
  38. +1 −1 source/reference/database-profiler.txt
  39. +8 −8 source/reference/glossary.txt
  40. +2 −2 source/reference/method/db.collection.aggregate.txt
  41. +1 −1 source/reference/method/db.collection.group.txt
  42. +10 −5 source/reference/method/db.collection.mapReduce.txt
  43. +1 −1 source/reference/method/db.eval.txt
  44. +2 −2 source/reference/method/db.getLastError.txt
  45. +2 −2 source/reference/method/mongo.setSlaveOk.txt
  46. +2 −1 source/reference/method/rs.slaveOk.txt
  47. +9 −9 source/reference/mongo-shell.txt
  48. +1 −1 source/reference/mongos.txt
  49. +2 −2 source/reference/operator/setOnInsert.txt
  50. +1 −1 source/reference/server-status.txt
  51. +1 −1 source/reference/simple-aggregation.txt
  52. +1 −1 source/reference/sql-aggregation-comparison.txt
  53. +5 −4 source/reference/system-collections.txt
  54. +1 −1 source/release-notes/2.0.txt
  55. +5 −5 source/release-notes/2.2.txt
  56. +1 −1 source/release-notes/2.4.txt
  57. +4 −0 source/tutorial.txt
  58. +1 −1 source/tutorial/aggregation-examples.txt
  59. +1 −1 source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt
  60. +1 −1 source/tutorial/expire-data.txt
  61. +4 −4 source/tutorial/getting-started-with-the-mongo-shell.txt
  62. +2 −2 source/tutorial/getting-started.txt
  63. +12 −0 source/tutorial/map-reduce-examples.txt
  64. +159 −0 source/tutorial/perform-incremental-map-reduce.txt
  65. +69 −0 source/tutorial/store-javascript-function-on-server.txt
  66. +84 −0 source/tutorial/troubleshoot-map-function.txt
  67. +221 −0 source/tutorial/troubleshoot-reduce-function.txt
  68. +3 −2 source/use-cases/hierarchical-aggregation.txt
  69. +1 −1 source/use-cases/product-catalog.txt
  70. +3 −3 source/use-cases/storing-log-data.txt
View
6 source/administration/production-notes.txt
@@ -282,7 +282,7 @@ There is a :limit:`BSON Document Size` -- at the time of this writing
Set Appropriate Write Concern for Write Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See :ref:`write concern <write-concern>` for more information.
+See :doc:`/core/write-concern` for more information.
Dynamic Schema
~~~~~~~~~~~~~~
@@ -336,7 +336,7 @@ Consider:
- and/or using :doc:`$toLower </reference/aggregation/toLower/>` or
:doc:`$toUpper </reference/aggregation/toUpper/>` in the
- :doc:`aggregation framework </applications/aggregation/>`
+ :doc:`aggregation framework </core/aggregation/>`
Type Sensitive Fields
~~~~~~~~~~~~~~~~~~~~~
@@ -394,7 +394,7 @@ here:
1. Monitoring and alerts for any lagging can be done via various means.
MMS shows a graph of replica set lag
-#. Using :ref:`getLastError <replica-set-write-concern>` with
+#. Using :doc:`getLastError </core/write-concern>` with
``w:'majority'``, you will get a timeout or no return if a majority of
the set is lagging. This is thus another way to guard against lag and
get some reporting back of its occurrence.
View
6 source/aggregation.txt
@@ -7,7 +7,7 @@ Aggregation
.. default-domain:: mongodb
In version 2.2, MongoDB introduced the :doc:`aggregation framework
-</applications/aggregation>` that provides a powerful and flexible set
+</core/aggregation>` that provides a powerful and flexible set
of tools to use for many data aggregation tasks. If you're familiar with data aggregation in SQL, consider the
:doc:`/reference/sql-aggregation-comparison` document as an introduction to
some of the basic concepts in the aggregation framework. Consider the
@@ -16,10 +16,10 @@ full documentation of the aggregation framework here:
.. toctree::
:maxdepth: 2
- applications/aggregation
+ core/aggregation
tutorial/aggregation-examples
reference/aggregation
- applications/map-reduce
+ core/map-reduce
In addition to the aggregation framework, MongoDB provides simple
:doc:`aggregation methods and commands </reference/simple-aggregation>`,
View
13 source/applications.txt
@@ -31,15 +31,20 @@ The following documents outline basic application development topics:
applications/drivers
applications/optimization
- applications/server-side-javascript
core/capped-collections
+ core/server-side-javascript
+ tutorial/store-javascript-function-on-server
.. seealso::
- - :doc:`/applications/replication`
+ - :doc:`/core/read-preference`
+ - :doc:`/core/write-concern`
- :doc:`/applications/indexes`
- - :doc:`/applications/aggregation`
- - :doc:`/applications/map-reduce`
+ - :doc:`/core/aggregation`
+ - :doc:`/core/map-reduce`
+ - :doc:`/tutorial/perform-incremental-map-reduce`
+ - :doc:`/tutorial/troubleshoot-map-function`
+ - :doc:`/tutorial/troubleshoot-reduce-function`
- :doc:`/reference/connection-string`
.. _application-patterns:
View
601 source/applications/map-reduce.txt
@@ -1,601 +0,0 @@
-==========
-Map-Reduce
-==========
-
-.. default-domain:: mongodb
-
-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.
-
-For many simple aggregation tasks, see the :doc:`aggregation framework
-</applications/aggregation>`.
-
-.. _map-reduce-examples:
-
-Map-Reduce Examples
--------------------
-
-This section provides some map-reduce examples in the :program:`mongo`
-shell using the :method:`db.collection.mapReduce()` method:
-
-.. code-block:: javascript
-
- db.collection.mapReduce(
- <mapfunction>,
- <reducefunction>,
- {
- out: <collection>,
- query: <document>,
- sort: <document>,
- limit: <number>,
- finalize: <function>,
- scope: <document>,
- jsMode: <boolean>,
- verbose: <boolean>
- }
- )
-
-For more information on the parameters, see the
-:method:`db.collection.mapReduce()` reference page .
-
-.. include:: /includes/examples-map-reduce.rst
- :start-after: map-reduce-document-prototype-begin
-
-.. _map-reduce-incremental:
-
-Incremental Map-Reduce
-----------------------
-
-If the map-reduce dataset is constantly growing, then rather than
-performing the map-reduce operation over the entire dataset each time
-you want to run map-reduce, you may want to perform an incremental
-map-reduce.
-
-To perform incremental map-reduce:
-
-#. Run a map-reduce job over the current collection and output the
- result to a separate collection.
-
-#. When you have more data to process, run subsequent map-reduce job
- with:
-
- - the ``query`` parameter that specifies conditions that match
- *only* the new documents.
-
- - the ``out`` parameter that specifies the ``reduce`` action to
- merge the new results into the existing output collection.
-
-Consider the following example where you schedule a map-reduce
-operation on a ``sessions`` collection to run at the end of each day.
-
-Data Setup
-~~~~~~~~~~
-
-The ``sessions`` collection contains documents that log users' session
-each day, for example:
-
-.. code-block:: javascript
-
- db.sessions.save( { userid: "a", ts: ISODate('2011-11-03 14:17:00'), length: 95 } );
- db.sessions.save( { userid: "b", ts: ISODate('2011-11-03 14:23:00'), length: 110 } );
- db.sessions.save( { userid: "c", ts: ISODate('2011-11-03 15:02:00'), length: 120 } );
- db.sessions.save( { userid: "d", ts: ISODate('2011-11-03 16:45:00'), length: 45 } );
-
- db.sessions.save( { userid: "a", ts: ISODate('2011-11-04 11:05:00'), length: 105 } );
- db.sessions.save( { userid: "b", ts: ISODate('2011-11-04 13:14:00'), length: 120 } );
- db.sessions.save( { userid: "c", ts: ISODate('2011-11-04 17:00:00'), length: 130 } );
- db.sessions.save( { userid: "d", ts: ISODate('2011-11-04 15:37:00'), length: 65 } );
-
-Initial Map-Reduce of Current Collection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Run the first map-reduce operation as follows:
-
-#. Define the ``map`` function that maps the ``userid`` to an
- object that contains the fields ``userid``, ``total_time``, ``count``,
- and ``avg_time``:
-
- .. code-block:: javascript
-
- var mapFunction = function() {
- var key = this.userid;
- var value = {
- userid: this.userid,
- total_time: this.length,
- count: 1,
- avg_time: 0
- };
-
- emit( key, value );
- };
-
-#. Define the corresponding ``reduce`` function with two arguments
- ``key`` and ``values`` to calculate the total time and the count.
- The ``key`` corresponds to the ``userid``, and the ``values`` is an
- array whose elements corresponds to the individual objects mapped to the
- ``userid`` in the ``mapFunction``.
-
- .. code-block:: javascript
-
- var reduceFunction = function(key, values) {
-
- var reducedObject = {
- userid: key,
- total_time: 0,
- count:0,
- avg_time:0
- };
-
- values.forEach( function(value) {
- reducedObject.total_time += value.total_time;
- reducedObject.count += value.count;
- }
- );
- return reducedObject;
- };
-
-#. Define ``finalize`` function with two arguments ``key`` and
- ``reducedValue``. The function modifies the ``reducedValue`` document
- to add another field ``average`` and returns the modified document.
-
- .. code-block:: javascript
-
- var finalizeFunction = function (key, reducedValue) {
-
- if (reducedValue.count > 0)
- reducedValue.avg_time = reducedValue.total_time / reducedValue.count;
-
- return reducedValue;
- };
-
-#. Perform map-reduce on the ``session`` collection using the
- ``mapFunction``, the ``reduceFunction``, and the
- ``finalizeFunction`` functions. Output the results to a collection
- ``session_stat``. If the ``session_stat`` collection already exists,
- the operation will replace the contents:
-
- .. code-block:: javascript
-
- db.sessions.mapReduce( mapFunction,
- reduceFunction,
- {
- out: { reduce: "session_stat" },
- finalize: finalizeFunction
- }
- )
-
-Subsequent Incremental Map-Reduce
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Later as the ``sessions`` collection grows, you can run additional
-map-reduce operations. For example, add new documents to the
-``sessions`` collection:
-
-.. code-block:: javascript
-
- 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 } );
-
-At the end of the day, perform incremental map-reduce on the
-``sessions`` collection but use the ``query`` field to select only the
-new documents. Output the results to the collection ``session_stat``,
-but ``reduce`` the contents with the results of the incremental
-map-reduce:
-
-.. code-block:: javascript
-
- db.sessions.mapReduce( mapFunction,
- reduceFunction,
- {
- query: { ts: { $gt: ISODate('2011-11-05 00:00:00') } },
- out: { reduce: "session_stat" },
- finalize: finalizeFunction
- }
- );
-
-.. _map-reduce-temporary-collection:
-
-Temporary Collection
---------------------
-
-The map-reduce operation uses a temporary collection during processing.
-At completion, the map-reduce operation renames the temporary
-collection. As a result, you can perform a map-reduce operation
-periodically with the same target collection name without affecting
-the intermediate states. Use this mode when
-generating statistical output collections on a regular basis.
-
-.. _map-reduce-concurrency:
-
-Concurrency
------------
-
-The map-reduce operation is composed of many tasks, including:
-
-- reads from the input collection,
-
-- executions of the ``map`` function,
-
-- executions of the ``reduce`` function,
-
-- writes to the output collection.
-
-These various tasks take the following locks:
-
-- The read phase takes a read lock. It yields every 100 documents.
-
-- The insert into the temporary collection takes a write lock for a
- single write.
-
- If the output collection does not exist, the creation of the output
- collection takes a write lock.
-
- If the output collection exists, then the output actions (i.e.
- ``merge``, ``replace``, ``reduce``) take a write lock.
-
-.. versionchanged:: 2.4
- The V8 JavaScript engine, which became the default in 2.4, allows
- multiple JavaScript operations to execute at the same time. Prior to
- 2.4, JavaScript code (i.e. ``map``, ``reduce``, ``finalize``
- functions) executed in a single thread.
-
-.. note::
-
- The final write lock during post-processing makes the results appear
- atomically. However, output actions ``merge`` and ``reduce`` may
- take minutes to process. For the ``merge`` and ``reduce``, the
- ``nonAtomic`` flag is available. See the
- :method:`db.collection.mapReduce()` reference for more information.
-
-.. _map-reduce-sharded-cluster:
-
-Sharded Cluster
----------------
-
-Sharded Input
-~~~~~~~~~~~~~
-
-When using sharded collection as the input for a map-reduce operation,
-:program:`mongos` will automatically dispatch the map-reduce job to
-each shard in parallel. There is no special option
-required. :program:`mongos` will wait for jobs on all shards to
-finish.
-
-Sharded Output
-~~~~~~~~~~~~~~
-
-By default the output collection is not sharded. The process is:
-
-- :program:`mongos` dispatches a map-reduce finish job to the shard
- that will store the target collection.
-
-- The target shard pulls results from all other shards, and runs a
- final reduce/finalize operation, and write to the output.
-
-- If using the ``sharded`` option to the ``out`` parameter, MongoDB
- shards the output using ``_id`` field as the shard key.
-
- .. versionchanged:: 2.2
-
-- If the output collection does not exist, MongoDB creates and shards
- the collection on the ``_id`` field. If the collection is empty,
- MongoDB creates :term:`chunks <chunk>` using the result of the first
- stage of the map-reduce operation.
-
-- :program:`mongos` dispatches, in parallel, a map-reduce finish job
- to every shard that owns a chunk.
-
-- Each shard will pull the results it owns from all other shards, run a
- final reduce/finalize, and write to the output collection.
-
-.. note::
-
- - During later map-reduce jobs, MongoDB splits chunks as needed.
-
- - Balancing of chunks for the output collection is automatically
- prevented during post-processing to avoid concurrency issues.
-
-In MongoDB 2.0:
-
-- :program:`mongos` retrieves the results from each shard, and
- performs merge sort to order the results, and performs a reduce/finalize as
- needed. :program:`mongos` then writes the result to the output
- collection in sharded mode.
-
-- This model requires only a small amount of memory, even for large datasets.
-
-- Shard chunks are not automatically split during insertion. This
- requires manual intervention until the chunks are granular and
- balanced.
-
-.. warning::
-
- For best results, only use the sharded output options for
- :dbcommand:`mapReduce` in version 2.2 or later.
-
-.. _map-reduce-troubleshooting:
-
-Troubleshooting Map-Reduce Operations
--------------------------------------
-
-You can troubleshoot the ``map`` function and the ``reduce`` function
-in the :program:`mongo` shell.
-
-.. _troubleshoot-map-function:
-
-Troubleshoot the Map Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can verify the ``key`` and ``value`` pairs emitted by the ``map``
-function by writing your own ``emit`` function.
-
-Consider a collection ``orders`` that contains documents of the
-following prototype:
-
-.. code-block:: javascript
-
- {
- _id: ObjectId("50a8240b927d5d8b5891743c"),
- cust_id: "abc123",
- ord_date: new Date("Oct 04, 2012"),
- status: 'A',
- price: 250,
- items: [ { sku: "mmm", qty: 5, price: 2.5 },
- { sku: "nnn", qty: 5, price: 2.5 } ]
- }
-
-#. Define the ``map`` function that maps the ``price`` to the
- ``cust_id`` for each document and emits the ``cust_id`` and ``price``
- pair:
-
- .. code-block:: javascript
-
- var map = function() {
- emit(this.cust_id, this.price);
- };
-
-#. Define the ``emit`` function to print the key and value:
-
- .. code-block:: javascript
-
- var emit = function(key, value) {
- print("emit");
- print("key: " + key + " value: " + tojson(value));
- }
-
-#. Invoke the ``map`` function with a single document from the ``orders``
- collection:
-
- .. code-block:: javascript
-
- var myDoc = db.orders.findOne( { _id: ObjectId("50a8240b927d5d8b5891743c") } );
- map.apply(myDoc);
-
-#. Verify the key and value pair is as you expected.
-
- .. code-block:: javascript
-
- emit
- key: abc123 value:250
-
-#. Invoke the ``map`` function with multiple documents from the ``orders``
- collection:
-
- .. code-block:: javascript
-
- var myCursor = db.orders.find( { cust_id: "abc123" } );
-
- while (myCursor.hasNext()) {
- var doc = myCursor.next();
- print ("document _id= " + tojson(doc._id));
- map.apply(doc);
- print();
- }
-
-#. Verify the key and value pairs are as you expected.
-
-.. _troubleshoot-reduce-function:
-
-Troubleshoot the Reduce Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Confirm Output Type
-```````````````````
-
-You can test that the ``reduce`` function returns a value that is the
-same type as the value emitted from the ``map`` function.
-
-#. Define a ``reduceFunction1`` function that takes the arguments
- ``keyCustId`` and ``valuesPrices``. ``valuesPrices`` is an array of
- integers:
-
- .. code-block:: javascript
-
- var reduceFunction1 = function(keyCustId, valuesPrices) {
- return Array.sum(valuesPrices);
- };
-
-#. Define a sample array of integers:
-
- .. code-block:: javascript
-
- var myTestValues = [ 5, 5, 10 ];
-
-#. Invoke the ``reduceFunction1`` with ``myTestValues``:
-
- .. code-block:: javascript
-
- reduceFunction1('myKey', myTestValues);
-
-#. Verify the ``reduceFunction1`` returned an integer:
-
- .. code-block:: javascript
-
- 20
-
-#. Define a ``reduceFunction2`` function that takes the arguments
- ``keySKU`` and ``valuesCountObjects``. ``valuesCountObjects`` is an array of
- documents that contain two fields ``count`` and ``qty``:
-
- .. code-block:: javascript
-
- var reduceFunction2 = function(keySKU, valuesCountObjects) {
- reducedValue = { count: 0, qty: 0 };
-
- for (var idx = 0; idx < valuesCountObjects.length; idx++) {
- reducedValue.count += valuesCountObjects[idx].count;
- reducedValue.qty += valuesCountObjects[idx].qty;
- }
-
- return reducedValue;
- };
-
-#. Define a sample array of documents:
-
- .. code-block:: javascript
-
- var myTestObjects = [
- { count: 1, qty: 5 },
- { count: 2, qty: 10 },
- { count: 3, qty: 15 }
- ];
-
-#. Invoke the ``reduceFunction2`` with ``myTestObjects``:
-
- .. code-block:: javascript
-
- reduceFunction2('myKey', myTestObjects);
-
-#. Verify the ``reduceFunction2`` returned a document with exactly the
- ``count`` and the ``qty`` field:
-
- .. code-block:: javascript
-
- { "count" : 6, "qty" : 30 }
-
-Ensure Insensitivity to the Order of Mapped Values
-``````````````````````````````````````````````````
-
-The ``reduce`` function takes a ``key`` and a ``values`` array as its
-argument. You can test that the result of the ``reduce`` function does
-not depend on the order of the elements in the ``values`` array.
-
-#. Define a sample ``values1`` array and a sample ``values2`` array
- that only differ in the order of the array elements:
-
- .. code-block:: javascript
-
- var values1 = [
- { count: 1, qty: 5 },
- { count: 2, qty: 10 },
- { count: 3, qty: 15 }
- ];
-
- var values2 = [
- { count: 3, qty: 15 },
- { count: 1, qty: 5 },
- { count: 2, qty: 10 }
- ];
-
-#. Define a ``reduceFunction2`` function that takes the arguments
- ``keySKU`` and ``valuesCountObjects``. ``valuesCountObjects`` is an array of
- documents that contain two fields ``count`` and ``qty``:
-
- .. code-block:: javascript
-
- var reduceFunction2 = function(keySKU, valuesCountObjects) {
- reducedValue = { count: 0, qty: 0 };
-
- for (var idx = 0; idx < valuesCountObjects.length; idx++) {
- reducedValue.count += valuesCountObjects[idx].count;
- reducedValue.qty += valuesCountObjects[idx].qty;
- }
-
- return reducedValue;
- };
-
-#. Invoke the ``reduceFunction2`` first with ``values1`` and then with
- ``values2``:
-
- .. code-block:: javascript
-
- reduceFunction2('myKey', values1);
- reduceFunction2('myKey', values2);
-
-#. Verify the ``reduceFunction2`` returned the same result:
-
- .. code-block:: javascript
-
- { "count" : 6, "qty" : 30 }
-
-Ensure Reduce Function Idempotentcy
-```````````````````````````````````
-
-Because the map-reduce operation may call a ``reduce`` multiple times
-for the same key, the ``reduce`` function must return a value of the
-same type as the value emitted from the ``map`` function. You can test
-that the ``reduce`` function process "reduced" values without
-affecting the *final* value.
-
-#. Define a ``reduceFunction2`` function that takes the arguments
- ``keySKU`` and ``valuesCountObjects``. ``valuesCountObjects`` is an array of
- documents that contain two fields ``count`` and ``qty``:
-
- .. code-block:: javascript
-
- var reduceFunction2 = function(keySKU, valuesCountObjects) {
- reducedValue = { count: 0, qty: 0 };
-
- for (var idx = 0; idx < valuesCountObjects.length; idx++) {
- reducedValue.count += valuesCountObjects[idx].count;
- reducedValue.qty += valuesCountObjects[idx].qty;
- }
-
- return reducedValue;
- };
-
-#. Define a sample key:
-
- .. code-block:: javascript
-
- var myKey = 'myKey';
-
-#. Define a sample ``valuesIdempotent`` array that contains an element that is a
- call to the ``reduceFunction2`` function:
-
- .. code-block:: javascript
-
- var valuesIdempotent = [
- { count: 1, qty: 5 },
- { count: 2, qty: 10 },
- reduceFunction2(myKey, [ { count:3, qty: 15 } ] )
- ];
-
-#. Define a sample ``values1`` array that combines the values passed to
- ``reduceFunction2``:
-
- .. code-block:: javascript
-
- var values1 = [
- { count: 1, qty: 5 },
- { count: 2, qty: 10 },
- { count: 3, qty: 15 }
- ];
-
-#. Invoke the ``reduceFunction2`` first with ``myKey`` and
- ``valuesIdempotent`` and then with ``myKey`` and ``values1``:
-
- .. code-block:: javascript
-
- reduceFunction2(myKey, valuesIdempotent);
- reduceFunction2(myKey, values1);
-
-#. Verify the ``reduceFunction2`` returned the same result:
-
- .. code-block:: javascript
-
- { "count" : 6, "qty" : 30 }
View
2 source/applications/optimization.txt
@@ -182,7 +182,7 @@ operations. Consider the following example:
server is more efficient than transmitting the collection to your
client and back again.
-For more information, see the :doc:`/applications/server-side-javascript`
+For more information, see the :doc:`/core/server-side-javascript`
page.
Use Capped Collections
View
792 source/applications/replication.txt
@@ -8,793 +8,13 @@ From the perspective of a client application, whether a MongoDB
instance is running as a single server (i.e. "standalone") or a :term:`replica set`
is transparent. However, replica sets
offer some configuration options for write and read operations. [#sharded-clusters]_
-This document describes those options and their implications.
+
+.. toctree::
+ :maxdepth: 1
+
+ /core/write-concern
+ /core/read-preference
.. [#sharded-clusters] :term:`Sharded clusters <sharded cluster>` where the
shards are also replica sets provide the same configuration options
with regards to write and read operations.
-
-.. _replica-set-write-concern:
-
-Write Concern
--------------
-
-MongoDB's built-in :term:`write concern` confirms the success of write
-operations to a :term:`replica set's <replica set>` :term:`primary`.
-Write concern uses the :dbcommand:`getLastError` command after write
-operations to return an object with error information or confirmation
-that there are no errors.
-
-After the :doc:`driver write concern change
-</release-notes/drivers-write-concern>` all officially supported
-MongoDB drivers enable write concern by default.
-
-Verify Write Operations
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The default write concern confirms write operations only on the
-primary. You can configure write concern to confirm write operations
-to additional replica set members as well by issuing the
-:dbcommand:`getLastError` command with the ``w`` option.
-
-The ``w`` option confirms that write operations have replicated to the
-specified number of replica set members, including the primary. You can
-either specify a number or specify ``majority``, which ensures the write
-propagates to a majority of set members. The following example ensures
-the operation has replicated to two members (the primary and one other
-member):
-
-.. code-block:: javascript
-
- db.runCommand( { getLastError: 1, w: 2 } )
-
-The following example ensures the write operation has replicated to a
-majority of the configured members of the set.
-
-.. code-block:: javascript
-
- db.runCommand( { getLastError: 1, w: "majority" } )
-
-If you specify a ``w`` value greater than the number of members that
-hold a copy of the data (i.e., greater than the number of
-non-:term:`arbiter` members), the operation blocks until those members
-become available. This can cause the operation to block forever. To
-specify a timeout threshold for the :dbcommand:`getLastError` operation,
-use the ``wtimeout`` argument. The following example sets the timeout to
-5000 milliseconds:
-
-.. code-block:: javascript
-
- db.runCommand( { getLastError: 1, w: 2, wtimeout:5000 } )
-
-Modify Default Write Concern
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can configure your own "default" :dbcommand:`getLastError`
-behavior for a replica set. Use the
-:data:`~local.system.replset.settings.getLastErrorDefaults` setting in
-the :doc:`replica set configuration
-</reference/replica-configuration>`. The following sequence of
-commands creates a configuration that waits for the write operation to
-complete on a majority of the set members before returning:
-
-.. code-block:: javascript
-
- cfg = rs.conf()
- cfg.settings = {}
- cfg.settings.getLastErrorDefaults = {w: "majority"}
- rs.reconfig(cfg)
-
-The :data:`~local.system.replset.settings.getLastErrorDefaults`
-setting affects only those :dbcommand:`getLastError` commands that
-have *no* other arguments.
-
-.. note::
-
- Use of insufficient write concern can lead to :ref:`rollbacks
- <replica-set-rollbacks>` in the case of :ref:`replica set failover
- <replica-set-failover>`. Always ensure that your operations have
- specified the required write concern for your application.
-
-.. seealso:: :ref:`write-operations-write-concern` and
- :ref:`connections-write-concern`
-
-Custom Write Concerns
-~~~~~~~~~~~~~~~~~~~~~
-
-You can use replica set tags to create custom write concerns using the
-:data:`~local.system.replset.settings.getLastErrorDefaults` and
-:data:`~local.system.replset.settings.getLastErrorModes` replica set
-settings.
-
-.. note::
-
- Custom write concern modes specify the field name and a number of
- *distinct* values for that field. By contrast, read preferences use
- the value of fields in the tag document to direct read operations.
-
- In some cases, you may be able to use the same tags for read
- preferences and write concerns; however, you may need to create
- additional tags for write concerns depending on the requirements of
- your application.
-
-Single Tag Write Concerns
-`````````````````````````
-
-Consider a five member replica set, where each member has one of the
-following tag sets:
-
-.. code-block:: javascript
-
- { "use": "reporting" }
- { "use": "backup" }
- { "use": "application" }
- { "use": "application" }
- { "use": "application" }
-
-You could create a custom write concern mode that will ensure that
-applicable write operations will not return until members with two
-different values of the ``use`` tag have acknowledged the write
-operation. Create the mode with the following sequence of operations
-in the :program:`mongo` shell:
-
-.. code-block:: javascript
-
- cfg = rs.conf()
- cfg.settings = { getLastErrorModes: { use2: { "use": 2 } } }
- rs.reconfig(cfg)
-
-.. these examples need to be better so that they avoid overwriting
- getLastErrorModes upon repetition (i.e. they don't $push documents
- to getLastErrorModes.)
-
-To use this mode pass the string ``multiUse`` to the ``w`` option of
-:dbcommand:`getLastError` as follows:
-
-.. code-block:: javascript
-
- db.runCommand( { getLastError: 1, w: use2 } )
-
-Specific Custom Write Concerns
-``````````````````````````````
-
-If you have a three member replica with the following tag sets:
-
-.. code-block:: javascript
-
- { "disk": "ssd" }
- { "disk": "san" }
- { "disk": "spinning" }
-
-You cannot specify a custom
-:data:`~local.system.replset.settings.getLastErrorModes` value to
-ensure that the write propagates to the ``san`` before
-returning. However, you may implement this write concern policy by
-creating the following additional tags, so that the set resembles the
-following:
-
-.. code-block:: javascript
-
- { "disk": "ssd" }
- { "disk": "san", "disk.san": "san" }
- { "disk": "spinning" }
-
-Then, create a custom
-:data:`~local.system.replset.settings.getLastErrorModes` value, as
-follows:
-
-.. code-block:: javascript
-
- cfg = rs.conf()
- cfg.settings = { getLastErrorModes: { san: { "disk.san": 1 } } }
- rs.reconfig(cfg)
-
-.. these examples need to be better so that they avoid overwriting
- getLastErrorModes upon repetition (i.e. they don't $push documents
- to getLastErrorModes.)
-
-To use this mode pass the string ``san`` to the ``w`` option of
-:dbcommand:`getLastError` as follows:
-
-.. code-block:: javascript
-
- db.runCommand( { getLastError: 1, w: san } )
-
-This operation will not return until a replica set member with the tag
-``disk.san`` returns.
-
-You may set a custom write concern mode as the default write concern
-mode using :data:`~local.system.replset.settings.getLastErrorDefaults`
-replica set as in the following setting:
-
-.. code-block:: javascript
-
- cfg = rs.conf()
- cfg.settings.getLastErrorDefaults = { ssd:1 }
- rs.reconfig(cfg)
-
-.. seealso:: :ref:`replica-set-configuration-tag-sets` for further
- information about replica set reconfiguration and tag sets.
-
-.. index:: read preference
-.. index:: slaveOk
-
-.. _replica-set-read-preference:
-.. _slaveOk:
-.. _read-preference:
-
-Read Preference
----------------
-
-Read preference describes how MongoDB clients route read operations to
-members of a :term:`replica set`.
-
-.. index:: read preference; background
-.. _replica-set-read-preference-background:
-
-Background
-~~~~~~~~~~
-
-By default, an application directs its read operations to the :term:`primary`
-member in a :term:`replica set`. Reading from the primary guarantees that
-read operations reflect the latest version of a document. However,
-for an application that does not require fully up-to-date data, you
-can improve read throughput, or reduce latency, by distributing some or all
-reads to secondary members of the replica set.
-
-The following are use cases where you might use secondary reads:
-
-- Running systems operations that do not affect the front-end
- application, operations such as backups and reports.
-
-- Providing low-latency queries for geographically distributed
- deployments. If one secondary is closer to an application server
- than the primary, you may see better
- performance for that application if you use secondary reads.
-
-- Providing graceful degradation in :ref:`failover
- <replica-set-failover>` situations where a set has *no* primary for 10
- seconds or more. In this use case, you should give the application the
- :readmode:`primaryPreferred` read preference, which prevents the
- application from performing reads if the set has no primary.
-
-MongoDB :term:`drivers <driver>` allow client applications to configure
-a :term:`read preference` on a per-connection, per-collection, or
-per-operation basis. For more information about secondary read
-operations in the :program:`mongo` shell, see the :method:`readPref() <cursor.readPref()>`
-method. For more information about a driver's read preference
-configuration, see the appropriate :ref:`driver` API documentation.
-
-.. note::
-
- Read preferences affect how an application selects which member
- to use for read operations. As a result read
- preferences dictate if the application receives stale or
- current data from MongoDB. Use appropriate :term:`write concern`
- policies to ensure proper data
- replication and consistency.
-
- If read operations account for a large percentage of your
- application's traffic, distributing reads to secondary members can
- improve read throughput. However, in most cases :doc:`sharding
- </core/sharded-clusters>` provides better support for larger scale
- operations, as clusters can distribute read and write
- operations across a group of machines.
-
-.. index:: read preference; semantics
-.. _replica-set-read-preference-semantics:
-.. index:: read preference; modes
-.. _replica-set-read-preference-modes:
-
-Read Preference Modes
-~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 2.2
-
-MongoDB :doc:`drivers </applications/drivers>` support five
-read preference modes:
-
-- :readmode:`primary`
-- :readmode:`primaryPreferred`
-- :readmode:`secondary`
-- :readmode:`secondaryPreferred`
-- :readmode:`nearest`
-
-You can specify a read preference mode on connection objects, database object,
-collection object, or per-operation. The syntax for specifying the read
-preference mode is :api:`specific to the driver and to the idioms of the host language <>`.
-
-Read preference modes are also available to clients connecting to a
-:term:`sharded cluster` through a :program:`mongos`. The
-:program:`mongos` instance obeys specified read preferences when
-connecting to the :term:`replica set` that provides each :term:`shard`
-in the cluster.
-
-In the :program:`mongo` shell, the
-:method:`readPref() <cursor.readPref()>` cursor method
-provides access to read preferences.
-
-.. warning::
-
- All read preference modes except :readmode:`primary` may return
- stale data as :term:`secondaries <secondary>` replicate operations
- from the primary with some delay.
-
- Ensure that your application can tolerate stale data if you choose
- to use a non-:readmode:`primary` mode.
-
-For more information, see :ref:`read preference background
-<replica-set-read-preference-background>` and :ref:`read preference
-behavior <replica-set-read-preference-behavior>`. See also the
-:api:`documentation for your driver <>`.
-
-.. readmode:: primary
-
- All read operations use only the current replica set :term:`primary`.
- This is the default. If the primary is unavailable,
- read operations produce an error or throw an exception.
-
- The :readmode:`primary` read preference mode is not compatible with
- read preference modes that use :ref:`tag sets
- <replica-set-read-preference-tag-sets>`. If you specify a tag set
- with :readmode:`primary`, the driver will produce an error.
-
-.. readmode:: primaryPreferred
-
- In most situations, operations read from the :term:`primary` member
- of the set. However, if the primary is unavailable, as is the case
- during :term:`failover` situations, operations read from secondary
- members.
-
- When the read preference includes a :ref:`tag set
- <replica-set-read-preference-tag-sets>`, the client reads first from
- the primary, if available, and then from :term:`secondaries
- <secondary>` that match the specified tags. If no secondaries have
- matching tags, the read operation produces an error.
-
- Since the application may receive data from a secondary, read
- operations using the :readmode:`primaryPreferred` mode may return
- stale data in some situations.
-
- .. warning::
-
- .. versionchanged:: 2.2
- :program:`mongos` added full support for read preferences.
-
- When connecting to a :program:`mongos` instance older than 2.2,
- using a client that supports read preference modes,
- :readmode:`primaryPreferred` will send queries to secondaries.
-
-.. readmode:: secondary
-
- Operations read *only* from the :term:`secondary` members of the set.
- If no secondaries are available, then this read operation produces an
- error or exception.
-
- Most sets have at least one secondary, but there are situations
- where there may be no available secondary. For example, a set
- with a primary, a secondary, and an :term:`arbiter` may not have
- any secondaries if a member is in recovering state or unavailable.
-
- When the read preference includes a :ref:`tag set
- <replica-set-read-preference-tag-sets>`, the client attempts to find
- secondary members that match the specified tag set and directs reads
- to a random secondary from among the :ref:`nearest group
- <replica-set-read-preference-behavior-nearest>`. If no secondaries
- have matching tags, the read operation produces an error. [#capacity-planning]_
-
- Read operations using the :readmode:`secondary` mode may return stale data.
-
-.. readmode:: secondaryPreferred
-
- In most situations, operations read from :term:`secondary` members,
- but in situations where the set consists of a single
- :term:`primary` (and no other members,) the read operation will use
- the set's primary.
-
- When the read preference includes a :ref:`tag set
- <replica-set-read-preference-tag-sets>`, the client attempts to find
- a secondary member that matches the specified tag set and directs
- reads to a random secondary from among the :ref:`nearest group
- <replica-set-read-preference-behavior-nearest>`. If no secondaries
- have matching tags, the read operation produces an error.
-
- Read operations using the :readmode:`secondaryPreferred` mode may return stale data.
-
-.. readmode:: nearest
-
- The driver reads from the *nearest* member of the :term:`set <replica
- set>` according to the :ref:`member selection
- <replica-set-read-preference-behavior-nearest>` process. Reads in
- the :readmode:`nearest` mode do not consider the member's
- *type*. Reads in :readmode:`nearest` mode may read from both
- primaries and secondaries.
-
- Set this mode to minimize the effect of network latency
- on read operations without preference for current or stale data.
-
- If you specify a :ref:`tag set <replica-set-read-preference-tag-sets>`,
- the client attempts to find a replica set member that matches the
- specified tag set and directs reads to an arbitrary member from
- among the :ref:`nearest group <replica-set-read-preference-behavior-nearest>`.
-
- Read operations using the :readmode:`nearest` mode may return stale data.
-
- .. note::
-
- All operations read from a member of the nearest group of the
- replica set that matches the specified read preference mode. The
- :readmode:`nearest` mode prefers low latency reads over a
- member's :term:`primary` or :term:`secondary` status.
-
- For :readmode:`nearest`, the client assembles a list of
- acceptable hosts based on tag set and then narrows that list to
- the host with the shortest ping time and all other members of
- the set that are within the "local threshold," or acceptable
- latency. See :ref:`replica-set-read-preference-behavior-nearest`
- for more information.
-
- .. For I/O-bound users who want to distribute reads across all
- members evenly regardless of ping time, set
- secondaryAcceptableLatencyMS very high.
-
-.. The :method:`readPreference() <cursor.readPreference()>` reference
- above will error until DOCS-364 is complete.
-
-.. [#capacity-planning] If your set has more than one secondary, and
- you use the :readmode:`secondary` read preference mode, consider
- the following effect. If you have a :ref:`three member replica set
- <replica-set-three-members>` with a primary and two secondaries,
- and if one secondary becomes unavailable, all :readmode:`secondary`
- queries must target the remaining secondary. This will double the
- load on this secondary. Plan and provide capacity to support this
- as needed.
-
-.. index:: tag sets
-.. index:: read preference; tag sets
-.. _replica-set-read-preference-tag-sets:
-
-Tag Sets
-~~~~~~~~
-
-Tag sets allow you to specify custom :ref:`read preferences
-<replica-set-read-preference>`
-and :ref:`write concerns <write-operations-write-concern>`
-so that your application can target
-operations to specific members, based on custom parameters.
-
-.. note::
-
- Consider the following properties of read preferences:
-
- - Custom read preferences and write concerns evaluate tags sets in
- different ways.
-
- - Read preferences consider the value of a tag when selecting a
- member to read from.
-
- - Write concerns ignore the value of a tag to when selecting a
- member *except* to consider whether or not the value is unique.
-
-A tag set for a read operation may resemble the following document:
-
-.. code-block:: javascript
-
- { "disk": "ssd", "use": "reporting" }
-
-To fulfill the request, a member would need to have both of these tags.
-Therefore the following tag sets, would satisfy this
-requirement:
-
-.. code-block:: javascript
-
- { "disk": "ssd", "use": "reporting" }
- { "disk": "ssd", "use": "reporting", "rack": 1 }
- { "disk": "ssd", "use": "reporting", "rack": 4 }
- { "disk": "ssd", "use": "reporting", "mem": "64"}
-
-However, the following tag sets would *not* be able to fulfill this query:
-
-.. code-block:: javascript
-
- { "disk": "ssd" }
- { "use": "reporting" }
- { "disk": "ssd", "use": "production" }
- { "disk": "ssd", "use": "production", "rack": 3 }
- { "disk": "spinning", "use": "reporting", "mem": "32" }
-
-Therefore, tag sets make it possible to ensure that read operations
-target specific members in a particular data center or
-:program:`mongod` instances designated for a particular class of
-operations, such as reporting or analytics.
-For information on configuring tag sets, see
-:ref:`replica-set-configuration-tag-sets` in the
-:doc:`/reference/replica-configuration` document.
-You can specify tag sets with the following read preference modes:
-
-- :readmode:`primaryPreferred`
-- :readmode:`secondary`
-- :readmode:`secondaryPreferred`
-- :readmode:`nearest`
-
-You cannot specify tag sets with the :readmode:`primary` read preference mode.
-
-Tags are not compatible with :readmode:`primary` and only apply when
-:ref:`selecting <replica-set-read-preference-behavior-member-selection>`
-a :term:`secondary` member of a set for a read operation. However, the
-:readmode:`nearest` read mode, when combined with a tag set will
-select the nearest member that matches the specified tag set, which
-may be a primary or secondary.
-
-All interfaces use the same :ref:`member selection logic
-<replica-set-read-preference-behavior-member-selection>` to choose the
-member to which to direct read operations, basing the choice on read
-preference mode and tag sets.
-
-For more information on how read preference :ref:`modes
-<replica-set-read-preference-modes>` interact with tag sets, see the
-documentation for each read preference mode.
-
-.. index:: read preference; behavior
-.. _replica-set-read-preference-behavior:
-
-Behavior
-~~~~~~~~
-
-.. versionchanged:: 2.2
-
-.. _replica-set-read-preference-behavior-retry:
-
-Auto-Retry
-``````````
-
-Connection between MongoDB drivers and :program:`mongod` instances in
-a :term:`replica set` must balance two concerns:
-
-#. The client should attempt to prefer current results, and any
- connection should read from the same member of the replica set as
- much as possible.
-
-#. The client should minimize the amount of time that the database is
- inaccessible as the result of a connection issue, networking
- problem, or :term:`failover` in a replica set.
-
-As a result, MongoDB drivers and :program:`mongos`:
-
-- Reuse a connection to specific :program:`mongod` for as long as
- possible after establishing a connection to that instance. This
- connection is *pinned* to this :program:`mongod`.
-
-- Attempt to reconnect to a new member, obeying existing :ref:`read
- preference modes <replica-set-read-preference-modes>`, if the connection
- to :program:`mongod` is lost.
-
- Reconnections are transparent to the application itself. If
- the connection permits reads from :term:`secondary` members, after
- reconnecting, the application can receive two sequential reads
- returning from different secondaries. Depending on the state of the
- individual secondary member's replication, the documents can reflect
- the state of your database at different moments.
-
-- Return an error *only* after attempting to connect to three members
- of the set that match the :ref:`read preference mode <replica-set-read-preference-modes>`
- and :ref:`tag set <replica-set-read-preference-tag-sets>`.
- If there are fewer than three members of the set, the
- client will error after connecting to all existing members of the
- set.
-
- After this error, the driver selects a new member using the
- specified read preference mode. In the absence of a specified read
- preference, the driver uses :readmode:`primary`.
-
-- After detecting a failover situation, [#fn-failover]_ the driver
- attempts to refresh the state of the replica set as quickly as
- possible.
-
-.. [#fn-failover] When a :term:`failover` occurs, all members of the set
- close all client connections that produce a socket error in the
- driver. This behavior prevents or minimizes :term:`rollback`.
-
-.. _replica-set-read-preference-behavior-requests:
-
-Request Association
-```````````````````
-
-Reads from :term:`secondary` may reflect the state of the data set at
-different points in time because :term:`secondary` members of a
-:term:`replica set` may lag behind the current state of the primary by
-different amounts. To prevent subsequent reads from jumping around in
-time, the driver can associate application threads to a specific member
-of the set after the first read. The thread will continue to read from
-the same member until:
-
-- The application performs a read with a different read preference.
-
-- The thread terminates.
-
-- The client receives a socket exception, as is
- the case when there's a network error or when
- the :program:`mongod` closes connections during a :term:`failover`.
- This triggers a :ref:`retry
- <replica-set-read-preference-behavior-retry>`, which may be
- transparent to the application.
-
-If an application thread issues a query with the
-:readmode:`primaryPreferred` mode while the primary is inaccessible,
-the thread will carry the association with that secondary for the
-lifetime of the thread. The thread will associate with the primary, if
-available, only after issuing a query with a different read
-preference, even if a primary becomes available. By extension, if a
-thread issues a read with the :readmode:`secondaryPreferred` when all
-secondaries are down, it will carry an association with the
-primary. This application thread will continue to read from the
-primary even if a secondary becomes available later in the thread's
-lifetime.
-
-.. index:: read preference; ping time
-.. index:: read preference; nearest
-.. index:: read preference; member selection
-.. _replica-set-read-preference-behavior-ping-time:
-.. _replica-set-read-preference-behavior-nearest:
-.. _replica-set-read-preference-behavior-member-selection:
-
-Member Selection
-````````````````
-
-Clients, by way of their drivers, and :program:`mongos` instances for
-sharded clusters periodically update their view of the replica set's state:
-which members are up or down, which member is primary, and the latency to each
-:program:`mongod` instance.
-
-For any operation that targets a member *other* than the
-:term:`primary`, the driver:
-
-#. Assembles a list of suitable members, taking into account member type
- (i.e. secondary, primary, or all members.)
-
-#. Excludes members not matching the tag sets, if specified.
-
-#. Determines which suitable member is the closest to the
- client in absolute terms.
-
-#. Builds a list of members that are within a defined ping distance (in
- milliseconds) of the "absolute nearest" member. [#acceptable-secondary-latency]_
-
-#. Selects a member from these hosts at random. The member receives the read operation.
-
-Once the application selects a member of the set to use for read
-operations, the driver continues to use this connection for read
-preference until the application specifies a new read preference or
-something interrupts the connection. See :ref:`replica-set-read-preference-behavior-requests`
-for more information.
-
-.. [#acceptable-secondary-latency] Applications can configure the
- threshold used in this stage. The default "acceptable latency" is
- 15 milliseconds, which you can override in the drivers with their own
- ``secondaryAcceptableLatencyMS`` option.
- For :program:`mongos` you can use the :option:`--localThreshold <mongos --localThreshold>` or
- :setting:`localThreshold` runtime options to set this value.
-
-.. index:: read preference; sharding
-.. index:: read preference; mongos
-.. _replica-set-read-preference-behavior-sharding:
-.. _replica-set-read-preference-behavior-mongos:
-
-Sharding and ``mongos``
-```````````````````````
-
-.. versionchanged:: 2.2
- Before version 2.2, :program:`mongos` did not support the
- :ref:`read preference mode semantics <replica-set-read-preference-modes>`.
-
-In most :term:`sharded clusters <sharded cluster>`, a :term:`replica set`
-provides each shard where read preferences are also applicable. Read
-operations in a sharded cluster, with regard to read preference, are
-identical to unsharded replica sets.
-
-Unlike simple replica sets, in sharded clusters, all interactions with
-the shards pass from the clients to the :program:`mongos` instances
-that are actually connected to the set members. :program:`mongos` is
-responsible for the application of the read preferences, which is
-transparent to applications.
-
-There are no configuration changes required for full support of read
-preference modes in sharded environments, as long as the
-:program:`mongos` is at least version 2.2. All :program:`mongos`
-maintain their own connection pool to the replica set members. As a
-result:
-
-- A request without a specified preference has
- :readmode:`primary`, the default, unless, the :program:`mongos`
- reuses an existing connection that has a different mode set.
-
- Always explicitly set your read preference mode to prevent
- confusion.
-
-- All :readmode:`nearest` and latency calculations reflect the
- connection between the :program:`mongos` and the :program:`mongod`
- instances, not the client and the :program:`mongod` instances.
-
- This produces the desired result, because all results must pass
- through the :program:`mongos` before returning to the client.
-
-Database Commands
-`````````````````
-
-Because some :term:`database commands <database command>` read and
-return data from the database, all of the official drivers support
-full :ref:`read preference mode semantics <replica-set-read-preference-modes>`
-for the following commands:
-
-- :dbcommand:`group`
-- :dbcommand:`mapReduce` [#inline-map-reduce]_
-- :dbcommand:`aggregate`
-- :dbcommand:`collStats`
-- :dbcommand:`dbStats`
-- :dbcommand:`count`
-- :dbcommand:`distinct`
-- :dbcommand:`geoNear`
-- :dbcommand:`geoSearch`
-- :dbcommand:`geoWalk`
-
-.. [#inline-map-reduce] Only "inline" :dbcommand:`mapReduce`
- operations that do not write data support read preference,
- otherwise these operations must run on the :term:`primary`
- members.
-
-:program:`mongos` currently does not route commands using read
-preferences; clients send all commands to shards' primaries. See
-:issue:`SERVER-7423`.
-
-Uses for non-Primary Read Preferences
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You must exercise care when specifying read preferences: modes other
-than :readmode:`primary` can *and will* return stale data. These
-secondary queries will not
-include the most recent write operations to the replica set's
-:term:`primary`. Nevertheless, there are several common use cases for
-using non-:readmode:`primary` read preference modes:
-
-- Reporting and analytics workloads.
-
- Having these queries target a :term:`secondary` helps distribute
- load and prevent these operations from affecting the main workload
- of the primary.
-
- Also consider using :readmode:`secondary` in conjunction with a
- direct connection to a :ref:`hidden member <replica-set-hidden-members>` of the set.
-
-- Providing local reads for geographically distributed applications.
-
- If you have application servers in multiple data centers, you may
- consider having a :ref:`geographically distributed replica set
- <replica-set-geographical-distribution>` and using a non primary
- read preference or the :readmode:`nearest` to avoid network
- latency.
-
-- Maintaining availability during a failover.
-
- Use :readmode:`primaryPreferred` if you want your application to do
- consistent reads from the primary under normal circumstances, but to
- allow stale reads from secondaries in an emergency. This provides a
- "read-only mode" for your application during a failover.
-
-.. warning::
-
- In some situations using :readmode:`secondaryPreferred` to
- distribute read load to replica sets may carry significant
- operational risk: if all secondaries are unavailable and your set
- has enough :term:`arbiters <arbiter>` to prevent the primary from
- stepping down, then the primary will receive all traffic from
- clients.
-
- For this reason, use :readmode:`secondary` to distribute read load
- to replica sets, not :readmode:`secondaryPreferred`.
-
-Using read modes other than :readmode:`primary` and
-:readmode:`primaryPreferred` to provide extra capacity is not in and
-of itself justification for non-:readmode:`primary` in many
-cases. Furthermore, :doc:`sharding </sharding>` increases read and
-write capacity by distributing read and write operations across a
-group of machines.
View
164 source/applications/server-side-javascript.txt
@@ -1,164 +0,0 @@
-======================
-Server-side JavaScript
-======================
-
-.. default-domain:: mongodb
-
-MongoDB supports server-side execution of JavaScript code within the
-database process.
-
-.. note::
-
- The JavaScript code execution takes a JavaScript lock: each
- :program:`mongod` can only execute a single JavaScript operation at
- a time.
-
-.. include:: /includes/fact-disable-javascript-with-noscript.rst
-
-.. _server-side-map-reduce:
-
-Map-Reduce
-----------
-
-MongoDB performs the execution of JavaScript functions for
-:doc:`/applications/map-reduce` operations on the server. Within these
-JavaScript functions, you must not access the database for any reason,
-including to perform reads.
-
-See the :method:`db.collection.mapReduce()` and the
-:doc:`/applications/map-reduce` documentation for more information,
-including examples of map-reduce. See :ref:`map-reduce concurrency
-<map-reduce-concurrency>` section for concurrency information for
-map-reduce.
-
-.. _server-side-eval:
-
-``eval`` Command
-----------------
-
-The :dbcommand:`eval` command, and the corresponding :program:`mongo`
-shell method :method:`db.eval()`, evaluates JavaScript functions on the
-database server. This command may be useful if you need to touch a lot
-of data lightly since the network transfer of the data could become a
-bottleneck if performing these operations on the client-side.
-
-.. warning::
-
- By default, :dbcommand:`eval` command requires a write lock. As
- such :dbcommand:`eval` will block all other read and write
- operations while it runs. Because only a single JavaScript process
- can run at a time, *do not* run :dbcommand:`mapReduce`,
- :dbcommand:`group`, queries with the :operator:`$where` or any
- other operation that requires JavaScript execution within
- :dbcommand:`eval` operations.
-
-See :dbcommand:`eval` command and :method:`db.eval()` documentation for
-more information, including examples.
-
-.. _running-js-scripts-in-mongo-on-mongod-host:
-
-Running ``.js`` files via a ``mongo`` shell Instance on the Server
-------------------------------------------------------------------
-
-Running a JavaScript (``.js``) file using a :program:`mongo` shell
-instance on the server is a good technique for performing batch
-administrative work. When you run :program:`mongo` shell on the
-server, connecting via the localhost interface, the connection is fast
-with low latency. Additionally, this technique has the advantage over
-the :dbcommand:`eval` command since the command :dbcommand:`eval`
-blocks all other operations.
-
-.. _server-side-where:
-
-``$where`` Operator
--------------------
-
-To perform :doc:`/core/read-operations`, in addition to the standard
-operators (e.g. :operator:`$gt`, :operator:`$lt`), with the
-:operator:`$where` operator, you can also express the query condition
-either as a string or a full JavaScript function that specifies a
-SQL-like ``WHERE`` clause. However, use the standard operators whenever
-possible since :operator:`$where` operations have significantly slower
-performance.
-
-.. warning::
-
- Do not write to the database within the :operator:`$where`
- JavaScript function.
-
-See :operator:`$where` documentation for more information, including
-examples.
-
-.. _storing-server-side-javascript:
-
-Storing Functions Server-side
------------------------------
-
-.. note::
-
- We do **not** recommend using server-side stored functions if
- possible.
-
-There is a special system collection named ``system.js`` that can store
-JavaScript functions for reuse.
-
-To store a function, you can use the :method:`db.collection.save()`, as
-in the following example:
-
-.. code-block:: javascript
-
- db.system.js.save(
- {
- _id : "myAddFunction" ,
- value : function (x, y){ return x + y; }
- }
- );
-
-- The ``_id`` field holds the name of the function and is unique per
- database.
-
-- The ``value`` field holds the function definition
-
-Once you save a function in the ``system.js`` collection, you can use
-the function from any JavaScript context (e.g. :ref:`eval
-<server-side-eval>`, :ref:`$where <server-side-where>`,
-:ref:`map-reduce <server-side-map-reduce>`).
-
-Consider the following example from the :program:`mongo` shell that
-first saves a function named ``echoFunction`` to the ``system.js``
-collection and calls the function using :ref:`db.eval()
-<server-side-eval>`:
-
-.. code-block:: javascript
-
- db.system.js.save(
- { _id: "echoFunction",
- value : function(x) { return x; }
- }
- )
-
- db.eval( "echoFunction( 'test' )" )
-
-See `<http://github.com/mongodb/mongo/tree/master/jstests/storefunc.js>`_ for a full example.
-
-.. versionadded:: 2.1
- In the :program:`mongo` shell, you can use
- :method:`db.loadServerScripts()` to load all the scripts saved in
- the ``system.js`` collection for the current db. Once loaded, you
- can invoke the functions directly in the shell, as in the following
- example:
-
-.. code-block:: javascript
-
- db.loadServerScripts();
-
- echoFunction(3);
-
- myAddFunction(3, 5);
-
-Concurrency
------------
-
-Refer to the individual method or operator documentation for any
-concurrency information. See also the :ref:`concurrency table
-<faq-concurrency-operations-locks>`.
View
0 source/applications/aggregation.txt → source/core/aggregation.txt
File renamed without changes.
View
8 source/applications/create.txt → source/core/create.txt
@@ -106,7 +106,7 @@ create this collection:
}
)
-You can confirm the insert by :doc:`querying </applications/read>`
+You can confirm the insert by :doc:`querying </core/read>`
the ``bios`` collection:
.. code-block:: javascript
@@ -365,7 +365,7 @@ the ``_id`` field:
The :method:`~db.collection.update()` operation in MongoDB accepts an
"``upsert``" flag that modifies the behavior of
:method:`~db.collection.update()` from :doc:`updating existing documents
-</applications/update>`, to inserting data.
+</core/update>`, to inserting data.
These :method:`~db.collection.update()` operations with the upsert
flag eliminate the need to perform an additional operation to check
@@ -374,10 +374,10 @@ insert operation. These update operations have the use ``<query>``
argument to determine the write operation:
- If the query matches an existing document(s), the operation is an
- :doc:`update </applications/update>`.
+ :doc:`update </core/update>`.
- If the query matches no document in the collection, the operation is
- an :doc:`insert </applications/create>`.
+ an :doc:`insert </core/create>`.
An upsert operation has the following syntax:
View
0 source/applications/delete.txt → source/core/delete.txt
File renamed without changes.
View
8 source/core/document.txt
@@ -275,13 +275,13 @@ for MongoDB to return, remove, or update, as in the following:
.. seealso::
- :ref:`read-operations-query-argument` and
- :doc:`/applications/read` for more examples on selecting documents
+ :doc:`/core/read` for more examples on selecting documents
for reads.
- - :doc:`/applications/update` for more examples on
+ - :doc:`/core/update` for more examples on
selecting documents for updates.
- - :doc:`/applications/delete` for more examples on selecting
+ - :doc:`/core/delete` for more examples on selecting
documents for deletes.
.. _documents-update-actions:
@@ -339,7 +339,7 @@ When passed as an argument to the :method:`update()
- :ref:`update operators <update-operators>` page for the available
update operators and syntax.
- - :doc:`update </applications/update>` for more examples on
+ - :doc:`update </core/update>` for more examples on
update documents.
For additional examples of updates that involve array elements,
View
4 source/core/import-export.txt
@@ -50,8 +50,8 @@ with the database itself.
If you want to transform and process data once you've imported it
in MongoDB consider the topics in :doc:`/aggregation`, including:
- - :doc:`/applications/map-reduce` and
- - :doc:`/applications/aggregation`.
+ - :doc:`/core/map-reduce` and
+ - :doc:`/core/aggregation`.
.. _bson-json-type-conversion-fidelity:
View
159 source/core/map-reduce.txt
@@ -0,0 +1,159 @@
+==========
+Map-Reduce
+==========
+
+.. default-domain:: mongodb
+
+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.
+
+Examples
+--------
+
+For examples of map-reduce, see
+
+.. toctree::
+ :maxdepth: 1
+
+ /tutorial/map-reduce-examples
+ /tutorial/perform-incremental-map-reduce
+
+For many simple aggregation tasks, see the :doc:`aggregation framework
+</core/aggregation>`.
+
+.. _map-reduce-temporary-collection:
+
+Temporary Collection
+--------------------
+
+The map-reduce operation uses a temporary collection during processing.
+At completion, the map-reduce operation renames the temporary
+collection. As a result, you can perform a map-reduce operation
+periodically with the same target collection name without affecting
+the intermediate states. Use this mode when
+generating statistical output collections on a regular basis.
+
+.. _map-reduce-concurrency:
+
+Concurrency
+-----------
+
+The map-reduce operation is composed of many tasks, including:
+
+- reads from the input collection,
+
+- executions of the ``map`` function,
+
+- executions of the ``reduce`` function,
+
+- writes to the output collection.
+
+These various tasks take the following locks:
+
+- The read phase takes a read lock. It yields every 100 documents.
+
+- The insert into the temporary collection takes a write lock for a
+ single write.
+
+ If the output collection does not exist, the creation of the output
+ collection takes a write lock.
+
+ If the output collection exists, then the output actions (i.e.
+ ``merge``, ``replace``, ``reduce``) take a write lock.
+
+.. versionchanged:: 2.4
+ The V8 JavaScript engine, which became the default in 2.4, allows
+ multiple JavaScript operations to execute at the same time. Prior to
+ 2.4, JavaScript code (i.e. ``map``, ``reduce``, ``finalize``
+ functions) executed in a single thread.
+
+.. note::
+
+ The final write lock during post-processing makes the results appear
+ atomically. However, output actions ``merge`` and ``reduce`` may
+ take minutes to process. For the ``merge`` and ``reduce``, the
+ ``nonAtomic`` flag is available. See the
+ :method:`db.collection.mapReduce()` reference for more information.
+
+.. _map-reduce-sharded-cluster:
+
+Sharded Cluster
+---------------
+
+Sharded Input
+~~~~~~~~~~~~~
+
+When using sharded collection as the input for a map-reduce operation,
+:program:`mongos` will automatically dispatch the map-reduce job to
+each shard in parallel. There is no special option
+required. :program:`mongos` will wait for jobs on all shards to
+finish.
+
+Sharded Output
+~~~~~~~~~~~~~~
+
+By default the output collection is not sharded. The process is:
+
+- :program:`mongos` dispatches a map-reduce finish job to the shard
+ that will store the target collection.
+
+- The target shard pulls results from all other shards, and runs a
+ final reduce/finalize operation, and write to the output.
+
+- If using the ``sharded`` option to the ``out`` parameter, MongoDB
+ shards the output using ``_id`` field as the shard key.
+
+ .. versionchanged:: 2.2
+
+- If the output collection does not exist, MongoDB creates and shards
+ the collection on the ``_id`` field. If the collection is empty,
+ MongoDB creates :term:`chunks <chunk>` using the result of the first
+ stage of the map-reduce operation.
+
+- :program:`mongos` dispatches, in parallel, a map-reduce finish job
+ to every shard that owns a chunk.
+
+- Each shard will pull the results it owns from all other shards, run a
+ final reduce/finalize, and write to the output collection.
+
+.. note::
+
+ - During later map-reduce jobs, MongoDB splits chunks as needed.
+
+ - Balancing of chunks for the output collection is automatically
+ prevented during post-processing to avoid concurrency issues.
+
+In MongoDB 2.0:
+
+- :program:`mongos` retrieves the results from each shard, and
+ performs merge sort to order the results, and performs a reduce/finalize as
+ needed. :program:`mongos` then writes the result to the output
+ collection in sharded mode.
+
+- This model requires only a small amount of memory, even for large datasets.
+
+- Shard chunks are not automatically split during insertion. This
+ requires manual intervention until the chunks are granular and
+ balanced.
+
+.. warning::
+
+ For best results, only use the sharded output options for
+ :dbcommand:`mapReduce` in version 2.2 or later.
+
+.. _map-reduce-troubleshooting:
+
+Troubleshooting Map-Reduce Operations
+-------------------------------------
+
+You can troubleshoot the ``map`` function and the ``reduce`` function
+in the :program:`mongo` shell. See the following tutorials for more
+information:
+
+.. toctree::
+ :maxdepth: 1
+
+ /tutorial/troubleshoot-map-function
+ /tutorial/troubleshoot-reduce-function
View
4 source/core/operational-segregation.txt
@@ -50,10 +50,10 @@ Specifically, with MongoDB, you can:
For full documentation of these features, see the following
documentation in the MongoDB Manual:
-- :ref:`Read Preferences <read-preference>`, which controls how drivers
+- :doc:`Read Preferences </core/read-preference>`, which controls how drivers
help applications target read operations to members of a replica set.
-- :ref:`Write Concerns <replica-set-write-concern>`, which controls
+- :doc:`Write Concerns </core/write-concern>`, which controls
how MongoDB ensures that write operations propagate to members of a
replica set.
View
8 source/core/read-operations.txt
@@ -90,7 +90,7 @@ syntax:
db.collection.findOne( <query>, <projection> )
For additional documentation and examples of the main MongoDB read
-operators, refer to the :doc:`/applications/read` page of the
+operators, refer to the :doc:`/core/read` page of the
:doc:`/crud` section.
.. [#formal-query-structure] :method:`db.collection.find()` is a
@@ -974,7 +974,7 @@ operations for more basic data aggregation operations:
- :dbcommand:`mapReduce`. (Also consider
:method:`~db.collection.mapReduce()` and
- :doc:`/applications/map-reduce`.)
+ :doc:`/core/map-reduce`.)
.. index:: read operation; architecture
.. _read-operations-architecture:
@@ -1055,6 +1055,6 @@ applications don't rely on this kind of strict consistency, but
application developers should always consider the needs of their
application before setting read preference.
-For more information on :ref:`read preferences <read-preference>` or
-on the read preference modes, see :ref:`read-preference` and
+For more information on read preference or on the read preference
+modes, see :doc:`/core/read-preference` and
:ref:`replica-set-read-preference-modes`.
View
581 source/core/read-preference.txt
@@ -0,0 +1,581 @@
+===============
+Read Preference
+===============
+
+.. default-domain:: mongodb
+
+Read preference describes how MongoDB clients route read operations to
+members of a :term:`replica set`.
+
+.. index:: read preference
+.. index:: slaveOk
+.. index:: read preference; background
+.. _replica-set-read-preference:
+.. _replica-set-read-preference-background:
+
+Background
+~~~~~~~~~~
+
+By default, an application directs its read operations to the :term:`primary`
+member in a :term:`replica set`. Reading from the primary guarantees that
+read operations reflect the latest version of a document. However,
+for an application that does not require fully up-to-date data, you
+can improve read throughput, or reduce latency, by distributing some or all
+reads to secondary members of the replica set.
+
+The following are use cases where you might use secondary reads:
+
+- Running systems operations that do not affect the front-end
+ application, operations such as backups and reports.
+
+- Providing low-latency queries for geographically distributed
+ deployments. If one secondary is closer to an application server
+ than the primary, you may see better
+ performance for that application if you use secondary reads.
+
+- Providing graceful degradation in :ref:`failover
+ <replica-set-failover>` situations where a set has *no* primary for 10
+ seconds or more. In this use case, you should give the application the
+ :readmode:`primaryPreferred` read preference, which prevents the
+ application from performing reads if the set has no primary.
+
+MongoDB :term:`drivers <driver>` allow client applications to configure
+a :term:`read preference` on a per-connection, per-collection, or
+per-operation basis. For more information about secondary read
+operations in the :program:`mongo` shell, see the :method:`readPref() <cursor.readPref()>`
+method. For more information about a driver's read preference
+configuration, see the appropriate :ref:`driver` API documentation.
+
+.. note::
+
+ Read preferences affect how an application selects which member
+ to use for read operations. As a result read
+ preferences dictate if the application receives stale or
+ current data from MongoDB. Use appropriate :term:`write concern`
+ policies to ensure proper data
+ replication and consistency.
+
+ If read operations account for a large percentage of your
+ application's traffic, distributing reads to secondary members can
+ improve read throughput. However, in most cases :doc:`sharding
+ </core/sharded-clusters>` provides better support for larger scale
+ operations, as clusters can distribute read and write
+ operations across a group of machines.
+
+.. index:: read preference; semantics
+.. _replica-set-read-preference-semantics:
+.. index:: read preference; modes
+.. _replica-set-read-preference-modes:
+
+Read Preference Modes
+---------------------
+
+.. versionadded:: 2.2
+
+MongoDB :doc:`drivers </applications/drivers>` support five
+read preference modes:
+
+- :readmode:`primary`
+- :readmode:`primaryPreferred`
+- :readmode:`secondary`
+- :readmode:`secondaryPreferred`
+- :readmode:`nearest`
+
+You can specify a read preference mode on connection objects, database object,
+collection object, or per-operation. The syntax for specifying the read
+preference mode is :api:`specific to the driver and to the idioms of the host language <>`.
+
+Read preference modes are also available to clients connecting to a
+:term:`sharded cluster` through a :program:`mongos`. The
+:program:`mongos` instance obeys specified read preferences when
+connecting to the :term:`replica set` that provides each :term:`shard`
+in the cluster.
+
+In the :program:`mongo` shell, the
+:method:`readPref() <cursor.readPref()>` cursor method
+provides access to read preferences.
+
+.. warning::
+
+ All read preference modes except :readmode:`primary` may return
+ stale data as :term:`secondaries <secondary>` replicate operations
+ from the primary with some delay.
+
+ Ensure that your application can tolerate stale data if you choose
+ to use a non-:readmode:`primary` mode.
+
+For more information, see :ref:`read preference background
+<replica-set-read-preference-background>` and :ref:`read preference
+behavior <replica-set-read-preference-behavior>`. See also the
+:api:`documentation for your driver <>`.
+
+.. readmode:: primary
+
+ All read operations use only the current replica set :term:`primary`.
+ This is the default. If the primary is unavailable,
+ read operations produce an error or throw an exception.
+
+ The :readmode:`primary` read preference mode is not compatible with
+ read preference modes that use :ref:`tag sets
+ <replica-set-read-preference-tag-sets>`. If you specify a tag set
+ with :readmode:`primary`, the driver will produce an error.
+
+.. readmode:: primaryPreferred
+
+ In most situations, operations read from the :term:`primary` member
+ of the set. However, if the primary is unavailable, as is the case
+ during :term:`failover` situations, operations read from secondary
+ members.
+
+ When the read preference includes a :ref:`tag set
+ <replica-set-read-preference-tag-sets>`, the client reads first from
+ the primary, if available, and then from :term:`secondaries
+ <secondary>` that match the specified tags. If no secondaries have
+ matching tags, the read operation produces an error.
+
+ Since the application may receive data from a secondary, read
+ operations using the :readmode:`primaryPreferred` mode may return
+ stale data in some situations.
+
+ .. warning::
+
+ .. versionchanged:: 2.2
+ :program:`mongos` added full support for read preferences.
+
+ When connecting to a :program:`mongos` instance older than 2.2,
+ using a client that supports read preference modes,
+ :readmode:`primaryPreferred` will send queries to secondaries.
+
+.. readmode:: secondary
+
+ Operations read *only* from the :term:`secondary` members of the set.
+ If no secondaries are available, then this read operation produces an
+ error or exception.
+
+ Most sets have at least one secondary, but there are situations
+ where there may be no available secondary. For example, a set
+ with a primary, a secondary, and an :term:`arbiter` may not have
+ any secondaries if a member is in recovering state or unavailable.
+
+ When the read preference includes a :ref:`tag set
+ <replica-set-read-preference-tag-sets>`, the client attempts to find
+ secondary members that match the specified tag set and directs reads
+ to a random secondary from among the :ref:`nearest group
+ <replica-set-read-preference-behavior-nearest>`. If no secondaries
+ have matching tags, the read operation produces an error. [#capacity-planning]_
+
+ Read operations using the :readmode:`secondary` mode may return stale data.
+
+.. readmode:: secondaryPreferred
+
+ In most situations, operations read from :term:`secondary` members,
+ but in situations where the set consists of a single
+ :term:`primary` (and no other members,) the read operation will use
+ the set's primary.
+
+ When the read preference includes a :ref:`tag set
+ <replica-set-read-preference-tag-sets>`, the client attempts to find
+ a secondary member that matches the specified tag set and directs
+ reads to a random secondary from among the :ref:`nearest group
+ <replica-set-read-preference-behavior-nearest>`. If no secondaries
+ have matching tags, the read operation produces an error.
+
+ Read operations using the :readmode:`secondaryPreferred` mode may return stale data.
+
+.. readmode:: nearest
+
+ The driver reads from the *nearest* member of the :term:`set <replica
+ set>` according to the :ref:`member selection
+ <replica-set-read-preference-behavior-nearest>` process. Reads in
+ the :readmode:`nearest` mode do not consider the member's
+ *type*. Reads in :readmode:`nearest` mode may read from both
+ primaries and secondaries.
+
+ Set this mode to minimize the effect of network latency
+ on read operations without preference for current or stale data.
+
+ If you specify a :ref:`tag set <replica-set-read-preference-tag-sets>`,
+ the client attempts to find a replica set member that matches the
+ specified tag set and directs reads to an arbitrary member from
+ among the :ref:`nearest group <replica-set-read-preference-behavior-nearest>`.
+
+ Read operations using the :readmode:`nearest` mode may return stale data.
+
+ .. note::
+
+ All operations read from a member of the nearest group of the
+ replica set that matches the specified read preference mode. The
+ :readmode:`nearest` mode prefers low latency reads over a
+ member's :term:`primary` or :term:`secondary` status.
+
+ For :readmode:`nearest`, the client assembles a list of
+ acceptable hosts based on tag set and then narrows that list to
+ the host with the shortest ping time and all other members of
+ the set that are within the "local threshold," or acceptable
+ latency. See :ref:`replica-set-read-preference-behavior-nearest`
+ for more information.
+
+ .. For I/O-bound users who want to distribute reads across all
+ members evenly regardless of ping time, set
+ secondaryAcceptableLatencyMS very high.
+
+.. The :method:`readPreference() <cursor.readPreference()>` reference
+ above will error until DOCS-364 is complete.
+
+.. [#capacity-planning] If your set has more than one secondary, and
+ you use the :readmode:`secondary` read preference mode, consider
+ the following effect. If you have a :ref:`three member replica set
+ <replica-set-three-members>` with a primary and two secondaries,
+ and if one secondary becomes unavailable, all :readmode:`secondary`
+ queries must target the remaining secondary. This will double the
+ load on this secondary. Plan and provide capacity to support this
+ as needed.
+
+.. index:: tag sets
+.. index:: read preference; tag sets
+.. _replica-set-read-preference-tag-sets:
+
+Tag Sets
+--------
+
+Tag sets allow you to specify custom :doc:`read preferences
+</core/read-preference>`
+and :ref:`write concerns <write-operations-write-concern>`
+so that your application can target
+operations to specific members, based on custom parameters.
+
+.. note::
+
+ Consider the following properties of read preferences:
+
+ - Custom read preferences and write concerns evaluate tags sets in
+ different ways.
+
+ - Read preferences consider the value of a tag when selecting a
+ member to read from.
+
+ - Write concerns ignore the value of a tag to when selecting a
+ member *except* to consider whether or not the value is unique.
+
+A tag set for a read operation may resemble the following document:
+
+.. code-block:: javascript
+
+ { "disk": "ssd", "use": "reporting" }
+
+To fulfill the request, a member would need to have both of these tags.
+Therefore the following tag sets, would satisfy this
+requirement:
+
+.. code-block:: javascript
+
+ { "disk": "ssd", "use": "reporting" }
+ { "disk": "ssd", "use": "reporting", "rack": 1 }
+ { "disk": "ssd", "use": "reporting", "rack": 4 }
+ { "disk": "ssd", "use": "reporting", "mem": "64"}
+
+However, the following tag sets would *not* be able to fulfill this query:
+
+.. code-block:: javascript
+
+ { "disk": "ssd" }
+ { "use": "reporting" }
+ { "disk": "ssd", "use": "production" }
+ { "disk": "ssd", "use": "production", "rack": 3 }
+ { "disk": "spinning", "use": "reporting", "mem": "32" }
+
+Therefore, tag sets make it possible to ensure that read operations
+target specific members in a particular data center or
+:program:`mongod` instances designated for a particular class of
+operations, such as reporting or analytics.
+For information on configuring tag sets, see
+:ref:`replica-set-configuration-tag-sets` in the
+:doc:`/reference/replica-configuration` document.
+You can specify tag sets with the following read preference modes:
+
+- :readmode:`primaryPreferred`
+- :readmode:`secondary`
+- :readmode:`secondaryPreferred`
+- :readmode:`nearest`
+
+You cannot specify tag sets with the :readmode:`primary` read preference mode.
+
+Tags are not compatible with :readmode:`primary` and only apply when
+:ref:`selecting <replica-set-read-preference-behavior-member-selection>`
+a :term:`secondary` member of a set for a read operation. However, the
+:readmode:`nearest` read mode, when combined with a tag set will
+select the nearest member that matches the specified tag set, which
+may be a primary or secondary.
+
+All interfaces use the same :ref:`member selection logic
+<replica-set-read-preference-behavior-member-selection>` to choose the
+member to which to direct read operations, basing the choice on read
+preference mode and tag sets.
+
+For more information on how read preference :ref:`modes
+<replica-set-read-preference-modes>` interact with tag sets, see the
+documentation for each read preference mode.
+
+.. index:: read preference; behavior
+.. _replica-set-read-preference-behavior:
+
+Behavior
+--------
+
+.. versionchanged:: 2.2
+
+.. _replica-set-read-preference-behavior-retry:
+
+Auto-Retry
+~~~~~~~~~~
+
+Connection between MongoDB drivers and :program:`mongod` instances in
+a :term:`replica set` must balance two concerns:
+
+#. The client should attempt to prefer current results, and any
+ connection should read from the same member of the replica set as
+ much as possible.
+
+#. The client should minimize the amount of time that the database is
+ inaccessible as the result of a connection issue, networking
+ problem, or :term:`failover` in a replica set.
+
+As a result, MongoDB drivers and :program:`mongos`:
+
+- Reuse a connection to specific :program:`mongod` for as long as
+ possible after establishing a connection to that instance. This
+ connection is *pinned* to this :program:`mongod`.
+
+- Attempt to reconnect to a new member, obeying existing :ref:`read
+ preference modes <replica-set-read-preference-modes>`, if the connection
+ to :program:`mongod` is lost.
+
+ Reconnections are transparent to the application itself. If
+ the connection permits reads from :term:`secondary` members, after
+ reconnecting, the application can receive two sequential reads
+ returning from different secondaries. Depending on the state of the
+ individual secondary member's replication, the documents can reflect
+ the state of your database at different moments.
+
+- Return an error *only* after attempting to connect to three members
+ of the set that match the :ref:`read preference mode <replica-set-read-preference-modes>`
+ and :ref:`tag set <replica-set-read-preference-tag-sets>`.
+ If there are fewer than three members of the set, the
+ client will error after connecting to all existing members of the
+ set.
+
+ After this error, the driver selects a new member using the
+ specified read preference mode. In the absence of a specified read
+ preference, the driver uses :readmode:`primary`.
+
+- After detecting a failover situation, [#fn-failover]_ the driver
+ attempts to refresh the state of the replica set as quickly as
+ possible.
+
+.. [#fn-failover] When a :term:`failover` occurs, all members of the set
+ close all client connections that produce a socket error in the
+ driver. This behavior prevents or minimizes :term:`rollback`.
+
+.. _replica-set-read-preference-behavior-requests:
+
+Request Association
+~~~~~~~~~~~~~~~~~~~
+
+Reads from :term:`secondary` may reflect the state of the data set at
+different points in time because :term:`secondary` members of a
+:term:`replica set` may lag behind the current state of the primary by
+different amounts. To prevent subsequent reads from jumping around in
+time, the driver can associate application threads to a specific member
+of the set after the first read. The thread will continue to read from
+the same member until:
+
+- The application performs a read with a different read preference.
+
+- The thread terminates.
+
+- The client receives a socket exception, as is
+ the case when there's a network error or when
+ the :program:`mongod` closes connections during a :term:`failover`.
+ This triggers a :ref:`retry
+ <replica-set-read-preference-behavior-retry>`, which may be
+ transparent to the application.
+
+If an application thread issues a query with the
+:readmode:`primaryPreferred` mode while the primary is inaccessible,
+the thread will carry the association with that secondary for the
+lifetime of the thread. The thread will associate with the primary, if
+available, only after issuing a query with a different read
+preference, even if a primary becomes available. By extension, if a
+thread issues a read with the :readmode:`secondaryPreferred` when all
+secondaries are down, it will carry an association with the
+primary. This application thread will continue to read from the
+primary even if a secondary becomes available later in the thread's
+lifetime.
+
+.. index:: read preference; ping time
+.. index:: read preference; nearest
+.. index:: read preference; member selection
+.. _replica-set-read-preference-behavior-ping-time:
+.. _replica-set-read-preference-behavior-nearest:
+.. _replica-set-read-preference-behavior-member-selection:
+
+Member Selection
+~~~~~~~~~~~~~~~~
+
+Clients, by way of their drivers, and :program:`mongos` instances for
+sharded clusters periodically update their view of the replica set's state:
+which members are up or down, which member is primary, and the latency to each
+:program:`mongod` instance.
+
+For any operation that targets a member *other* than the
+:term:`primary`, the driver:
+
+#. Assembles a list of suitable members, taking into account member type
+ (i.e. secondary, primary, or all members.)
+
+#. Excludes members not matching the tag sets, if specified.
+
+#. Determines which suitable member is the closest to the
+ client in absolute terms.
+
+#. Builds a list of members that are within a defined ping distance (in
+ milliseconds) of the "absolute nearest" member. [#acceptable-secondary-latency]_
+
+#. Selects a member from these hosts at random. The member receives the read operation.
+
+Once the application selects a member of the set to use for read
+operations, the driver continues to use this connection for read
+preference until the application specifies a new read preference or
+something interrupts the connection. See :ref:`replica-set-read-preference-behavior-requests`
+for more information.
+
+.. [#acceptable-secondary-latency] Applications can configure the
+ threshold used in this stage. The default "acceptable latency" is
+ 15 milliseconds, which you can override in the drivers with their own
+ ``secondaryAcceptableLatencyMS`` option.
+ For :program:`mongos` you can use the :option:`--localThreshold <mongos --localThreshold>` or
+ :setting:`localThreshold` runtime options to set this value.
+
+.. index:: read preference; sharding
+.. index:: read preference; mongos
+.. _replica-set-read-preference-behavior-sharding:
+.. _replica-set-read-preference-behavior-mongos:
+
+Sharding and ``mongos``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionchanged:: 2.2
+ Before version 2.2, :program:`mongos` did not support the
+ :ref:`read preference mode semantics <replica-set-read-preference-modes>`.
+
+In most :term:`sharded clusters <sharded cluster>`, a :term:`replica set`
+provides each shard where read preferences are also applicable. Read
+operations in a sharded cluster, with regard to read preference, are
+identical to unsharded replica sets.
+
+Unlike simple replica sets, in sharded clusters, all interactions with
+the shards pass from the clients to the :program:`mongos` instances
+that are actually connected to the set members. :program:`mongos` is
+responsible for the application of the read preferences, which is
+transparent to applications.
+
+There are no configuration changes required for full support of read
+preference modes in sharded environments, as long as the
+:program:`mongos` is at least version 2.2. All :program:`mongos`
+maintain their own connection pool to the replica set members. As a
+result:
+
+- A request without a specified preference has
+ :readmode:`primary`, the default, unless, the :program:`mongos`
+ reuses an existing connection that has a different mode set.
+
+ Always explicitly set your read preference mode to prevent
+ confusion.
+
+- All :readmode:`nearest` and latency calculations reflect the
+ connection between the :program:`mongos` and the :program:`mongod`
+ instances, not the client and the :program:`mongod` instances.
+
+ This produces the desired result, because all results must pass
+ through the :program:`mongos` before returning to the client.
+
+Database Commands
+~~~~~~~~~~~~~~~~~
+
+Because some :term:`database commands <database command>` read and
+return data from the database, all of the official drivers support
+full :ref:`read preference mode semantics <replica-set-read-preference-modes>`
+for the following commands:
+
+- :dbcommand:`group`
+- :dbcommand:`mapReduce` [#inline-map-reduce]_
+- :dbcommand:`aggregate`
+- :dbcommand:`collStats`
+- :dbcommand:`dbStats`
+- :dbcommand:`count`
+- :dbcommand:`distinct`
+- :dbcommand:`geoNear`
+- :dbcommand:`geoSearch`
+- :dbcommand:`geoWalk`
+
+.. [#inline-map-reduce] Only "inline" :dbcommand:`mapReduce`
+ operations that do not write data support read preference,
+ otherwise these operations must run on the :term:`primary`
+ members.
+
+:program:`mongos` currently does not route commands using read
+preferences; clients send all commands to shards' primaries. See
+:issue:`SERVER-7423`.
+
+Uses for non-Primary Read Preferences
+-------------------------------------
+
+You must exercise care when specifying read preferences: modes other
+than :readmode:`primary` can *and will* return stale data. These
+secondary queries will not
+include the most recent write operations to the replica set's
+:term:`primary`. Nevertheless, there are several common use cases for
+using non-:readmode:`primary` read preference modes:
+
+- Reporting and analytics workloads.
+
+ Having these queries target a :term:`secondary` helps distribute
+ load and prevent these operations from affecting the main workload
+ of the primary.
+
+ Also consider using :readmode:`secondary` in conjunction with a
+ direct connection to a :ref:`hidden member <replica-set-hidden-members>` of the set.
+