DOCS-11790 equality sort range v5.3 (#908) (#948)

Author: Dave

source/applications/indexes.txt

@@ -37,31 +37,34 @@ index, and in addition, MongoDB can use an :doc:`intersection
 
 The following documents introduce indexing strategies:
 
-.. class:: toc
+:ref:`Use the ESR (Equality, Sort, Range) Rule <esr-indexing-rule>`
+   The ESR (Equality, Sort, Range) Rule is a guide to creating indexes
+   that support your queries efficiently.
 
-   :doc:`/tutorial/create-indexes-to-support-queries`
-      An index supports a query when the index contains all the fields
-      scanned by the query. Creating indexes that supports queries
-      results in greatly increased query performance.
+:ref:`create-indexes-to-support-queries`
+   An index supports a query when the index contains all the fields
+   scanned by the query. Creating indexes that support queries
+   results in greatly increased query performance.
 
-   :doc:`/tutorial/sort-results-with-indexes`
-      To support efficient queries, use the strategies here when you
-      specify the sequential order and sort order of index fields.
+:ref:`sorting-with-indexes`
+   To support efficient queries, use the strategies here when you
+   specify the sequential order and sort order of index fields.
 
-   :doc:`/tutorial/ensure-indexes-fit-ram`
-      When your index fits in RAM, the system can avoid reading the
-      index from disk and you get the fastest processing.
+:ref:`indexes-ensure-indexes-fit-ram`
+   When your index fits in RAM, the system can avoid reading the
+   index from disk and you get the fastest processing.
 
-   :doc:`/tutorial/create-queries-that-ensure-selectivity`
-      Selectivity is the ability of a query to narrow results using the
-      index. Selectivity allows MongoDB to use the index for a larger
-      portion of the work associated with fulfilling the query.
+:ref:`index-selectivity`
+   Selectivity is the ability of a query to narrow results using the
+   index. Selectivity allows MongoDB to use the index for a larger
+   portion of the work associated with fulfilling the query.
 
 
 .. toctree::
    :titlesonly: 
    :hidden: 
 
+   /tutorial/equality-sort-range-rule
    /tutorial/create-indexes-to-support-queries
    /tutorial/sort-results-with-indexes
    /tutorial/ensure-indexes-fit-ram

source/core/index-compound.txt

@@ -39,10 +39,14 @@ operation that resembles the following prototype:
 
 .. include:: /includes/fact-index-specification-field-value.rst
 
-.. important:: You may not create compound indexes that have
-   ``hashed`` index type. You will receive an error if you attempt to
-   create a compound index that includes :doc:`a hashed index
-   field </core/index-hashed>`.
+.. important:: 
+
+   In MongoDB 4.2 or earlier: 
+   
+   - Compound indexes may **not** contain a :doc:`hashed index field 
+     </core/index-hashed>`. 
+   - You will receive an error if you attempt to create a compound index
+     that contains a :doc:`hashed index field </core/index-hashed>`.
 
 Consider a collection named ``products`` that holds documents that
 resemble the following document:
@@ -86,6 +90,11 @@ For details, see :ref:`compound-index-prefix`.
 .. index:: index; sort order
 .. _index-ascending-and-descending:
 
+The order of the indexed fields has a strong impact on the
+effectiveness of a particular index for a given query. For most
+compound indexes, following the :ref:`ESR (Equality, Sort, Range) rule
+<esr-indexing-rule>` helps to create efficient indexes.
+
 Sort Order
 ----------
 

source/indexes.txt

@@ -141,8 +141,11 @@ index can support a sort operation. See
 :ref:`index-ascending-and-descending` for more information on the
 impact of index order on results in compound indexes.
 
-See :doc:`/core/index-compound` and :ref:`sort-on-multiple-fields` for
-more information on compound indexes.
+See also:
+
+- :ref:`index-type-compound`,
+- :ref:`sort-on-multiple-fields`, and
+- :ref:`esr-indexing-rule` 
 
 Multikey Index
 ~~~~~~~~~~~~~~

source/reference/method/cursor.hint.txt

@@ -1,3 +1,5 @@
+.. _cursor-hint:
+
 =============
 cursor.hint()
 =============

source/tutorial/equality-sort-range-rule.txt

@@ -0,0 +1,172 @@
+.. _esr-indexing-rule:
+
+====================================
+The ESR (Equality, Sort, Range) Rule
+====================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+An index that references multiple fields is a :ref:`compound index
+<index-type-compound>`. Compound indexes can dramatically improve query
+response times.
+
+Index keys correspond to document fields. In most cases, applying the
+ESR (Equality, Sort, Range) Rule to arrange the index keys helps to
+create a more efficient :ref:`compound index <index-type-compound>`.
+
+This page introduces the ESR Rule. For more information on tuning
+queries, see :dbcommand:`explain` and 
+:ref:`query-plans-query-optimization`. 
+
+.. tip::
+
+   To force MongoDB to use a particular index, use :ref:`cursor-hint`
+   when testing indexes.
+
+.. _esr-rule-equality:
+
+Equality
+--------
+
+"Equality" refers to an exact match on a single value. The following
+exact match queries scan the ``cars`` collection for documents whose
+``model`` field exactly matches ``Cordoba``.
+
+.. code-block:: javascript
+
+   db.cars.find( { model: "Cordoba" } )
+   db.cars.find( { model: { $eq: "Cordoba" } } )
+
+Index searches make efficient use of exact matches to limit the number
+of documents that need to be examined to satisfy a query. Place fields
+that require exact matches first in your index.
+
+An index may have multiple keys for queries with exact matches. The
+index keys for equality matches can appear in any order. However, to
+satisfy an equality match with the index, all of the index keys for
+exact matches must come before any other index fields. MongoDB's search
+algorithm eliminates any need to arrange the exact match fields in a
+particular order.
+
+Exact matches should be selective. To reduce the number of index keys
+scanned, ensure equality tests eliminate at least 90% of possible
+document matches.
+
+.. _esr-rule-sort:
+
+Sort
+----
+
+"Sort" determines the order for results. Sort follows equality matches
+because the equality matches reduce the number of documents that need
+to be sorted. Sorting after the equality matches also allows MongoDB to
+do a non-blocking sort.
+
+An index can support sort operations when the query fields are a subset
+of the index keys. Sort operations on a subset of the index keys are
+only supported if the query includes equality conditions for all of the
+prefix keys that precede the sort keys. For more information see:
+:ref:`Sort and Non-prefix Subset of an Index
+<sort-index-nonprefix-subset>`.
+
+The following example queries the ``cars`` collection. The output is
+sorted by ``model``:
+
+.. code-block:: javascript
+
+   db.cars.find( { manufacturer: "GM" } ).sort( { model: 1 } )
+
+To improve query performance, create an index on the ``manufacturer``
+and ``model`` fields:
+
+.. code-block:: javascript
+
+   db.cars.createIndex( { manufacturer: 1, model: 1 } )
+
+- ``manufacturer`` is the first key because it is an equality match.
+- ``model`` is indexed in the same order ( ``1`` ) as the query. 
+
+.. _esr-rule-range:
+
+Range
+-----
+
+"Range" filters scan fields. The scan doesn't require an exact match,
+which means range filters are loosely bound to index keys. To improve
+query efficiency, make the range bounds as tight as possible and use
+equality matches to limit the number of documents that must be scanned.
+
+Range filters resemble the following:
+
+.. code-block:: javascript
+
+   db.cars.find( { price: { $gte: 15000} } )
+   db.cars.find( { age: { $lt: 10 } } )
+   db.cars.find( { priorAccidents: { $ne: null } } )
+
+MongoDB cannot do an index sort on the results of a range filter.
+Place the range filter after the sort predicate so MongoDB can use a
+non-blocking index sort. For more information on blocking sorts, see
+:method:`cursor.allowDiskUse()`.
+
+Additional Considerations
+-------------------------
+
+Inequality operators such as :query:`$ne` or :query:`$nin` are range
+operators, not equality operators.
+
+:query:`$regex` is a range operator.
+
+:query:`$in` can be an equality operator or a range operator.
+When :query:`$in` is used alone, it is an equality operator that
+does a series of equality matches. :query:`$in` acts like a range
+operator when it is used with ``.sort()``.
+
+Example
+-------
+
+The following query searches the ``cars`` collection for vehicles
+manufactured by Ford that cost more than $15,000 dollars. The results
+are sorted by model:
+
+.. code-block:: javascript
+
+   db.cars.find(
+      {
+          manufacturer: 'Ford',
+          cost: { $gt: 10000 }
+      } ).sort( { model: 1 } )
+
+
+The query contains all the elements of the ESR Rule:
+
+- ``manufacturer: 'Ford'`` is an equality based match
+- ``cost: { $gt: 10000 }`` is a range based match, and
+- ``model`` is used for sorting
+
+Following the ESR rule, the optimal index for the example query is:
+
+.. code-block:: javascript
+
+   { manufacturer: 1, model: 1, cost: 1 }
+
+Further Discussion
+------------------
+
+A number of MongoDB conference presentations discuss the ESR rule in
+depth.
+
+- `Tips and Tricks for Effective Indexing
+  <https://www.slideshare.net/mongodb/mongodb-local-toronto-2019-tips-and-tricks-for-effective-indexing>`__
+- `The Sights (and Smells) of a Bad Query
+  <https://www.slideshare.net/mongodb/mongodb-world-2019-the-sights-and-smells-of-a-bad-query>`__
+- `Tips and Tricks++ for Querying and Indexing MongoDB
+  <https://www.slideshare.net/mongodb/mongodb-world-2019-tips-and-tricks-for-querying-and-indexing-mongodb>`__
+

source/tutorial/sort-results-with-indexes.txt

@@ -144,6 +144,8 @@ In such cases, MongoDB can use the index to retrieve the documents in
 order specified by the sort. As the example shows, the index prefix in
 the query predicate can be different from the prefix in the sort.
 
+.. _sort-index-nonprefix-subset:
+
 Sort and Non-prefix Subset of an Index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~