DOCSP-19212 change stream events and orphans (#740)

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

* DOCSP-19212-change-stream-events-and-orphans

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/administration/change-streams-production-recommendations.txt

@@ -99,3 +99,7 @@ Change Stream Optimization
 
 .. include:: /includes/change-streams-optimization.rst
 
+Change Streams and Orphan Documents
+-----------------------------------
+
+.. include:: /includes/change-streams-and-orphans.rst

source/changeStreams.txt

@@ -1045,6 +1045,11 @@ versions, change streams opened on a single collection
 (:method:`db.collection.watch()`) would inherit that collection's
 default collation.
 
+Change Streams and Orphan Documents
+-----------------------------------
+
+.. include:: /includes/change-streams-and-orphans.rst
+
 .. toctree::
    :titlesonly:
    :hidden:

source/core/distributed-queries.txt

@@ -38,11 +38,8 @@ Read operations from secondary members of replica sets may not reflect
 the current state of the primary. Read preferences that direct read
 operations to different servers may result in non-monotonic reads.
 
-.. versionchanged:: 3.6
-
-   Starting in MongoDB 3.6, clients can use :ref:`causally consistent
-   <causal-consistency>` sessions, which provides various guarantees,
-   including monotonic reads.
+Clients can use :ref:`causally consistent <causal-consistency>`
+sessions, which provides various guarantees including monotonic reads.
 
 You can configure the read preference on a per-connection or
 per-operation basis. For more information on read preference or on the
@@ -67,7 +64,6 @@ For more information on replica sets and write operations, see
 :doc:`/replication` and
 :doc:`/reference/write-concern`.
 
-
 .. _read-operations-sharded-clusters:
 
 Read Operations to Sharded Clusters
@@ -104,10 +100,7 @@ replica sets may not reflect the current state of the primary. Read
 preferences that direct read operations to different servers may result
 in non-monotonic reads.
 
-
 .. note::
-
-   Starting in MongoDB 3.6, 
 
    - Clients can use :ref:`causally consistent <causal-consistency>`
      sessions, which provides various guarantees, including monotonic
@@ -164,6 +157,9 @@ For more information, see :doc:`/sharding` and
 
    :ref:`retryable-writes`
 
+Change Streams and Orphan Documents
+-----------------------------------
 
+.. include:: /includes/change-streams-and-orphans.rst
 
 .. _read-operations-connection-pooling:

source/core/sharding-balancer-administration.txt

@@ -13,7 +13,6 @@ Sharded Cluster Balancer
    :depth: 1
    :class: singlecol
 
-
 The MongoDB balancer is a background process that monitors the number of
 :term:`chunks <chunk>` on each :term:`shard`. When the number of chunks on a
 given shard reaches specific :ref:`migration thresholds
@@ -60,18 +59,15 @@ Chunk migrations carry some overhead in terms of bandwidth and
 workload, both of which can impact database performance. [#auto-distribute]_ The
 :term:`balancer` attempts to minimize the impact by:
 
-- Restricting a shard to at most one migration at any given time; i.e.
-  a shard cannot participate in multiple chunk migrations at the same
-  time. To migrate multiple chunks from a shard, the balancer migrates
-  the chunks one at a time.
-
-  .. versionchanged:: 3.4
+- Restricting a shard to at most one migration at any given time.
+  Specifically, a shard cannot participate in multiple chunk migrations
+  at the same time. To migrate multiple chunks from a shard, the
+  balancer migrates the chunks one at a time.
 
-     Starting in MongoDB 3.4, MongoDB can perform parallel chunk
-     migrations. Observing the restriction that a shard can participate
-     in at most one migration at a time, for a sharded cluster with *n*
-     shards, MongoDB can perform at most *n/2* (rounded down)
-     simultaneous chunk migrations.
+  MongoDB can perform parallel chunk migrations, but a shard can
+  participate in at most one migration at a time. For a sharded cluster
+  with *n* shards, MongoDB can perform at most *n/2* (rounded down)
+  simultaneous chunk migrations.
 
   See also :ref:`chunk-migration-queuing`.
 
@@ -260,8 +256,6 @@ testing purposes. For more information, see
 Chunk Migration and Replication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionchanged:: 3.4
-
 During chunk migration, the ``_secondaryThrottle`` value determines
 when the migration proceeds with next document in the chunk.
 
@@ -282,7 +276,6 @@ In the :data:`config.settings` collection:
   does not wait for replication to a secondary and instead continues
   with the next document.
 
-
 To update the ``_secondaryThrottle`` parameter for the balancer, see
 :ref:`sharded-cluster-config-secondary-throttle` for an example.
 
@@ -335,6 +328,11 @@ with :parameter:`rangeDeleterBatchSize` and
    collection targeted for deletes, range deletion processes may
    not proceed.
 
+Change Streams and Orphan Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/change-streams-and-orphans.rst
+
 .. _sharding-shard-size:
 
 Shard Size

source/core/transactions.txt

@@ -819,6 +819,21 @@ Storage Engines
 
 .. include:: /includes/extracts/transactions-inmemory-txn-page.rst
 
+Limit Critical Section Wait Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 5.2 (and 5.0.4):
+
+- When a query accesses a shard, a :ref:`chunk migration
+  <migrate-chunks-sharded-cluster>` or :ref:`DDL operation
+  <transactions-operations-ddl>` may hold the critical section for the
+  collection.
+
+- To limit the time a shard waits for a critical section within a
+  transaction, use the
+  :parameter:`metadataRefreshInTransactionMaxWaitBehindCritSecMS`
+  parameter.
+
 Additional Transactions Topics
 ------------------------------
 

source/includes/change-streams-and-orphans.rst

@@ -0,0 +1,4 @@
+Starting in MongoDB 5.3, during :ref:`chunk migration
+<chunk-migration-procedure>`, :ref:`change stream <changeStreams>`
+events are not generated for updates to :term:`orphaned documents
+<orphaned document>`.

source/release-notes/5.3-compatibility.txt

@@ -35,6 +35,11 @@ single document.
 
 See :parameter:`indexMaxNumGeneratedKeysPerDocument`.
 
+Change Streams and Orphan Documents
+-----------------------------------
+
+.. include:: /includes/change-streams-and-orphans.rst
+
 Intra-Cluster Authentication
 ----------------------------
 
@@ -46,4 +51,3 @@ Starting in MongoDB 5.3.0, 5.2.1, and 5.0.6, the :dbcommand:`dbStats`
 command and the :method:`db.stats()` method only report free space
 assigned to collections if the :ref:`freeStorage <dbStats-freeStorage>`
 parameter is set to 1.
-

source/tutorial/migrate-chunks-in-sharded-cluster.txt

@@ -91,3 +91,8 @@ balancer proceeds with the next document in the migrating chunk. See
    cursors manually.
 
    .. todo:: insert link to killing a cursor.
+
+Change Streams and Orphan Documents
+-----------------------------------
+
+.. include:: /includes/change-streams-and-orphans.rst