Merge remote-tracking branch 'upstream/master' into v6.0

Author: jeff-allen-mongo

Makefile

@@ -151,7 +151,7 @@ examples:
 	curl -SfL https://raw.githubusercontent.com/mongodb/mongo-ruby-driver/master/spec/integration/versioned_api_examples_spec.rb -o ${DRIVERS_PATH}/versioned_api_examples_spec.rb
 
 # rust
-	curl -SfL https://raw.githubusercontent.com/mongodb/mongo-rust-driver/master/src/test/documentation_examples/mod.rs -o ${DRIVERS_PATH}/mod.rs
+	curl -SfL https://raw.githubusercontent.com/mongodb/mongo-rust-driver/main/src/test/documentation_examples/mod.rs -o ${DRIVERS_PATH}/mod.rs
 
 # scala
 	curl -SfL https://raw.githubusercontent.com/mongodb/mongo-scala-driver/master/driver/src/it/scala/org/mongodb/scala/DocumentationExampleSpec.scala -o ${DRIVERS_PATH}/DocumentationExampleSpec.scala

source/applications/indexes.txt

@@ -37,20 +37,24 @@ index, and in addition, MongoDB can use an :doc:`intersection
 
 The following documents introduce indexing strategies:
 
-:doc:`/tutorial/create-indexes-to-support-queries`
+: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.
+
+: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`
+: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`
+: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`
+: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.
@@ -60,6 +64,7 @@ The following documents introduce indexing strategies:
    :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,6 +39,11 @@ operation that resembles the following prototype:
 
 .. include:: /includes/fact-index-specification-field-value.rst
 
+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.
+
 .. important:: 
 
    Starting in MongoDB 4.4: 

source/index.txt

@@ -18,7 +18,7 @@ What is MongoDB?
    .. button:: Get started with MongoDB Atlas
       :uri: https://www.mongodb.com/cloud?tck=docs_server
 
-   .. include:: /includes/fact-mongodb-intro.rst
+   .. include:: /includes/rapid-release-short.rst
 
 .. image:: /images/hero.png
    :alt: Homepage hero image

source/indexes.txt

@@ -142,8 +142,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
 ~~~~~~~~~~~~~~
@@ -284,13 +287,6 @@ Indexes and Collation
 
 .. include:: /includes/extracts/collation-versionadded.rst
 
-----------
-
-|arrow| Use the **Select your language** drop-down menu in the
-upper-right to set the language of the examples on this page.
-
-----------
-
 .. include:: /includes/driver-examples/driver-example-indexes-2.rst
 
 .. include:: /includes/extracts/collation-index-use.rst

source/reference/database-references.txt

@@ -13,58 +13,49 @@ Database References
    :class: singlecol
 
 For many use cases in MongoDB, the denormalized data model where
-related data is stored within a single :term:`document <document>` will
-be optimal. However, in some cases, it makes sense to store related
+related data is stored within a single :term:`document <document>` is optimal. 
+However, in some cases, it makes sense to store related
 information in separate documents, typically in different collections
 or databases.
 
 .. important::
 
-   MongoDB 3.2 introduces :pipeline:`$lookup` pipeline stage to perform
+   You can use the :pipeline:`$lookup` pipeline stage to perform
    a left outer join to an unsharded collection in the same database.
-   For more information and examples, see :pipeline:`$lookup`.
 
-   Starting in MongoDB 3.4, you can also use :pipeline:`$graphLookup`
-   pipeline stage to join an unsharded collection to perform recursive
-   search. For more information and examples, see
-   :pipeline:`$graphLookup`.
+   You can also use the :pipeline:`$graphLookup` pipeline stage to join an 
+   unsharded collection to perform recursive search.
 
 This page outlines alternative procedures that predate the
 :pipeline:`$lookup` and :pipeline:`$graphLookup` pipeline stages.
 
-MongoDB applications use one of two methods for relating documents:
+MongoDB applications use one of two methods to relate documents:
 
-- :ref:`Manual references <document-references>` where you save the
+- :ref:`Manual references <document-references>` save the
   ``_id`` field of one document in another document as a reference.
-  Then your application can run a second query to return the related
+  Your application runs a second query to return the related
   data. These references are simple and sufficient for most use
   cases.
 
 - :ref:`DBRefs <dbref-explanation>` are references from one document to another
   using the value of the first document's ``_id`` field, collection name,
