DOCS-254 incorporate comments from aaron and ed

Author: kay-kim

source/applications/indexes.txt

@@ -29,7 +29,7 @@ understanding of:
 
 The best overall strategy for designing indexes is to profile a variety
 of index configurations with data sets similar to the ones you'll be
-running in production and to see which configurations perform best.
+running in production to see which configurations perform best.
 
 MongoDB can only use *one* index to support any given
 operation. However, each clause of an :operator:`$or` query can use
@@ -41,14 +41,14 @@ Create Indexes to Support Your Queries
 --------------------------------------
 
 If you only ever query on a single key in a given collection, then you need
-create just one single-key index for that collection. For example, you
+to create just one single-key index for that collection. For example, you
 might create an index on ``category`` in the ``product`` collection:
 
 .. code-block:: javascript
 
    db.products.ensureIndex( { "category": 1 } )
 
-However, if you sometimes query on only one key but and at other times
+However, if you sometimes query on only one key and at other times
 query on that key combined with a second key, then creating a
 :ref:`compound index <index-type-compound>` is more efficient. MongoDB
 will use the compound index for both queries. For example, you might
@@ -122,9 +122,9 @@ part of an index. They are "covered queries" because an index "covers" the query
 MongoDB can fulfill the query by using *only* the index. MongoDB need
 not scan documents from the database.
 
-Querying *only* the index is much faster than querying documents.
-Indexes keys are typically smaller than the documents they catalog, and indexes are
-typically stored in RAM or located sequentially on disk.
+Querying *only* the index is much faster than querying documents. Index
+keys are typically smaller than the documents they catalog, and indexes
+are typically stored in RAM or located sequentially on disk.
 
 Mongod automatically uses a covered query when possible. To ensure use
 of a covered query, create an index that includes all the fields listed
@@ -135,7 +135,7 @@ explicitly exclude the ``_id`` field from the result set, unless the
 index includes ``_id``.
 
 MongoDB cannot use a covered query if any of the indexed fields in any
-of the documents in the collection include an array. If an indexed field
+of the documents in the collection includes an array. If an indexed field
 is an array, the index becomes a :ref:`multi-key index
 <index-type-multikey>` index and cannot support a covered query.
 
@@ -197,10 +197,10 @@ are equality matches.
 
 .. note::
 
-   When the :method:`sort() <cursor.sort()>` method performs an
-   in-memory sort operation without the use of an index, the operation
-   is significantly slower than for operations that use an index, and
-   the operation aborts when it consumes 32 megabytes of memory.
+   For in-memory sorts that do not use an index, the :method:`sort()
+   <cursor.sort()>` operation is significantly slower. The
+   :method:`~cursor.sort()` operation will abort when it uses 32
+   megabytes of memory.
 
 .. _indexes-ensure-indexes-fit-ram:
 
@@ -226,7 +226,7 @@ available but also must have RAM available for the rest of the
 
 If you have and use multiple collections, you must consider the size
 of all indexes on all collections. The indexes and the working set must be able to
-fit RAM at the same time.
+fit in RAM at the same time.
 
 There are some limited cases where indexes do not need
 to fit in RAM. See :ref:`indexing-right-handed`.
@@ -337,8 +337,8 @@ Consider Performance when Creating Indexes for Write-heavy Applications
 If your application is write-heavy, then be careful when creating new
 indexes, since each additional index with impose a
 write-performance penalty. In general, don't be careless about adding
-indexes. Add indexes complement your queries. Always have
-a good reason for adding a new index, and make sure you've benchmarked
+indexes. Add indexes to complement your queries. Always have
+a good reason for adding a new index, and be sure to benchmark
 alternative strategies.
 
 Consider Insert Throughput
@@ -347,17 +347,16 @@ Consider Insert Throughput
 .. todo:: insert link to /source/core/write-operations when that page is complete.
    Do we want to link to write concern? -bg
 
