DOCS-11604,DOCS-11425, DOCS-11637: system collection restrictions, getMore restrictions, update txn operations pages

Author: kay-kim

source/core/transactions.txt

@@ -26,7 +26,7 @@ However, for situations that require atomicity for updates to multiple
 documents or consistency between reads to multiple documents, MongoDB
 provides the ability to perform multi-document transactions against
 replica sets. Multi-document transactions can be used across multiple
-operations, collections, and documents. Multi-document transactions
+operations, collections, databases, and documents. Multi-document transactions
 provide an "all-or-nothing" proposition. When a transaction commits,
 all data changes made in the transaction are saved. If any operation in
 the transaction fails, the transaction aborts and all data changes made
@@ -65,7 +65,7 @@ Storage Engines
 ~~~~~~~~~~~~~~~
 
 Multi-document transactions are available for the WiredTiger storage
-engine and in-memory storage engines. 
+engine and in-memory storage engines.
 
 If any voting member of a replica set uses the in-memory storage
 engine, you must set :rsconf:`writeConcernMajorityJournalDefault` to
@@ -76,20 +76,18 @@ engine, you must set :rsconf:`writeConcernMajorityJournalDefault` to
 Transactions and Operations
 ---------------------------
 
-For multi-document transactions:
-
-- You can specify read/write (CRUD) operations on **existing**
-  collections. 
+For transactions:
 
-- You cannot read/write to collections in the ``config``, ``admin``,
-  or ``local`` databases.
+.. include:: /includes/extracts/transactions-operations-crud.rst
 
 Operations that affect the database catalog, such as creating or
-dropping a collection or an index, are not allowed in multi-document	
-transactions. For example, a multi-document transaction cannot include	
-an insert operation that would result in the creation of a new	
+dropping a collection or an index, are not allowed in multi-document
+transactions. For example, a multi-document transaction cannot include
+an insert operation that would result in the creation of a new
 collection. See :ref:`transactions-ops-restricted`.
 
+For multi-document transactions:
+
 .. include:: /includes/table-transactions-operations.rst
 
 .. _transactions-ops-count:
@@ -219,7 +217,7 @@ function if a ``"TransientTransactionError"`` is encountered:
                break;
            } catch (error) {
                print("Transaction aborted. Caught exception during transaction.");
-    
+
                // If transient error, retry the whole transaction
                if ( error.hasOwnProperty("errorLabels") && error.errorLabels.includes( "TransientTransactionError")  ) {
                    print("TransientTransactionError, retrying transaction ...");
@@ -299,7 +297,7 @@ and retrying the commit, the full code example is:
                    throw error;
                }
            }
-       }   
+       }
    }
 
    // Retries commit if UnknownTransactionCommitResult encountered
@@ -375,10 +373,22 @@ Read Preference
 
 .. include:: /includes/extracts/transactions-read-pref.rst
 
+.. _transaction-options:
+
+Transaction Options
+-------------------
+
+.. code-block:: javascript
+
+   session.startTransaction( {
+      readConcern: { level: <level>},
+      writeConcern: { w: <value>, j: <boolean>, wtimeout: <number> } 
+   } );
+
 .. _txn-read-concern:
 
 Read Concern
-------------
+~~~~~~~~~~~~
 
 Multi-document transactions support read concern
 :readconcern:`"snapshot"`, :readconcern:`"local"`, and
@@ -419,7 +429,7 @@ concern.
 .. _transactions-write-concern:
 
 Write Concern
--------------
+~~~~~~~~~~~~~
 
 You set the write concern at the transaction level, not at the
 individual operation level. At the time of the commit, transactions use

source/includes/apiargs-dbcommand-update-field.yaml

@@ -37,6 +37,9 @@ description: |
   A document expressing the :doc:`write concern </reference/write-concern>`
   of the :dbcommand:`update` command. Omit to use the default write
   concern.
+
+  .. include:: /includes/extracts/transactions-operations-write-concern.rst
+
 interface: dbcommand
 name: writeConcern
 operation: update

source/includes/apiargs-method-Bulk.execute-param.yaml

@@ -8,6 +8,9 @@ description: |
   <repl-set-modify-default-write-concern>`.
 
   See :ref:`bulk-execute-ex-write-concern` for an example.
+  
+  .. include:: /includes/extracts/transactions-operations-write-concern.rst
+  
 interface: method
 name: writeConcern
 operation: Bulk.execute

source/includes/apiargs-method-db.collection.update-param.yaml

@@ -59,7 +59,8 @@ description: |
   </reference/write-concern>`. Omit to use the default write concern.
   See :ref:`update-wc`.
 
