DOCS-960 optimizer logic for ordered and unordered plans

Author: kay-kim

source/core/read-operations.txt

@@ -570,23 +570,39 @@ the collection changes to ensure optimal query plans.
 
 To create a new query plan, the query optimizer:
 
-1. runs the query against several indexes in parallel.
+1. runs the query against several candidate indexes in parallel.
 
-#. records the matches in a single common buffer, as though the
-   results all came from the same index.
+#. The query optimizer records the matches in a common results buffer
+   or buffers:
+
+   - If the candidate plans include only :term:`ordered query plans
+     <ordered query plan>`, there is a single common results buffer.
+     
+   - If the candidate plans include only :term:`unordered query plans
+     <unordered query plan>`, there is a single common results buffer.
+
+   - If the candidate plans include *both* :term:`ordered query plans
+     <ordered query plan>` and the :term:`unordered query plans
+     <unordered query plan>`, there are two common results buffers, one
+     for the ordered plans and the other for the unordered plans.
 
    If an index returns a result already returned by another index, the
-   optimizer skips the duplicate match.
+   optimizer skips the duplicate match. In the case of the two buffers,
+   both buffers are de-duped.
+
+#. stops the testing of candidate plans and selects an index when one of
+   the following events occur:
+
+   - An :term:`unordered query plan` has returned all the matching results; *or*
+
+   - An :term:`ordered query plan` has returned all the matching results; *or*
 
-#. selects an index when either of the following occur:
+   - An :term:`ordered query plan` has returned a threshold number of matching results:
 
-   - The optimizer exhausts an index, which means that the index has
-     provided the full result set. At this point, the optimizer stops
-     querying.
+     - Version 2.0: Threshold is the query batch size. The default
+       batch size is 101.
 
-   - The optimizer reaches 101 results. At this point, the optimizer
-     chooses the index that has provided the most results *first* and
-     continues reading only from that index.
+     - Version 2.2: Threshold is 101.
 
 The selected index becomes the index specified in the query plan;
 future iterations of this query or queries with the same query
@@ -618,7 +634,7 @@ use of the different indexes:
 
 This returns the statistics regarding the execution of the query. For
 more information on the output of :method:`explain()
-<cursor.explain()>` see the :doc:`/reference/explain`.
+<cursor.explain()>`, see the :doc:`/reference/explain`.
 
 .. note::
 
@@ -791,9 +807,9 @@ Consider the following behaviors related to cursors:
 
 - Because the cursor is not isolated during its lifetime, intervening
   write operations may result in a cursor that returns a single
-  document [#single-document-def]_ more than once.
-  To handle this situation, see the information on :wiki:`snapshot mode
-  <How to do Snapshotted Queries in the Mongo Database>`.
+  document [#single-document-def]_ more than once. To handle this
+  situation, see the information on :ref:`snapshot mode
+  <faq-developers-isolate-cursors>`.
 
 - The MongoDB server returns the query results in batches:
 
@@ -906,7 +922,8 @@ operations for more basic data aggregation operations:
 
 - :method:`group()`
 
-- :dbcommand:`mapReduce() <mapReduce>` (See also :wiki:`MapReduce`.)
+- :dbcommand:`mapReduce() <mapReduce>` (See also
+  :doc:`/applications/map-reduce`.)
 
 .. index:: read operation; architecture
 .. _read-operations-architecture:

source/reference/glossary.txt

@@ -178,8 +178,8 @@ Glossary
    circle
       MongoDB's :term:`geospatial` indexes and querying system
       allow you to build queries around circles on two-dimensional
-      coordinate systems. These queries use the
-      :operator:`$circle` operator to define circle using the center
+      coordinate systems. These queries use the :operator:`$within` operator
+      and the :operator:`$center` operator to define a circle using the center
       and the radius of the circle.
 
    box
@@ -196,9 +196,7 @@ Glossary
       capped collections.  Developers may also use capped collections in their
       applications.
 
-      .. seealso:: The :wiki:`Capped Collections <Capped+Collections>` wiki page.
-
-      .. STUB :doc:`/core/capped-collections`.
+      .. seealso:: The :doc:`/core/capped-collections` page.
 
    BSON types
       The set of types supported by the :term:`BSON` serialization
@@ -315,9 +313,7 @@ Glossary
 
       .. include:: /includes/fact-journal-commit-interval-with-gle.rst
 
-      .. seealso:: The :wiki:`Journaling` wiki page.
-
-      .. STUB :doc:`/core/journaling`.
+      .. seealso:: The :doc:`/administration/journaling/` page.
 
    pcap
       A packet capture format used by :program:`mongosniff` to record
@@ -729,13 +725,11 @@ Glossary
       transforms the data. In MongoDB, you can run arbitrary aggregations
       over data using map-reduce.
 
-      .. seealso:: The :wiki:`Map Reduce <MapReduce>` wiki page for
+      .. seealso:: The :doc:`/applications/map-reduce` page for
          more information regarding MongoDB's map-reduce
          implementation, and :doc:`/applications/aggregation` for
          another approach to data aggregation in MongoDB.
 
-      .. STUB :doc:`/core/map-reduce`
-
    RDBMS
       Relational Database Management System. A database management
       system based on the relational model, typically using
@@ -911,3 +905,15 @@ Glossary
 
    dot notation
       .. include:: /includes/fact-dot-notation.rst
+
+   ordered query plan
+      Query plan that returns results in the order consistent with the
+      :method:`~cursor.sort()` order.
+
+      .. seealso:: :ref:`read-operations-query-optimization`
+
+   unordered query plan
+      Query plan that returns results in an order inconsistent with the
+      :method:`~cursor.sort()` order.
+
+      .. seealso:: :ref:`read-operations-query-optimization`