DOCS-11906: 4.2 fcv index name limit

kay-kim · kay-kim · commit a84f40e881f8 · 2018-10-11T16:57:53.000-04:00
diff --git a/source/includes/apiargs-method-db.collection.createIndex-options-param.yaml b/source/includes/apiargs-method-db.collection.createIndex-options-param.yaml
@@ -35,9 +35,11 @@ description: |
   The name of the index. If unspecified, MongoDB generates an index name
   by concatenating the names of the indexed fields and the sort order.
 
-  Whether user specified or MongoDB generated, index names including
-  their full namespace (i.e. ``database.collection``) cannot be longer
-  than the :limit:`Index Name Limit <Index Name Length>`.
+  .. admonition:: Changed in MongoDB 4.2
+     :class: note
+
+     .. include:: /includes/extracts/4.2-changes-index-names.rst
+
 interface: method
 name: name
 operation: db.collection.createIndex
diff --git a/source/includes/extracts-4.2-changes.yaml b/source/includes/extracts-4.2-changes.yaml
@@ -0,0 +1,12 @@
+ref: 4.2-changes-index-names
+content: |
+
+     Starting in version 4.2, for :ref:`featureCompatibilityVersion
+     <view-fcv>` set to ``"4.2"`` or greater, MongoDB removes the
+     :limit:`Index Name Length` limit of 127 byte maximum. In previous
+     versions or MongoDB versions with
+     :ref:`featureCompatibilityVersion <view-fcv>` (fCV) set to
+     ``"4.0"``, index names must fall within the
+     :limit:`limit <Index Name Length>`.
+...
+
diff --git a/source/includes/extracts-4.2-downgrade-fcv.yaml b/source/includes/extracts-4.2-downgrade-fcv.yaml
@@ -1,18 +1,38 @@
 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. 
+   Starting in MongoDB 4.2, for ``featureCompatibilityVersion`` (fCV)
+   set to ``"4.2"`` or greater, MongoDB removes the :limit:`Index Key
+   Limit`. For fCV 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"``,
+   Limit` once fCV 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
+   the problem. However, with :parameter:`failIndexKeyTooLong` set to
    ``false``, queries that use these indexes can return incomplete
    results.
+---
+ref: 4.2-downgrade-fcv-index-name
+content: |
+
+   Starting in MongoDB 4.2, for ``featureCompatibilityVersion`` (fCV)
+   set to ``"4.2"`` or greater, MongoDB removes the :limit:`Index Key
+   Limit`. For fCV set to ``"4.0"``, the limit still applies.
+
+   If you have an index with a name that exceeds the :limit:`Index Name
+   Length` once fCV is set to ``"4.0"``,
+   drop and recreate the index with a shorter name.
+
+   .. code-block:: javascript
+
+      db.collection.dropIndex( <name | index specification> )
+
+      db.collection.createIndex(
+         { <index specification> },
+         { name: <shorter name> }
+      }
    
+   .. see:: :method:`db.collection.dropIndex()` and :method:`db.collection.createIndex()`
 ...
diff --git a/source/reference/command/createIndexes.txt b/source/reference/command/createIndexes.txt
@@ -70,8 +70,10 @@ Considerations
 Index Names
 ~~~~~~~~~~~
 
-An index name, including the :term:`namespace`, cannot be longer than
-the :ref:`Index Name Length <limit-index-name-length>` limit.
+.. admonition:: Changed in MongoDB 4.2
+   :class: note
+
+   .. include:: /includes/extracts/4.2-changes-index-names.rst
 
 Replica Sets and Sharded Clusters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/source/reference/limits.txt b/source/reference/limits.txt
@@ -113,19 +113,19 @@ Indexes
 .. _limit-index-size:
 .. limit:: Index Key Limit
 
-   .. versionchanged:: 4.2
 
-      MongoDB removes the :limit:`Index Key Limit` for fCV set to
-      ``"4.2"`` or greater.
+   .. admonition:: Changed in version 4.2
+      :class: note
+
+      Starting in version 4.2, MongoDB removes the :limit:`Index Key
+      Limit` for :ref:`featureCompatibilityVersion <view-fcv>` (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
+   For MongoDB 2.6 through MongoDB versions with 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>`
 
    .. include:: /includes/list-index-field-limit-behaviors.rst