-MongoDB must update *all* indexes associated with a collection after every
-insert, update, or delete operation. For update operations, if the updated document
-does not move to a new location, then only the modified, MongoDB only needs
-to update  the updated fields in the index.
-Therefore, every index on a
-collection adds some amount of overhead to these write operations. In almost
-every case, the performance gains that indexes realize for read
+MongoDB must update *all* indexes associated with a collection after
+every insert, update, or delete operation. For update operations, if
+the updated document does not move to a new location, then MongoDB only
+modifies the updated fields in the index. Therefore, every index on a
+collection adds some amount of overhead to these write operations. In
+almost every case, the performance gains that indexes realize for read
 operations are worth the insertion penalty. However, in some cases:
 
 - An index to support an infrequent query might incur more
-  insert-related costs than saved read-time.
+  insert-related costs than savings in read-time.
 
   .. todo:: How do you determine if the above is the case? 
      Empirically.
@@ -371,5 +370,5 @@ operations are worth the insertion penalty. However, in some cases:
 
 - If your indexes and queries are not sufficiently :ref:`selective
   <index-selectivity>`, the speed improvements for query operations
-  might not offset the costs of maintaining an index. For more
+  may not offset the costs of maintaining an index. For more
   information see :ref:`index-selectivity`.

source/reference/explain-output.txt

@@ -5,7 +5,7 @@ Explain Output
 .. default-domain:: mongodb
 
 This document explains the output of the :operator:`$explain` operator
-and the :program:`mongo` shell wrapper :method:`explain()
+and the :program:`mongo` shell method :method:`explain()
 <cursor.explain()>`.
 
 Core Explain Output
@@ -47,6 +47,36 @@ this information is displayed for each accessed shard.
      "server" : "<host:port>",
    }
 
+$OR Queries
+-----------
+
+Queries with :operator:`$or` operator execute each clause of the
+:operator:`$or` expression in parallel and can use separate indexes on
+the individual clauses. If the indexes on the clauses are used, the
+explain output contains the :ref:`explain-output-fields-core` for each
+clause as well as the cumulative information for the query:
+
+.. code-block:: javascript
+
+   {
+      "clauses" : [
+                     {
+                        <core explain output>
+                     },
+                     {
+                        <core explain output>
+                     },
+                     ...
+                  ],
+      "n" : <num>,
+      "nscannedObjects" : <num>,
+      "nscanned" : <num>,
+      "nscannedObjectsAllPlans" : <num>,
+      "nscannedAllPlans" : <num>,
+      "millis" : <num>,
+      "server" : "<host:port>"
+   } 
+
 Sharded Collections
 -------------------
 
@@ -100,13 +130,15 @@ Core Explain Output
 
    Specifies the type of cursor used in the query operation:
 
-   - ``BasicCursor`` indicates use of full table scan.
+   - ``BasicCursor`` indicates use of full collection scan.
 
-   - ``BtreeCursor`` indicates use of an index. The cursor information
-     includes the index name. With the use of an index, the
+   - ``BtreeCursor`` indicates use of an B-tree index. The cursor
+     information includes the index name. With the use of an index, the
      :method:`explain() <cursor.explain()>` output will include the
      :data:`indexBounds` details.
 
+   - ``GeoSearchCursor`` indicates use of a geospatial index. 
+
 .. data:: isMultiKey
 
    Specifies whether a :ref:`multikey index on an array field
@@ -119,17 +151,18 @@ Core Explain Output
 
 .. data:: nscannedObjects
 
-   Specifies the total number of documents scanned during the query. If
-   the index is a covered index, the :data:`nscannedObjects` may be
-   lower than :data:`nscanned`.
+   Specifies the total number of documents scanned during the query.
+   The :data:`nscannedObjects` may be lower than :data:`nscanned`, such
+   as if the index is a covered index.
 
 .. data:: nscanned
 
    Specifies the total number of documents or index entries scanned
    during the database operation. You want :data:`n` and
-   :data:`nscanned` to be close in value as possible. If the index is a
-   covered index, :data:`nscanned` may be higher than
-   :data:`nscannedObjects`.
+   :data:`nscanned` to be close in value as possible. The
+   :data:`nscanned` value may be higher than the
+   :data:`nscannedObjects` value, such as if the index is a covered
+   index.
 
 .. data:: nscannedObjectsAllPlans
 
@@ -149,8 +182,12 @@ Core Explain Output
 
    .. versionadded:: 2.2
 
