DOCS-15586 expireAfterSeconds (#2136) (#2203)

* DOCS-15586 expireAfterSeconds

* DOCS-15586 expireAfterSeconds

* Review feedback

* Review feedback

* Upstream doc updated

* Staging updates

* Review feedback

Author: Dave Cuthbert

source/includes/indexes/expireAfterSeconds-config-option.rst

@@ -0,0 +1,4 @@
+Optional. Specifies a value, in seconds, as a time to live (:term:`TTL`)
+to control how long MongoDB retains documents in this collection. This
+option only applies to :term:`TTL` indexes. See :ref:`ttl-collections`
+for more information. 

source/includes/indexes/expireAfterSeconds-versions.rst

@@ -0,0 +1,2 @@
+Starting in MongoDB 5.0.14 (and 6.0.2), the server will not use TTL
+indexes that have ``expireAfterSeconds`` set to ``NaN``.

source/includes/indexes/expireAfterSeconds-warning.rst

@@ -0,0 +1,3 @@
+If you use TTL indexes created before MongoDB 5.0, or if you want to
+sync data created in MongDB 5.0 with a pre-5.0 installation, see
+:ref:`expireData-warning` to avoid misconfiguration issues.

source/reference/command/collMod.txt

@@ -87,6 +87,8 @@ Index Options
           Modifying the index option ``expireAfterSeconds`` resets the
           :pipeline:`$indexStats` for the index.
 
+          .. include:: /includes/indexes/expireAfterSeconds-warning.rst
+
       * - ``hidden``
         - A boolean that determines whether the index is :ref:`hidden
           <index-type-hidden>` or not from the query planner.

source/reference/command/createIndexes.txt

@@ -312,12 +312,11 @@ Each document in the ``indexes`` array can take the following fields:
    * - ``expireAfterSeconds``
 
      - integer
- 
-     - Optional. Specifies a value, in seconds, as a :term:`TTL` to control how long
-       MongoDB retains documents in this collection. See
-       :doc:`/tutorial/expire-data` for more information on this
-       functionality. This applies only to :term:`TTL` indexes.
-  
+
+     - .. include:: /includes/indexes/expireAfterSeconds-config-option.rst
+       
+       .. include:: /includes/indexes/expireAfterSeconds-warning.rst
+
    * - :ref:`hidden <cmd-createIndexes-hidden>`
 
      - boolean

source/reference/method/db.collection.createIndex.txt

@@ -268,12 +268,10 @@ otherwise specified:
 
      - integer
 
-     - Optional. Specifies a value, in seconds, as a :term:`TTL` to control how long
-       MongoDB retains documents in this collection. See
-       :doc:`/tutorial/expire-data` for more information on this
-       functionality. This applies only to :term:`TTL` indexes.
-       
+     - .. include:: /includes/indexes/expireAfterSeconds-config-option.rst
 
+       .. include:: /includes/indexes/expireAfterSeconds-warning.rst
+
 
    * - :ref:`hidden <method-createIndex-hidden>`
 

source/reference/method/db.collection.createIndexes.txt

@@ -305,12 +305,10 @@ otherwise specified:
 
      - integer
 
-     - Optional. Specifies a value, in seconds, as a :term:`TTL` to control how long
-       MongoDB retains documents in this collection. See
-       :doc:`/tutorial/expire-data` for more information on this
-       functionality. This applies only to :term:`TTL` indexes.
-       
+     - .. include:: /includes/indexes/expireAfterSeconds-config-option.rst
 
+       .. include:: /includes/indexes/expireAfterSeconds-warning.rst
+
    * - :ref:`hidden <method-createIndexes-hidden>`
 
      - boolean

source/release-notes/5.0-compatibility.txt

@@ -141,17 +141,21 @@ when a :ref:`resharding operation <sharding-resharding>` is taking place.
 TTL ``expireAfterSeconds`` Behavior When Set to ``NaN``
 -------------------------------------------------------
 
-Setting :ref:`TTL <ttl-collections>` ``expireAfterSeconds`` to ``NaN`` 
-experiences a behavior change from MongoDB 4.4 to MongoDB 5.0 that 
-affects: 
+Starting in MongoDB 5.0, :ref:`TTL <ttl-collections>` indexes with
+``expireAfterSeconds`` set to ``NaN`` :ref:`experience a behavior change
+<expireData-warning>` compared to earlier versions.
+
+The behavior change affects: 
 
 - direct upgrades
 - initial sync from earlier versions 
-- :binary:`~bin.mongorestore` from earlier versions. 
+- :binary:`~bin.mongorestore` from earlier versions
+
+Performing any of those actions causes an ``expireAfterSeconds`` value
+of  ``NaN`` to be treated as an ``expireAfterSeconds`` of ``0``. As a
+result, documents may expire immediately. 
 
-Performing any of those actions causes an ``expireAfterSeconds`` of 
-``NaN`` to be treated as an ``expireAfterSeconds`` of ``0``. Immediate 
-document expiration may occur as a result.
+.. include:: /includes/indexes/expireAfterSeconds-versions.rst
 
 Shell Changes
 -------------

source/tutorial/expire-data.txt

@@ -31,7 +31,7 @@ collection.
 Procedures
 ----------
 
-To create a :doc:`TTL index </core/index-ttl>`, use the
+To create a :ref:`TTL index <index-feature-ttl>`, use the
 :method:`db.collection.createIndex()` method with the
 ``expireAfterSeconds`` option on a field whose value is either a
 :ref:`date <document-bson-type-date>` or an array that contains
@@ -47,7 +47,7 @@ You can modify the ``expireAfterSeconds`` of an existing TTL index
 using the :dbcommand:`collMod` command.
 
 Expire Documents after a Specified Number of Seconds
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
 
 To expire data after a specified number of seconds has passed since the
 indexed field, create a TTL index on a field that holds values of BSON
@@ -88,7 +88,7 @@ specified in ``expireAfterSeconds``.
    ``expireAfterSeconds``.
 
 Expire Documents at a Specific Clock Time
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 To expire documents at a specific clock time, begin by creating a TTL
 index on a field that holds values of BSON date type or an array of
@@ -125,3 +125,91 @@ number of seconds specified in ``expireAfterSeconds``, i.e. ``0``
 seconds older in this case. As such, the data expires at the specified
 ``expireAt`` value.
 
+.. _expireData-warning:
+
+Indexes Configured Using NaN
+----------------------------
+
+.. warning::
+ 
+   Possible Data Loss
+
+   When a TTL index has ``expireAfterSeconds`` set to ``NaN``, upgrade,
+   downgrade, and certain syncing operations can lead to unexpected
+   behavior and possible data loss.
+
+Do not set ``expireAfterSeconds`` to ``NaN`` in your TTL index
+configuration.
+
+Prior to MongoDB 5.0, when a TTL index has ``expireAfterSeconds`` set to
+``NaN``, MongoDB logs an error and does not remove any records.
+
+From MongoDB 5.0.0 - 5.0.13 (and 6.0.0 - 6.0.1), ``NaN`` is treated as
+``0``. If a TTL index is configured with ``expireAfterSeconds`` set to
+``NaN``, all TTL-indexed documents expire immediately.
+
+.. include:: /includes/indexes/expireAfterSeconds-versions.rst
+
+However, there are still some situations which may result in unexpected
+behavior. Documents may expire:
+
+- During an initial sync to an earlier version from MongoDB 5.0.0 -
+  5.0.13 (or 6.0.0 - 6.0.1).
+- When upgrading from an earlier version to MongoDB 5.0.0 - 5.0.13.
+- When restoring a collection from a pre-5.0 :binary:`~bin.mongodump`
+  into a MongoDB 5.0.0 - 5.0.13 (or 6.0.0 - 6.0.1) instance.
+
+To avoid problems, either drop or correct any misconfigured TTL indexes.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Identify misconfigured indexes.
+    
+      Run the following script in the :binary:`mongosh` shell. The
+      script does not work in the legacy ``mongo`` shell.
+
+      .. code-block:: javascript
+
+         function getNaNIndexes() {
+           const nan_index = [];
+          
+           const dbs = db.adminCommand({ listDatabases: 1 }).databases;
+          
+           dbs.forEach((d) => {
+             const listCollCursor = db
+               .getSiblingDB(d.name)
+               .runCommand({ listCollections: 1 }).cursor;
+          
+             const collDetails = {
+               db: listCollCursor.ns.split(".$cmd")[0],
+               colls: listCollCursor.firstBatch.map((c) => c.name),
+             };
+          
+             collDetails.colls.forEach((c) =>
+               db
+                 .getSiblingDB(collDetails.db)
+                 .getCollection(c)
+                 .getIndexes()
+                 .forEach((entry) => {
+                   if (Object.is(entry.expireAfterSeconds, NaN)) {
+                     nan_index.push({ ns: `${collDetails.db}.${c}`, index: entry });
+                   }
+                 })
+             );
+           });
+          
+           return nan_index;
+         };
+
+         getNaNIndexes();
+
+   .. step:: Correct misconfigured indexes.
+ 
+      Use the :dbcommand:`collMod` command to update any misconfigured
+      ``expireAfterSeconds`` values that the script found. 
+      
+      As an alternative, you can :dbcommand:`drop <dropIndexes>` any
+      misconfigured TTL indexes and recreate them later using the
+      :dbcommand:`createIndexes` command. 
+