@@ -138,14 +138,24 @@ Indexes
 .. _limit-index-name-length:
 .. limit:: Index Name Length
 
-   Fully qualified index names, which includes the namespace and the dot
-   separators (i.e. ``<database name>.<collection name>.$<index name>``),
-   cannot be longer than 128 characters.
+   .. admonition:: Changed in version 4.2
+      :class: note
+
+      Starting in version 4.2, MongoDB removes the :limit:`Index Key
+      Limit` for MongoDB versions with
+      :ref:`featureCompatibilityVersion <view-fcv>` (fCV) set to
+      ``"4.2"`` or greater.
+
+   In previous versions of MongoDB or MongoDB versions with fCV set
+   to ``"4.0"`` or earlier, fully qualified index names, which include
+   the namespace and the dot separators (i.e. ``<database
+   name>.<collection name>.$<index name>``), cannot be longer than 127
+   bytes.
 
    By default, ``<index name>`` is the concatenation of the field names
-   and index type. You can explicitly specify the ``<index name>`` to the
-   :method:`~db.collection.createIndex()` method to ensure that the fully
-   qualified index name does not exceed the limit.
+   and index type. You can explicitly specify the ``<index name>`` to
+   the :method:`~db.collection.createIndex()` method to ensure that the
+   fully qualified index name does not exceed the limit.
 
 .. limit:: Number of Indexed Fields in a Compound Index
 
diff --git a/source/release-notes/4.2-compatibility.txt b/source/release-notes/4.2-compatibility.txt
@@ -239,3 +239,6 @@ features include:
   :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.
+
+- Removal of :limit:`Index Name Length` for MongoDB versions with fCV
+  set to 4.2+.
diff --git a/source/release-notes/4.2-downgrade-replica-set.txt b/source/release-notes/4.2-downgrade-replica-set.txt
@@ -41,8 +41,8 @@ versions as generally outlined below. These steps are necessary only if
 
 .. _4.2-downgrade-feature-compatibility-rs:
 
-1. Downgrade Feature Compatibility Version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Downgrade Feature Compatibility Version (fCV)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. tip::
 
@@ -80,11 +80,22 @@ value, see :ref:`view-fcv`.
 2. Remove Backwards Incompatible Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Remove all persisted 4.2 features that are :ref:`incompatible with 4.0
+<4.2-compatibility-enabled>`.
+
 Index Key Size
 ``````````````
 
-.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+.. container::
+
+   .. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+
+Index Name Length
+`````````````````
+
+.. container::
 
+   .. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst
 
 Procedure
 ---------
diff --git a/source/release-notes/4.2-downgrade-sharded-cluster.txt b/source/release-notes/4.2-downgrade-sharded-cluster.txt
@@ -30,18 +30,18 @@ Create Backup
 Prerequisites
 -------------
 
-Before downgrading the binaries, you must downgrade the feature
-compatibility version and remove any |newversion| features :ref:`incompatible
-<4.2-compatibility-enabled>` with |oldversion| or earlier versions as outlined
-below. These steps are necessary only if
-``featureCompatibilityVersion`` has ever been set to ``"4.2"``.
+Before downgrading the binaries, you must downgrade the
+``featureCompatibilityVersion`` (fCV) and remove any |newversion|
+features :ref:`incompatible <4.2-compatibility-enabled>` with
+|oldversion| or earlier versions as outlined below. These steps are
+necessary only if fCV has ever been set to ``"4.2"``.
 
 .. |target| replace:: :binary:`~bin.mongos` instance
 
 .. _4.2-downgrade-feature-compatibility-sharded-cluster:
 
-1. Downgrade Feature Compatibility Version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Downgrade Feature Compatibility Version (fCV)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 #. Connect a :binary:`~bin.mongo` shell to the |target|.
 
@@ -78,11 +78,22 @@ value, see :ref:`view-fcv`.
 2. Remove Backwards Incompatible Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Remove all persisted 4.2 features that are :ref:`incompatible with 4.0