-  .. versionadded:: 2.6
+  .. include:: /includes/extracts/transactions-operations-write-concern.rst
+
 interface: method
 name: writeConcern
 operation: db.collection.update

source/includes/extracts-transactions.yaml

@@ -10,11 +10,16 @@ ref: transactions-usage
 content: |
    .. important::
 
-      Multi-document transaction incurs a greater performance cost over
-      single document writes, and the availability of multi-document
-      transaction should not be a replacement for effective schema design.
-      For many scenarios, the denormalized data model will continue to be
-      optimal for your data and use cases.
+      In most cases, multi-document transaction incurs a greater
+      performance cost over single document writes, and the
+      availability of multi-document transaction should not be a
+      replacement for effective schema design. For many scenarios, the
+      :ref:`denormalized data model (embedded documents and arrays)
+      <data-modeling-embedding>` will continue to be optimal for your
+      data and use cases. That is, for many scenarios, modeling your data
+      appropriately will minimize the need for multi-document
+      transactions.
+
 ---
 ref: transactions-intro
 content: |
@@ -78,5 +83,56 @@ content: |
    abort operation encounters an error, MongoDB drivers retry the
    operation a single time regardless of whether :urioption:`retryWrites` is
    set to ``true``.
+---
+ref: transactions-operations-crud
+content: |
+   - You can specify read/write (CRUD) operations on **existing**
+     collections.  The collections can be in different databases.
+
+   - You cannot read/write to collections in the ``config``, ``admin``,
+     or ``local`` databases.
+
+   - You cannot write to ``system.*`` collections.
+
+   - You cannot return the supported operation's query plan (i.e. ``explain``).
+
+   .. include:: /includes/extracts/transactions-operations-getMore.rst
+
+---
+ref: transactions-operations-getMore
+content: |
+
+   - For cursors created outside of transactions, you cannot call
+     :dbcommand:`getMore` inside a transaction.
+
+   - For cursors created in a transaction, you cannot call
+     :dbcommand:`getMore` outside the transaction.
+
+---
+ref: transactions-supported-operation
+content: |
+
+   |operation| supports :doc:`multi-document transactions
+   </core/transactions>`.
+
+---
+ref: transactions-operations-write-concern
+content: |
+
+   Do not explicitly set the write concern for the operation if run in
+   a transaction. To use write concern with transactions, see
+   :ref:`transaction-options`.
+
+---
+ref: transactions-read-concern-tip
+content: |
+   In MongoDB 4.0, all multi-documents transactions have ``snapshot`` isolation. In
+   future versions of MongoDB, the server will optimize around your specified read
+   concern (isolation level).  
 
+   For :readconcern:`"local"` and :readconcern:`"majority"` read concern, MongoDB
+   may provide stronger isolation guarantees than specified. If stronger guarantees
+   are needed, be explicit as future versions of the server may include
+   optimizations that remove stronger isolation guarantees than explicitly
+   specified.
 ...

source/includes/table-sql-to-mongo-terms.rst

@@ -36,3 +36,16 @@
      - aggregation pipeline
 
        See the :doc:`/reference/sql-aggregation-comparison`.
+
+   * - transactions
+
+     - :doc:`/core/transactions`
+
+       .. tip::
+
+          For many scenarios, the :ref:`denormalized data model
+          (embedded documents and arrays) <data-modeling-embedding>`
+          will continue to be optimal for your data and use cases
+          instead of multi-document transactions. That is, for many
+          scenarios, modeling your data appropriately will minimize the
+          need for multi-document transactions.

source/includes/table-transactions-operations.rst

@@ -41,7 +41,8 @@
        | :method:`db.collection.findOneAndUpdate()`
 
      - :dbcommand:`findAndModify`
-     - 
+     - For ``upsert``, only when run against an existing collection.
+
 
    * - | :method:`db.collection.insertMany()`
        | :method:`db.collection.insertOne()`
@@ -51,9 +52,13 @@
 
      - Only when run against an existing collection.
 
+   * - :method:`db.collection.save()`
+     - 
+     - If an insert, only when run against an existing collection.
 
    * - | :method:`db.collection.updateOne()`
        | :method:`db.collection.updateMany()`
+       | :method:`db.collection.replaceOne()`
        | :method:`db.collection.update()`
 
      - :dbcommand:`update`

source/reference/command/aggregate.txt

