DOCS-12032,DOCS-11942: index key limit fcv4.2

kay-kim · kay-kim · commit d04f90e582ee · 2018-10-10T16:20:14.000-04:00
diff --git a/source/core/document.txt b/source/core/document.txt
@@ -95,10 +95,11 @@ existing user document.
 Field Value Limit
 ~~~~~~~~~~~~~~~~~
 
-For :doc:`indexed collections </indexes>`, the values
-for the indexed fields have a
-:limit:`Maximum Index Key Length <Index Key Limit>` limit. See
-:limit:`Maximum Index Key Length <Index Key Limit>` for details.
+
+MongoDB 2.6 through MongoDB versions with :ref:`featureCompatibilityVersion <view-fcv>` (fCV) set to ``"4.0"`` or earlier
+   For :doc:`indexed collections </indexes>`, the values for the
+   indexed fields have a :limit:`Maximum Index Key Length <Index Key Limit>`. See
+   :limit:`Maximum Index Key Length <Index Key Limit>` for details.
 
 .. _document-dot-notation:
 
diff --git a/source/includes/extracts-4.2-downgrade-fcv.yaml b/source/includes/extracts-4.2-downgrade-fcv.yaml
@@ -0,0 +1,18 @@
+ref: 4.2-downgrade-fcv-index-key
+content: |
+
+   Starting in MongoDB 4.2, for ``featureCompatibilityVersion`` set to
+   ``"4.2"`` or greater, MongoDB removes the :limit:`Index Key Limit`. For
+   ``featureCompatibilityVersion`` set to ``"4.0"``, the limit still
+   applies. 
+
+   If you have an index with keys that exceed the :limit:`Index Key
+   Limit` once ``featureCompatibilityVersion`` is set to ``"4.0"``,
+   consider changing the index to a hashed index or to indexing a
+   computed value. You can also **temporarily** use
+   :parameter:`failIndexKeyTooLong` set to ``false`` before resolving
+   the problem. However, withs :parameter:`failIndexKeyTooLong` set to
+   ``false``, queries that use these indexes can return incomplete
+   results.
+   
+...
diff --git a/source/includes/list-index-field-limit-behaviors.rst b/source/includes/list-index-field-limit-behaviors.rst
@@ -1,5 +1,4 @@
-MongoDB versions 2.6 and greater implement a stronger enforcement of the limit on
-:limit:`index key <Index Key Limit>`:
+When the :limit:`Index Key Limit` applies:
 
 - .. include:: /includes/fact-index-key-length-operation-behaviors.rst
      :start-after: index-field-limit-ensureIndex
diff --git a/source/reference/limits.txt b/source/reference/limits.txt
@@ -113,16 +113,22 @@ Indexes
 .. _limit-index-size:
 .. limit:: Index Key Limit
 
-   The *total size* of an index entry, which can include structural
-   overhead depending on the BSON type, must be *less than* 1024 bytes.
+   .. versionchanged:: 4.2
+
+      MongoDB removes the :limit:`Index Key Limit` for fCV set to
+      ``"4.2"`` or greater.
+
+   For MongoDB 2.6 through MongoDB versions with
+   :ref:`featureCompatibilityVersion <view-fcv>` (fCV) set to ``"4.0"``
+   or earlier, the *total size* of an index entry, which can include
+   structural overhead depending on the BSON type, must be *less than*
+   1024 bytes.
 
    .. COMMENT refer to src/mongo/db/structure/btree/key.cpp (KeyV1Owned::KeyV1Owned)
 
    .. |limit| replace:: :limit:`index key limit <Index Key Limit>`
 
-   .. versionchanged:: 2.6
-
-      .. include:: /includes/list-index-field-limit-behaviors.rst
+   .. include:: /includes/list-index-field-limit-behaviors.rst
 
 .. _limit-number-of-indexes-per-collection:
 .. limit:: Number of Indexes per Collection
diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt
@@ -540,17 +540,25 @@ General Parameters
 
 .. parameter:: failIndexKeyTooLong
 
-   .. versionadded:: 2.6
-
    |mongod-only|
 
-   In MongoDB 2.6, if you attempt to insert or update a document so
-   that the value of an indexed field is longer than the
-   :limit:`Index Key Length Limit <Index Key Limit>`, the operation
-   will fail and return an error to the client. In previous versions
-   of MongoDB, these operations would successfully insert or modify a
-   document but the index or indexes would not include references to
-   the document.
+   .. versionchanged:: 4.2
+
+      - MongoDB removes the :limit:`Index Key Limit` for
+        :ref:`featureCompatibilityVersion <view-fcv>` (fCV) set to
+        ``"4.2"`` or greater.
+
+      - In concert with the removal of the limit,
+        :parameter:`failIndexTooLong` only applies for MongoDB 2.6
+        through MongoDB versions with :ref:`featureCompatibilityVersion
+        <view-fcv>` (fCV) set to ``"4.0"`` or earlier.
+
+   For MongoDB 2.6 through MongoDB versions with
+   ``featureCompatibilityVersion`` (fCV) set to ``"4.0"`` or earlier,
+   :limit:`Index Key Length Limit <Index Key Limit>` applies. If you
+   attempt to insert or update a document whose index field exceeds
+   the :limit:`Index Key Length Limit <Index Key Limit>`, the operation
+   will fail and return an error to the client.
 
    To avoid this issue, consider using :doc:`hashed indexes
    </core/index-hashed>` or indexing a computed value. If you have an