+<4.2-compatibility-enabled>`.
+
 Index Key Size
 ``````````````
 
-.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+.. container::
+
+   .. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+
+Index Name Length
+`````````````````
+
+.. container::
 
+   .. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst
 
 Procedure
 ---------
diff --git a/source/release-notes/4.2-downgrade-standalone.txt b/source/release-notes/4.2-downgrade-standalone.txt
@@ -32,18 +32,18 @@ Create Backup
 Prerequisites
 -------------
 
-Before downgrading the binaries, you must downgrade the feature
-compatibility version and remove any |newversion| features
-:ref:`incompatible <4.2-compatibility-enabled>` with |oldversion|
-versions as outlined below. These steps are necessary only if
-``featureCompatibilityVersion`` has ever been set to ``"4.2"``.
+Before downgrading the binaries, you must downgrade the
+``featureCompatibilityVersion`` (fCV) and remove any |newversion|
+features :ref:`incompatible <4.2-compatibility-enabled>` with
+|oldversion| versions as outlined below. These steps are necessary only
+if fCV has ever been set to ``"4.2"``.
 
 .. |target| replace:: :binary:`~bin.mongod` instance
 
 .. _4.2-downgrade-feature-compatibility-standalone:
 
-1. Downgrade Feature Compatibility Version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Downgrade Feature Compatibility Version (fCV)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 #. Connect a :binary:`~bin.mongo` shell to the |target|.
 
@@ -52,11 +52,22 @@ versions as outlined below. These steps are necessary only if
 2. Remove Backwards Incompatible Persisted Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Remove all persisted 4.2 features that are :ref:`incompatible with 4.0
+<4.2-compatibility-enabled>`.
+
 Index Key Size
 ``````````````
 
-.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+.. container::
+
+   .. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst
+
+Index Name Length
+`````````````````
+
+.. container::
 
+   .. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst
 
 Procedure
 ---------
diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt
@@ -265,6 +265,11 @@ Starting in MongoDB 4.2, for :ref:`featureCompatibilityVersion
 :limit:`Index Key Limit`. For fCV set to ``"4.0"``, the limit still
 applies.
 
+Remove Index Name Length Limit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/4.2-changes-index-names.rst
+
 .. seealso:: :ref:`4.2-compatibility-enabled`
 
 Externally Sourced Values for Configuration Files
diff --git a/source/tutorial/avoid-text-index-name-limit.txt b/source/tutorial/avoid-text-index-name-limit.txt
@@ -10,6 +10,11 @@ Specify Name for ``text`` Index
    :depth: 1
    :class: singlecol
 
+.. admonition:: Changed in MongoDB 4.2
+   :class: note
+
+   .. include:: /includes/extracts/4.2-changes-index-names.rst
+
 The default name for the index consists of each indexed field name
 concatenated with ``_text``. For example, the following command creates
 a ``text`` index on the fields ``content``, ``users.comments``, and
@@ -31,15 +36,11 @@ The default name for the index is:
 
    "content_text_users.comments_text_users.profiles_text"
 
-The ``text`` index, like other indexes, must fall within the
-:limit:`index name length limit <Index Name Length>`.
-
 Specify a Name for ``text`` Index
 ---------------------------------
 
-To avoid creating an index with a name that exceeds the :limit:`index
-name length limit <Index Name Length>`, you can pass the ``name``
-option to the :method:`db.collection.createIndex()` method:
+You can pass the ``name`` option to the
+:method:`db.collection.createIndex()` method:
 
 .. code-block:: javascript
 
