MONGOID-4902 Include shard key when reloading documents for improved query performance with Atlas Global Write clusters (#4791)

* Use atomic selector for document reload and update docs for Atlas Global Cluster

* Sharding docs formatting tweak

* add a test to check that reload uses shard key on sharded cluster

* add a test for embedded document

* Cleaned up some unnecessary test code

* added a note to the change log

* added info to change logs and documentation

* move changelog info to new 7.2 section

* tweak documentation

Co-authored-by: Emily Giurleo <[email protected]>
Co-authored-by: Oleg Pudeyev <[email protected]>

Author: 3 people

source/tutorials/mongoid-upgrade.txt

@@ -18,6 +18,55 @@ please consult GitHub releases for detailed release notes and JIRA for
 the complete list of issues fixed in each release, including bug fixes.
 
 
+Upgrading to Mongoid 7.2
+========================
+
+The following sections describe major changes in Mongoid 7.2.
+
+Shard Key Used For Reloading
+----------------------------
+
+Minor change: When sharding is used, Mongoid 7.2 expects the shard key declared
+in models to match the shard key in the database for the respective collections.
+In Mongoid 7.2 model reloading (either explicit via the ``reload`` method
+or implicit as part of persistence operations) uses the shard key, if one is
+defined, in the ``find`` command in addition to the ``id`` field value.
+This improves the performance of document reloading, and consequently some
+persistence operations, in sharded clusters, especially those with
+`geographically distributed shards
+<https://docs.atlas.mongodb.com/global-clusters/>`_.
+
+Consider a class ``Band`` whose documents are sharded by the ``name`` key.
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+
+    shard_key :name
+  end
+
+Example Mongoid 7.2 behavior:
+
+.. code-block:: ruby
+
+  band = Band.create(name: "Destiny's Child")
+  band.reload
+  # Command logs: { "find"=>"bands", "filter"=>{ "_id"=>BSON::ObjectId('...') "name"=>"Destiny's Child" } }
+
+Example Mongoid 7.1 behavior:
+
+.. code-block:: ruby
+
+  band = Band.create(name: "Destiny's Child")
+  band.reload
+  # Command logs: { "find"=>"bands", "filter"=>{"_id"=>BSON::ObjectId('...') } }
+
+Mongoid provides :ref:`sharding management Rake tasks <sharding-management>`
+to shard collections according to shard keys declared in models.
+
+
 Upgrading to Mongoid 7.1
 ========================
 
@@ -216,6 +265,7 @@ example, the following two approaches result in the same generated selector:
     #   class:    Band
     #   embedded: false>
 
+
 Ruby Version Support
 --------------------
 

source/tutorials/sharding.txt

@@ -25,11 +25,11 @@ Shard keys can be declared on models using the ``shard_key`` macro:
 
   class Person
     include Mongoid::Document
-    
+
     field :ssn
 
     shard_key ssn: 1
-    
+
     # The collection must also have an index that starts with the shard key.
     index ssn: 1
   end
@@ -48,11 +48,11 @@ collection sharding options:
 .. code-block:: ruby
 
   shard_key ssn: 1
-  
+
   shard_key ssn: 1, country: 1
-  
+
   shard_key ssn: :hashed
-  
+
   shard_key {ssn: :hashed}, unique: true
 
 The alternative is the shorthand syntax, in which only the keys are given.
@@ -62,7 +62,7 @@ be specified:
 .. code-block:: ruby
 
   shard_key :ssn
-  
+
   shard_key :ssn, :country
 
 ``shard_key`` macro can take the name of a ``belongs_to`` association in
@@ -71,16 +71,26 @@ configured in the association as the field name:
 
   class Person
     include Mongoid::Document
-    
+
     belongs_to :country
 
     # Shards by country_id.
     shard_key country: 1
-    
+
     # The collection must also have an index that starts with the shard key.
     index country: 1
   end
 
+.. note::
+
+  If a model declares a shard key, Mongoid expects the respective collection
+  to be sharded with the specified shard key. When reloading models, Mongoid
+  will provide the shard key in addition to the ``id`` field value to the
+  ``find`` command to improve query performance, especially on `geographically
+  distributed sharded clusters <https://docs.atlas.mongodb.com/global-clusters/>`_.
+  If the collection is not sharded with the specified shard key, queries
+  may produce incorrect results.
+
 
 .. _sharding-management: