From e22b4dc4ecb62fcb56736f6cf614951a08661e2a Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 2 Oct 2012 12:22:22 -0400 Subject: [PATCH] DOCS-233: edits --- draft/core/read-operations.txt | 120 +++++++++++++++++++++++---------- 1 file changed, 86 insertions(+), 34 deletions(-) diff --git a/draft/core/read-operations.txt b/draft/core/read-operations.txt index 4ce44d2d0a0..831f37d0009 100644 --- a/draft/core/read-operations.txt +++ b/draft/core/read-operations.txt @@ -4,12 +4,9 @@ Read Operations .. default-domain:: mongodb -Read operations determine how MongoDB returns collection data when you issue a query. - -This document describes how MongoDB performs read operations and how -different factors affect the efficiency of reads. - -.. TODO for information about queries, see ???. +Read operations determine how MongoDB returns collection data when you +issue a query. This document describes how MongoDB performs read +operations and how different factors affect the efficiency of reads. .. index:: read operation; query .. index:: query; read operations @@ -18,9 +15,7 @@ different factors affect the efficiency of reads. Query Operations ---------------- -Queries retrieve data from your database collections. How a query -retrieves data is dependent on MongoDB read operations and on the -indexes you have created. +Queries are the primary read operations in MongoDB. .. _read-operations-query-syntax: @@ -29,7 +24,7 @@ Query Syntax For a list of query operators, see :doc:`/reference/operators`. -.. TODO see the yet-to-be created query operations doc +.. TODO link to the yet-to-be created query operations doc .. _read-operations-indexing: @@ -78,8 +73,8 @@ documents that match the query criteria also match the entire query. - The :doc:`/indexes` documentation, in particular :doc:`/applications/indexes` - :doc:`/reference/operators` - - :method:`find ` - - :method:`findOne` + - :method:`find() ` + - :method:`findOne() ` .. index:: query optimizer .. _read-operations-query-optimization: @@ -138,8 +133,8 @@ For details on the output, see :method:`explain() `. .. note:: If you run :method:`explain() ` without including - :method:`hint() `, the query optimizer re-evaluates - the query and run against multiple indexes before returning the query + :method:`hint() ` the query optimizer re-evaluates + the query and runs against multiple indexes before returning the query statistics. Because your collections will likely change over time, the query @@ -148,17 +143,15 @@ of the following occur: - The number of writes to the collection reaches 1,000. -- You run the :dbcommand:`reIndex` command on the index. +- You run the :dbcommand:`reIndex() ` command on the index. - You restart :program:`mongod`. -When you re-evaluate a query, the optimizer displays the same results -(assuming no data has changed) but might display the results in a -different order. Similarly, the :method:`explain() ` -method and :method:`hint() ` methods might display -different statistics. This is because the optimizer retrieves the -results from several indexes at once during re-evaluation, and the order -in which results appear depends on the order of the indexes within the +When you re-evaluate a query, the optimizer displays the same results if +no data has changed, but the the results might appear in a different +order. This is because the optimizer retrieves the results from several +indexes at once during re-evaluation, and the order in which results +appear depends on the order in which indexes are arranged in the parallel query operation. .. _read-operations-projection: @@ -171,7 +164,11 @@ documents. If you run a query *without* a projection, the query returns all fields and values for matching documents. By narrowing the fields to display, projections can minimize network and deserialization costs. -You specify a projection in the second document in a query. +You specify a projection in the second document in a query: + +.. code-block:: javascript + + db.foo.find( { } , { } ) .. example:: @@ -184,17 +181,33 @@ You specify a projection in the second document in a query. { "_id" : 102 , x : 2 , y : 17 , z : 22 } { "_id" : 103 , x : 3 , y : 18 , z : 23 } - You can search for all documents where ``x`` is ``2`` but, instead of - returning all fields, you could choose to return only the ``z`` field - (and the ``_id`` field, which is always returned by default). You - would issue this query: + To search for all documents where ``x`` is ``2`` but return only the + ``z`` field, issue this query: .. code-block:: javascript db.foo.find( { x : 2 } , { z : 1 } ) - By specifying ``{ z : 1 }``, you tell MongoDB to return the ``z`` - field. + The query returns this result set: + + .. code-block:: javascript + + { "_id" : 101, "z" : 21 } + { "_id" : 102, "z" : 22 } + + By default, the results include the ``_id`` field. To return ``z`` + *without* returning ``_id``, include ``_id : 0`` in the projection: + + .. code-block:: javascript + + db.foo.find( { x : 2 } , { z : 1 , _id : 0 } ) + + The query returns this result set: + + .. code-block:: javascript + + { "z" : 21 } + { "z" : 22 } MongoDB also provides the following projection operators specific to arrays. For documentation on each operator, click the operator name: @@ -208,13 +221,30 @@ arrays. For documentation on each operator, click the operator name: Aggregation ~~~~~~~~~~~ -.. Probably short, but there's no docs for old-style aggregation so. +When you run a query using aggregation, MongoDB performs summary, +grouping, or other operations on data before returning results. When you +run a query without aggregation, you retrieve data as it's stored in the +database; when you run with aggregation, you retrieve reframed data. + +Beginning with MongoDB version 2.1, the primary way to perform +aggregation is through the aggregation framework, which processes data +through pipelines and returns data as a document stream specific to the +aggregation process. + +For more information on the aggregation framework, including +descriptions of operators, see see :doc:`/applications/aggregation`. + +In addition to the operators used by the aggregation framework, you can +use the following aggregation operators. For documentation on each +operator, click the operator name: + +- :method:`count() ` -.. - basic aggregation (count, distinct) -.. - legacy agg: group -.. - big things: mapreduce, aggregation +- :dbcommand:`distinct() ` -.. seealso:: :doc:`/applications/aggregation` +- :method:`group()` + +- :dbcommand:`mapReduce() ` (See also :wiki:`MapReduce`.) .. index:: read operation; architecture .. _read-operations-architecture: @@ -246,9 +276,31 @@ Architecture Connection Pooling ~~~~~~~~~~~~~~~~~~ +.. TODO + Shard Clusters ~~~~~~~~~~~~~~ +.. TODO + Replica Sets ~~~~~~~~~~~~ +:term:`Replica sets ` use :term:`read preferences ` to determine where and how to route read operations. By +default, MongoDB always reads data from a repilca set's :term:`primary`. +You can modify that behavior by changing the :ref:`read preference mode +`. + +For example, you can set the :ref:`read preference mode +` to allow reads from +:term:`secondaries ` when backing up data, or to block reads +entirely during a :ref:`failover `. + +If your database traffic is comprised mostly of read operations, then +using read preferences to distribute reads can improve read throughput. +The trade-off is that some reads might return stale data, as +secondaries always have some amount of lag. + +For more information on choosing read preference modes, see +:ref:`replica-set-read-preference-modes`.