DOCS-15751 insert delete with indexes (#2486)

* DOCS-15751-insert-delete-with-indexes

* DOCS-15751-insert-delete-with-indexes

* Staging fixes

* Staging fixes

* Staging fixes

* Staging fixes

* Review Feedback

* Review feedback

* Review feedback

* Review feedback

* Review feedback

Author: Dave Cuthbert

source/core/transactions-in-applications.txt

@@ -43,10 +43,13 @@ Callback API
 The callback API incorporates logic:
 
 - To retry the transaction as a whole if the transaction encounters a
-  :ref:`transient-transaction-error`.
+  :ref:`transient-transaction-error` error.
 
 - To retry the commit operation if the commit encounters an
-  :ref:`unknown-transaction-commit-result`.
+  :ref:`unknown-transaction-commit-result` error.
+
+Starting in MongoDB 6.2, the server does not retry the transaction if
+it receives a :ref:`transactionTooLargeForCache-error` error.
 
 Example
 ~~~~~~~
@@ -373,8 +376,8 @@ transaction commits and incorporate retry logic for transactions.
 
 .. _transient-transaction-error:
 
-``"TransientTransactionError"``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``TransientTransactionError``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The *individual* write operations inside the transaction are not
 retryable, regardless of the value of :urioption:`retryWrites`. If an
@@ -393,8 +396,8 @@ the transaction as a whole can be retried.
 
 .. _unknown-transaction-commit-result:
 
-``"UnknownTransactionCommitResult"``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``UnknownTransactionCommitResult``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The commit operations are :doc:`retryable write operations
 </core/retryable-writes>`. If the commit operation encounters an error,
@@ -412,6 +415,27 @@ If the commit operation encounters an error labeled
   ``"UnknownTransactionCommitResult"``, applications should explicitly
   incorporate retry logic for the error.
 
+.. _transactionTooLargeForCache-error:
+
+``TransactionTooLargeForCache``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 6.2 
+
+Starting in MongoDB 6.2, the server does not retry the transaction if
+it receives a ``TransactionTooLargeForCache`` error. This error means
+the cache is too small and a retry is likely to fail.
+
+The default value for the
+:parameter:`transactionTooLargeForCacheThreshold` threshold is ``0.75``.
+The server returns ``TransactionTooLargeForCache`` instead of retrying
+the transaction when the transaction uses more than 75% of the cache.
+
+In earlier versions of MongoDB, the server returns
+``TemporarilyUnavailable`` or ``WriteConflict`` instead of
+``TransactionTooLargeForCache``.
+
+Use the :dbcommand:`setParameter` command to modify the error threshold. 
 
 Driver Version Errors
 ~~~~~~~~~~~~~~~~~~~~~

source/core/transactions.txt

@@ -42,21 +42,14 @@ upper-right to set the language of the following example.
 
 ----------
 
-This example highlights the key components of the transactions API.
-
 .. tabs-selector:: drivers
 
 .. tabs-drivers::
 
    .. tab::
       :tabid: python
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -69,12 +62,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: java-sync
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -141,12 +129,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: nodejs
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -159,12 +142,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: php
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -177,12 +155,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: csharp
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -195,12 +168,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: c
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -212,12 +180,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: cpp
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API also incorporates retry logic for
-      ``TransientTransactionError`` or
-      ``UnknownTransactionCommitResult`` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -230,12 +193,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: motor
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API incorporates retry logic for
-      :ref:`transient-transaction-error` or
-      :ref:`unknown-transaction-commit-result` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -248,12 +206,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: ruby
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API incorporates retry logic for
-      :ref:`transient-transaction-error` or
-      :ref:`unknown-transaction-commit-result` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -267,12 +220,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: go
 
-      The example uses the new callback API for working with
-      transactions, which starts a transaction, executes the
-      specified operations, and commits (or aborts on error). The
-      new callback API incorporates retry logic for
-      :ref:`transient-transaction-error` or
-      :ref:`unknown-transaction-commit-result` commit errors.
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -284,12 +232,7 @@ This example highlights the key components of the transactions API.
    .. tab::
       :tabid: perl
 
-      This example uses the :ref:`core API <txn-core-api>`. Because the
-      core API does not incorporate retry logic for
-      :ref:`transient-transaction-error` or
-      :ref:`unknown-transaction-commit-result` commit errors, the
-      example includes explicit logic to retry the transaction for these
-      errors:
+      .. include:: /includes/transactions/example-intro.rst
 
       .. include:: /includes/extracts/transactions-example-note.rst
 
@@ -302,7 +245,7 @@ This example highlights the key components of the transactions API.
       :tabid: scala
 
       This example uses the :ref:`core API <txn-core-api>`. Because the
-      core API does not incorporate retry logic for
+      core API does not incorporate retry logic for the
       :ref:`transient-transaction-error` or
       :ref:`unknown-transaction-commit-result` commit errors, the
       example includes explicit logic to retry the transaction for

source/includes/transactions/example-intro.rst

@@ -0,0 +1,16 @@
+This example highlights the key components of the transactions API. In
+particular, it uses the callback API. The callback API:
+
+- starts a transaction
+- executes the specified operations
+- commits the result (or aborts on error)
+
+The callback API incorporates retry logic for certain errors. The server
+tries to rerun the transaction after a :ref:`TransientTransactionError
+<transient-transaction-error>` or :ref:`UnknownTransactionCommitResult
+<unknown-transaction-commit-result>` commit error.
+
+Starting in MongoDB 6.2, the server does not retry the transaction if
+it receives a :ref:`TransactionTooLargeForCache
+<transactionTooLargeForCache-error>` error.
+

source/reference/configuration-options.txt

@@ -3973,6 +3973,8 @@ LDAP Parameters
    :setting:`~storage.oplogMinRetentionHours`.
 
 
+.. _wiredTiger-storage-options:
+
 ``storage.wiredTiger`` Options
 ``````````````````````````````
 

source/reference/parameters.txt

@@ -4944,7 +4944,39 @@ Transaction Parameters
    modified for all shard replica set members.
 
    .. include:: /includes/transactionLifetimeLimitSeconds-parameter.rst
+
+.. parameter:: transactionTooLargeForCacheThreshold
+
+   .. versionadded:: 6.2
+
+   |mongod-only|
+
+   *Type*: decimal
+
+   *Default*: 0.75
+
+   The threshold value for retrying transactions that fail due to cache
+   pressure. The value is a percentage of the dirty cache size. The
+   default value, ``0.75``, means 75% of the dirty cache.
+   
+   The dirty cache is limited to 20% of the total cache size. When
+   ``transactionTooLargeForCacheThreshold`` is set to ``0.75``, the
+   server only retries transactions that use less than 15%
+   (``0.75 * 20%``) of the total storage engine cache.
 
+   The limit only applies to retries. Large transactions can use more
+   than ``transactionTooLargeForCacheThreshold`` percent of the dirty
+   cache. However, if a large transaction is rolled back due to cache
+   pressure, the server issues a
+   :ref:`transactionTooLargeForCache-error` error and does not retry the
+   transaction. 
+  
+   To disable this behavior, set
+   ``transactionTooLargeForCacheThreshold`` to ``1.0``.
+
+   For more information on WiredTiger storage, see:
+   :ref:`wiredTiger-storage-options`.
+
 .. parameter:: maxTransactionLockRequestTimeoutMillis
 
    .. versionadded:: 4.0

source/release-notes/6.2.txt

@@ -50,6 +50,12 @@ instances. Latencies reported by ``mongos`` include operation latency
 time and communication time between the ``mongod`` and ``mongos`` 
 instances.
 
+Server Parameters
+~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 6.2, :binary:`mongod` adds these parameters:
+
+- :parameter:`transactionTooLargeForCacheThreshold`
 
 Deprecated Commands
 ~~~~~~~~~~~~~~~~~~~