@@ -568,9 +576,7 @@ General Parameters
       documents whose indexed fields exceed the
       :limit:`Index Key Length Limit <Index Key Limit>`.
 
-   :parameter:`failIndexKeyTooLong` defaults to ``true``. When
-   ``false``, a 2.6 :binary:`~bin.mongod` instance will provide the 2.4
-   behavior.
+   :parameter:`failIndexKeyTooLong` defaults to ``true``.
 
    Issue the following command to disable the index key length
    validation:
diff --git a/source/reference/program/mongorestore.txt b/source/reference/program/mongorestore.txt
@@ -50,17 +50,17 @@ Rebuild Indexes
 
 .. note::
 
-   Starting in MongoDB 2.6, creating indexes will :ref:`error if an
+   For MongoDB 2.6 through MongoDB versions with
+   ``featureCompatibilityVersion`` (fCV) set to ``"4.0"`` or earlier,
+   creating indexes will :limit:`error if an
    index key in an existing document exceeds the limit
-   <2.6-index-key-length-incompatibility>`. See
-   :ref:`2.6-index-key-length-incompatibility` for more information and
-   solution.
-
-   If you have an existing data set that violates this limit but want
-   to resolve the index issue after restoring the data, you can disable
-   the default index key length validation on the target database by
-   setting the :program:`mongod` instance's
-   :parameter:`failIndexKeyTooLong` parameter to false.
+   <Index Key Limit>`. 
+
+   To avoid this issue, consider using hashed indexes or indexing a
+   computed value instead. If you want to resolve the index issue after
+   restoring the data, you can disable the default index key length
+   validation on the target database by setting the :program:`mongod`
+   instance's :parameter:`failIndexKeyTooLong` parameter to false.
 
 Version Compatibility
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/source/release-notes/4.2-compatibility.txt b/source/release-notes/4.2-compatibility.txt
@@ -227,8 +227,15 @@ General Changes
            
 .. _4.2-compatibility-enabled:
 
-4.2 Feature Compatibilitity
----------------------------
+4.2 Feature Compatibility
+-------------------------
 
 Some features in 4.2 require not just the 4.2 binaries but the
-``featureCompatibilityVersion`` set to 4.2. These features include:
+:ref:`featureCompatibilityVersion <view-fcv>` (fCV) set to 4.2. These
+features include:
+
+- Removal of :limit:`Index Key Limit` for MongoDB versions with fCV set
+  to 4.2+. In concert with the removal of this limit, the
+  :parameter:`failIndexKeyTooLong` parameter has no effect for MongoDB
+  versions with fCV set to 4.2+ and only applies for MongoDB 2.6
+  through MongoDB versions with fCV set to ``"4.0"`` or earlier.
diff --git a/source/release-notes/4.2-downgrade-replica-set.txt b/source/release-notes/4.2-downgrade-replica-set.txt
@@ -80,6 +80,11 @@ value, see :ref:`view-fcv`.
 2. Remove Backwards Incompatible Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Index Key Size
+``````````````
+
+.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+
 
 Procedure
 ---------
diff --git a/source/release-notes/4.2-downgrade-sharded-cluster.txt b/source/release-notes/4.2-downgrade-sharded-cluster.txt
@@ -78,6 +78,11 @@ value, see :ref:`view-fcv`.
 2. Remove Backwards Incompatible Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Index Key Size
+``````````````
+
+.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+
 
 Procedure
 ---------
diff --git a/source/release-notes/4.2-downgrade-standalone.txt b/source/release-notes/4.2-downgrade-standalone.txt
@@ -52,6 +52,11 @@ versions as outlined below. These steps are necessary only if
 2. Remove Backwards Incompatible Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Index Key Size
+``````````````
+
+.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+
 
 Procedure
 ---------
diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt
@@ -247,7 +247,6 @@ this option, you can start a change stream from an
 missed notifications after the previous stream was invalidated.
 
 
-
 General Improvements
 --------------------
 
@@ -258,6 +257,16 @@ MongoDB 4.2 adds the :option:`--outputConfig <mongod --outputConfig>` option for
 :binary:`~bin.mongod` and :binary:`~bin.mongos`, which outputs the resolved 
 YAML configuration document to ``stdout`` and halts the server instance.
 
+Remove Index Key Size Limit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 4.2, for :ref:`featureCompatibilityVersion
+<view-fcv>` set to ``"4.2"`` or greater, MongoDB removes the
+:limit:`Index Key Limit`. For fCV set to ``"4.0"``, the limit still
+applies.
+
+.. seealso:: :ref:`4.2-compatibility-enabled`
+
 Changes Affecting Compatibility
 -------------------------------
 