-   Specifies whether the index could not be used for sorting. If
-   ``true``, the index could *not* be used for sorting.
+   Specifies whether the index could not be used for sorting. 
+
+   If ``true``, the index could *not* be used for sorting. Instead, the
+   documents are sorted after being retrieved either from the index if
+   an index is used to return the documents, or from the full
+   collection if a collection scan is performed.
 
 .. data:: indexOnly
 
@@ -211,6 +248,18 @@ Core Explain Output
 
    Specifies the MongoDB server.
 
+.. _explain-output-field-or-clauses:
+
+$OR Query Output
+~~~~~~~~~~~~~~~~
+
+.. data:: clauses
+
+   Contains the :ref:`explain-output-fields-core` information for each
+   clause of the :operator:`$or` expression. Displays only if indexes
+   are used for the clauses in the :operator:`$or` expression.
+
+
 .. _explain-output-fields-sharded-collection:
 
 Sharded Collections Output

source/reference/method/cursor.explain.txt

@@ -4,10 +4,15 @@ cursor.explain()
 
 .. default-domain:: mongodb
 
+.. EDITS to cursor.explain.txt must be carried over to the operator
+   explain.txt and vice versa
+
 .. method:: cursor.explain()
 
    The :method:`cursor.explain()` method provides information on the
-   query plan. 
+   query plan. The query plan is the plan the server uses to find the
+   matches for a query. This information may be useful when optimizing
+   a query.
 
    :param boolean verbose:
 
@@ -17,7 +22,7 @@ cursor.explain()
           </reference/explain-output>`.
 
    :returns: A :doc:`document </reference/explain-output>` that
-             describes the process used to return the query.
+             describes the process used to return the query results.
 
    Retrieve the query plan by appending :method:`explain()
    <cursor.explain()>` to a :method:`find()` query, as in the following
@@ -27,14 +32,21 @@ cursor.explain()
 
       db.products.find().explain() 
 
+   For details on the output, see :doc:`/reference/explain-output`.
+
    :method:`explain <cursor.explain()>` runs the actual query to
-   determine the result. If the query is slow, the :method:`explain
-   <cursor.explain()>` will also be slow. Additionally, when you call
-   the :method:`explain <cursor.explain()>` on a query, the query
-   system reevaluates the query plan, which may cause some queries to
-   run slower. As a result, these operations provide an accurate
-   account of *how* MongoDB would perform the query, but not
-   necessarily *how long* the query would take.
+   determine the result. Although there are some differences between
+   running the query with :method:`explain <cursor.explain()>` and
+   running without, generally, the performance will be similar between
+   the two. So, if the query is slow, the :method:`explain
+   <cursor.explain()>` will also be slow.
+   
+   Additionally, when you call the :method:`explain <cursor.explain()>`
+   method on a query, the query system reevaluates a set of candidate
+   query plans, which may cause some queries to run slower. As a
+   result, these operations generally provide an accurate account of
+   *how* MongoDB would perform the query [#explain-cache-plan]_, but
+   not necessarily *how long* the query would take.
 
    To determine the performance of a particular index, you can use
    :method:`hint() <cursor.hint()>`  and in conjunction with
@@ -46,9 +58,19 @@ cursor.explain()
 
    When you run :method:`explain <cursor.explain()>` with
    :method:`hint() <cursor.hint()>`, the query optimizer does not
-   reevaluate the query plan.
-
-   For details on the output, see :doc:`/reference/explain-output`.
+   reevaluate the query plans.
+
+   .. [#explain-cache-plan] In some situations, the :method:`explain 
+      <cursor.explain()>` operation may differ from the actual query
+      plan used to perform the query. The :method:`explain
+      <cursor.explain()>` operation evaluates the set of query plans
+      and reports on the winning plan for the query. This plan is
+      cached to be used for the execution of the query and similar
+      queries at a later time. When you run similar queries, this
+      cached plan is selected even though the cached plan may not be
+      the best plan for similar queries. So, if you run
+      :method:`explain <cursor.explain()>` operation on similar
+      queries, the winning plan may be different.
 
    .. seealso::