@@ -56,6 +56,17 @@ For more information about the aggregation pipeline
 :doc:`/core/aggregation-pipeline`, :doc:`/reference/aggregation`, and
 :doc:`/core/aggregation-pipeline-limits`.
 
+Sessions
+~~~~~~~~
+
+.. versionadded:: 4.0
+
+For cursors created inside a session, you cannot call
+:dbcommand:`getMore` outside the session.
+
+Similarly, for cursors created outside of a session, you cannot call
+:dbcommand:`getMore` inside a session.
+
 Transactions
 ------------
 
@@ -72,6 +83,8 @@ However, the following stages are not allowed within transactions:
 
 You also cannot specify the ``explain`` option.
 
+.. include:: /includes/extracts/transactions-operations-getMore.rst
+
 .. include:: /includes/extracts/transactions-usage.rst
 
 .. |operation| replace:: :dbcommand:`aggregate`

source/reference/command/delete.txt

@@ -82,8 +82,6 @@ Transactions
 
 .. include:: /includes/extracts/transactions-usage.rst
 
-.. |operation| replace:: :dbcommand:`delete`
-
 
 Examples
 --------

source/reference/command/find.txt

@@ -62,11 +62,24 @@ Definition
 Behavior
 --------
 
+Sessions
+~~~~~~~~
+
+.. versionadded:: 4.0
+
+For cursors created inside a session, you cannot call
+:dbcommand:`getMore` outside the session.
+
+Similarly, for cursors created outside of a session, you cannot call
+:dbcommand:`getMore` inside a session.
+
 Transactions
 ~~~~~~~~~~~~
 
 .. include:: /includes/extracts/transactions-supported-operation.rst
 
+.. include:: /includes/extracts/transactions-operations-getMore.rst
+
 .. include:: /includes/extracts/transactions-usage.rst
 
 .. |operation| replace:: :dbcommand:`find`

source/reference/command/findAndModify.txt

@@ -159,15 +159,12 @@ Transactions
 
 .. include:: /includes/extracts/transactions-supported-operation.rst
 
-If ``upsert: true``, the collection must already exist.
+If the operation results in an upsert, the collection must already exist.
 
 .. include:: /includes/extracts/transactions-operations-write-concern.rst
 
 .. include:: /includes/extracts/transactions-usage.rst
 
-
-.. |operation| replace:: :dbcommand:`findAndModify`
-
 Examples
 --------
 

source/reference/command/geoSearch.txt

@@ -43,7 +43,7 @@ Transactions
 
 .. include:: /includes/extracts/transactions-usage.rst
 
-.. |operation| replace:: :dbcommand:`distinct`
+.. |operation| replace:: :dbcommand:`geoSearch`
 
 Examples
 --------

source/reference/command/getMore.txt

@@ -36,9 +36,35 @@ Definition
 
    .. include:: /includes/apiargs/dbcommand-getMore-field.rst
 
-   .. versionadded:: 3.6
 
-   If :doc:`authentication </core/authentication>` is turned on, you can 
-   only issue a :dbcommand:`getMore` against cursors you created.
+Behavior
+--------
+
+Access Control
+~~~~~~~~~~~~~~
+
+.. versionadded:: 3.6
+
+If :doc:`authentication </core/authentication>` is turned on, you can 
+only issue a :dbcommand:`getMore` against cursors you created.
+
+Sessions
+~~~~~~~~
+
+.. versionadded:: 4.0
+
+For cursors created inside a session, you cannot call
+:dbcommand:`getMore` outside the session.
+
+Similarly, for cursors created outside of a session, you cannot call
+:dbcommand:`getMore` inside a session.
+
+Transactions
+````````````
+
+.. versionadded:: 4.0
+
+For :doc:`multi-document transactions </core/transactions>`:
+
+.. include:: /includes/extracts/transactions-operations-getMore.rst
 
-.. seealso:: :ref:`3.2-driver-compatibility`

source/reference/command/update.txt

@@ -116,6 +116,19 @@ Document Validation
 
 .. include:: /includes/extracts/bypassDocumentValidation-update.rst
 
+Transactions
+~~~~~~~~~~~~
+
+.. include:: /includes/extracts/transactions-supported-operation.rst
+
+If the operation results in an upsert, the collection must already exist.
+
+.. include:: /includes/extracts/transactions-operations-write-concern.rst
+
+.. include:: /includes/extracts/transactions-usage.rst
+
+.. |operation| replace:: :dbcommand:`update`
+
 Examples
 --------