DOCSP-38442 Update contention factor guidance (#7399)

* Initial structural changes

* Subscript/superscript rendering check

* Parsing fix

* Syntax fixes

* Additional clarification

* Syntax and wording

* Line break

* Wording change

* Wording change

* Updated wording

* Updated wording

* Updated wording

* Fixed wording

* Changed chapter to section

* Apply suggestions from code review

Internal review feedback

Co-authored-by: Jeff Allen <[email protected]>

* Line break

* Monospace

---------

Co-authored-by: Jeff Allen <[email protected]>

Author: nvillahermosa-mdb

source/core/queryable-encryption/fundamentals/encrypt-and-query.txt

@@ -55,14 +55,20 @@ the storage space requirements.
 
 .. _qe-contention:
 
-Configure Contention Factor
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Include the ``contention`` property on queryable fields to prefer either
-find performance, or write and update performance.
+Contention
+----------
 
 .. include:: /includes/queryable-encryption/qe-csfle-contention.rst
 
+Adjusting the Contention Factor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can optionally include the ``contention`` property on queryable fields to
+change the contention factor from its default value of ``8``. Before you modify 
+the contention factor, consider the following points:
+
+.. include:: /includes/queryable-encryption/qe-csfle-setting-contention.rst
+
 .. _qe-query-types:
 
 Supported Query Types and Behavior

source/core/queryable-encryption/reference/limitations.txt

@@ -33,12 +33,11 @@ Contention Factor
 -----------------
 
 Contention factor is a setting that helps tune performance based on the
-number of concurrent connections.
+number of concurrent operations. When unset, contention uses a default value of
+``8``, which provides high performance for most workloads.
 
 You can set the contention factor only when specifying a field for encryption.
-Once you specify a field for encryption, the contention factor is immutable. If
-you don't specify the contention factor, it uses the default value of
-``8``.
+Once you specify a field for encryption, the contention factor is immutable.
 
 For more information, see :ref:`Configuring contention factor <qe-contention>`.
 

source/includes/queryable-encryption/qe-csfle-contention.rst

@@ -1,40 +1,16 @@
-Inserting the same field/value pair into multiple documents in close
-succession can cause conflicts that delay insert operations.
+Concurrent write operations, such as inserting the same field/value pair into
+multiple documents in close succession, can cause contention: conflicts that
+delay operations.
 
-MongoDB tracks the occurrences of each field/value pair in an
+With {+qe+}, MongoDB tracks the occurrences of each field/value pair in an
 encrypted collection using an internal counter. The contention factor
 partitions this counter, similar to an array. This minimizes issues with
 incrementing the counter when using ``insert``, ``update``, or ``findAndModify`` to add or modify an encrypted field
 with the same field/value pair in close succession. ``contention = 0``
-creates an array with one element
-at index 0. ``contention = 4`` creates an array with 5 elements at
-indexes 0-4. MongoDB increments a random array element during insert. If
-unset, ``contention`` defaults to 8.
+creates an array with one element at index 0. ``contention = 4`` creates an
+array with 5 elements at indexes 0-4. MongoDB increments a random array element
+during insert.
 
-High contention improves the performance of insert and update operations
-on low cardinality fields, but decreases find performance.
-
-Consider increasing ``contention`` above the default value of 8 only if:
-
-- The field has low cardinality or low selectivity. A ``state`` field
-  may have 50 values, but if 99% of the data points use ``{state: NY}``,
-  that pair is likely to cause contention.
-
-- Write and update operations frequently modify the field. Since high
-  contention values sacrifice find performance in favor of write and
-  update operations, the benefit of a high contention factor for a
-  rarely updated field is unlikely to outweigh the drawback.
-
-Some other examples of low cardinality fields are credit card types,
-gender, and ethnicity.
-
-Consider decreasing ``contention`` if:
-
-- The field is high cardinality and contains entirely unique values,
-  such as a credit card number.
-
-- The field is often queried, but never or rarely updated. In this
-  case, find performance is preferable to write and update performance.
-
-Some other examples of high cardinality fields are mobile phone numbers,
-social security numbers, full names, and addresses.
+When unset, ``contention`` defaults to ``8``, which provides high performance
+for most workloads. Higher contention improves the performance of insert and
+update operations on low cardinality fields, but decreases find performance.

source/includes/queryable-encryption/qe-csfle-setting-contention.rst

@@ -0,0 +1,46 @@
+Consider increasing ``contention`` above the default value of ``8`` only if the
+field has frequent concurrent write operations. Since high contention values
+sacrifice find performance in favor of insert and update operations, the
+benefit of a high contention factor for a rarely updated field is unlikely to
+outweigh the drawback.
+
+Consider decreasing ``contention`` if a field is often queried, but
+rarely written. In this case, find performance is preferable to write and 
+update performance.
+
+You can calculate contention factor for a field by using a formula where:
+
+- ``ω`` is the number of concurrent write operations on the field in a short
+  time, such as 30ms. If unknown, you can use the server's number of virtual 
+  cores.
+- ``valinserts`` is the number of unique field/value pairs inserted since last
+  performing :ref:`metadata compaction <qe-metadata-compaction>`.
+- ``ω``:sup:`∗` is ``ω/valinserts`` rounded up to the nearest integer. For a
+  workload of 100 operations with 1000 recent values, ``100/1000 = 0.1``,
+  which rounds up to ``1``.
+
+A reasonable contention factor, ``cf``, is the result of the following 
+formula, rounded up to the nearest positive integer:
+
+``(ω``:sup:`∗` ``· (ω``:sup:`∗` ``− 1)) / 0.2``
+
+For example, if there are 100 concurrent write operations on a field in 30ms,
+then ``ω = 100``. If there are 50 recent unique values for that field, then
+``ω``:sup:`∗` ``= 100/50 = 2``. This results in ``cf = (2·1)/0.2 = 10``.
+
+.. warning::
+
+   Don't set the contention factor on properties of the data itself, such as
+   the frequency of field/value pairs (:term:`cardinality`). Only set the contention factor based on your workload.
+   
+   Consider a case
+   where ``ω = 100`` and ``valinserts = 1000``, resulting in ``ω``:sup:`∗` ``=
+   100/1000 = 0.1 ≈ 1`` and ``cf = (1·0)/0.2 = 0 ≈ 1``. 20 of
+   the values appear very frequently, so you set ``contention = 3`` instead. An
+   attacker with access to multiple database snapshots can infer that the high
+   setting indicates frequent field/value pairs. In this case, leaving
+   ``contention`` unset so that it defaults to ``8`` would prevent the attacker
+   from having that information.
+
+For thorough information on contention and its cryptographic implications, see
+"Section 9: Guidelines" in MongoDB's `Queryable Encryption Technical Paper <https://www.mongodb.com/collateral/queryable-encryption-technical-paper>`_