-  and, optionally, its database name. By including these names, DBRefs
-  allow documents located in multiple collections to be more easily linked
-  with documents from a single collection.
-
-  To resolve DBRefs, your application
-  must perform additional queries to return the referenced
-  documents. Many :driver:`Drivers </>` have helper
-  methods that form the query for the DBRef automatically. The
-  drivers [#official-driver]_ do not *automatically* resolve DBRefs
-  into documents.
-
-  DBRefs provide a common format and type to represent relationships among
-  documents. The DBRef format also provides common semantics for representing
-  links between documents if your database must interact with
-  multiple frameworks and tools.
+  and, optionally, its database name, as well as any other fields. DBRefs allow
+  you to more easily reference documents stored in multiple collections or 
+  databases.
+
+To resolve DBRefs, your application must perform additional queries to return
+the referenced documents. Some :driver:`MongoDB drivers </>` provide helper 
+methods to enable DBRefs to be resolved into documents, but it doesn't happen 
+automatically.
+
+DBRefs provide a common format and type to represent relationships among
+documents. The DBRef format also provides common semantics for representing
+links between documents if your database must interact with
+multiple frameworks and tools.
 
 Unless you have a compelling reason to use DBRefs, use manual
 references instead.
 
-.. [#official-driver] Some community supported drivers may have
-   alternate behavior and may resolve a DBRef into a document
-   automatically.
-
 .. _document-references:
 
 Manual References
@@ -73,7 +64,7 @@ Manual References
 Background
 ~~~~~~~~~~
 
-Using manual references is the practice of including one
+A manual reference is the practice of including one
 :term:`document's <document>` ``_id`` field in another document. The
 application can then issue a second query to resolve the referenced
 fields as needed.
@@ -129,7 +120,11 @@ Background
 DBRefs are a convention for representing a :term:`document`, rather
 than a specific reference type. They include the name of the
 collection, and in some cases the database name, in addition to the
-value from the ``_id`` field.
+value from the ``_id`` field. 
+
+Optionally, DBRefs can include any number of other fields. Extra field names 
+must follow any :ref:`rules for field names <limit-restrictions-on-field-names>` 
+imposed by the server version.
 
 Format
 ~~~~~~
@@ -153,8 +148,6 @@ DBRefs have the following fields:
    Contains the name of the database where the referenced document
    resides.
 
-   Only some drivers support ``$db`` references.
-
 .. example::
 
    DBRef documents resemble the following document:
@@ -174,13 +167,15 @@ DBRefs have the following fields:
         "creator" : {
                         "$ref" : "creators",
                         "$id" : ObjectId("5126bc054aed4daf9e2ab772"),
-                        "$db" : "users"
+                        "$db" : "users",
+                        "extraField" : "anything"
                      }
       }
 
    The DBRef in this example points to a document in the ``creators``
    collection of the ``users`` database that has
-   ``ObjectId("5126bc054aed4daf9e2ab772")`` in its ``_id`` field.
+   ``ObjectId("5126bc054aed4daf9e2ab772")`` in its ``_id`` field. It also contains
+   an optional field.
 
 .. note::
 

source/reference/explain-results.txt

@@ -718,14 +718,20 @@ representative. Your output may differ significantly.
             * - ``spilledBytesApprox``
               - The approximate number of in-memory bytes spilled to disk in 
                 the stage.
+
+                .. versionadded:: 5.3
               - ``GROUP``
 
             * - ``spilledRecords``
               - The number of produced records spilled to disk in the stage.
+                
+                .. versionadded:: 5.3
               - ``GROUP``
 
             * - ``usedDisk``
               - Whether the stage wrote to disk.
+
+                .. versionadded:: 5.3
               - ``GROUP``
 
    .. data:: explain.executionStats.allPlansExecution

source/reference/method/cursor.hint.txt

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

source/reference/operator/aggregation/geoNear.txt

@@ -527,4 +527,3 @@ The aggregation returns the following:
          "calculated" : 5887.92792958097
       }
    }
-

source/release-notes/5.0.txt

@@ -19,8 +19,8 @@ Patch Releases
 
 .. _5.0.7-release-notes:
 
-5.0.7 - Upcoming
-~~~~~~~~~~~~~~~~
+5.0.7 - April 11, 2022
+~~~~~~~~~~~~~~~~~~~~~~
 
 Issues fixed: