Docsp 28726 backport (#3145)

* Initital cleanup of deprecated version references

* Typo fix

* Version number cleanup

* Rendering test

* Added expiration behavior for time series collections

* Added partial index limitations

* Clarified partial TTL index behavior with time series collections

* Internal review feedback

* Removed note in restrictions topic aboout TTL indexes being unsupported

* External PR feedback

Author: nvillahermosa-mdb

source/core/index-partial.txt

@@ -39,7 +39,9 @@ indexes only the documents with a ``rating`` field greater than 5.
    )
 
 You can specify a ``partialFilterExpression`` option for all MongoDB
-:ref:`index types <index-types>`.
+:ref:`index types <index-types>`. When specifying a
+``partialFilterExpression`` for a TTL index on a time series collection,
+you can only filter on the collection ``metaField``.
 
 .. seealso::
 

source/core/index-ttl.txt

@@ -1,5 +1,3 @@
-
-
 .. _index-feature-ttl:
 
 ===========
@@ -25,26 +23,69 @@ TTL Indexes
 
 TTL indexes are special single-field indexes that MongoDB can use to
 automatically remove documents from a collection after a certain amount
-of time or at a specific clock time. Data expiration is useful for certain types of information
-like machine generated event data, logs, and session information that
-only need to persist in a database for a finite amount of time.
+of time or at a specific clock time. Data expiration is useful for
+certain types of information like machine generated event data, logs,
+and session information that only need to persist in a database for a 
+finite amount of time.
 
 Create a TTL Index
 ------------------
 
 To create a TTL index, use the :method:`~db.collection.createIndex()`
 method on a field whose value is either a :ref:`date
-<document-bson-type-date>` or an array that contains :ref:`date values
-<document-bson-type-date>`, and specify the ``expireAfterSeconds``
-option with the desired TTL value in seconds.
+<document-bson-type-date>` or an array that contains date values, then specify the ``expireAfterSeconds`` option with the desired TTL value in
+seconds. 
 
 For example, to create a TTL index on the ``lastModifiedDate`` field of
-the ``eventlog`` collection, with a TTL value of ``3600`` seconds, use
+the ``eventlog`` collection with a TTL value of ``3600`` seconds, use
 the following operation in :binary:`~bin.mongosh`:
 
 .. code-block:: javascript
 
-   db.eventlog.createIndex( { "lastModifiedDate": 1 }, { expireAfterSeconds: 3600 } )
+   db.eventlog.createIndex( { "lastModifiedDate": 1 }, {
+   expireAfterSeconds: 3600 } )
+   
+Starting in MongoDB 6.3, you can create partial TTL indexes on 
+:ref:`time series collections <manual-timeseries-landing>`. These
+indexes use the collection ``timeField`` as the key field, and require a
+:ref:`partial filter expression <index-type-partial>` on the  ``metaField``.
+
+Time series collections include an optional ``expireAfterSeconds``
+field. If you do not set it, a TTL index with a
+``partialFilterExpression`` lets you set an expiration period for
+documents that match the filter. If you do set ``expireAfterSeconds``,
+a partial TTL index lets you set a different, shorter expiration period
+for matching documents. You can only create a ``partialFilterExpression`` on the ``metaField``.
+
+.. important::
+
+   If the ``expireAfterSeconds`` value of the collection is lower than
+   the ``expireAfterSeconds`` of the partial TTL index, the collection
+   deletes documents after the shorter time, so the TTL index has no effect.
+
+This weather data time series collection deletes documents after 24 hours:
+
+.. code-block:: javascript
+
+   db.createCollection(
+       "weather24h",
+       {
+          timeseries: {
+             timeField: "timestamp",
+             metaField: "sensor",
+             granularity: "hours"
+          },
+          expireAfterSeconds: 86400})
+
+This TTL index deletes documents from the MongoDB NYC
+headquarters weather sensor after 1 hour, instead of 24 hours:
+
+.. code-block:: javascript
+
+   db.eventlog.createIndex( 
+     { "timestamp": 1 },
+     { partialFilterExpression: { "sensor": { $eq: "40.761873, -73.984287" } } },
+     { expireAfterSeconds: 3600 } )
 
 .. _convert-non-ttl-single-field-index-into-ttl:
 
@@ -118,12 +159,19 @@ Expiration of Data
 
 TTL indexes expire documents after the specified number of seconds has
 passed since the indexed field value; i.e. the expiration threshold is
-the indexed field value plus the specified number of seconds.
+the indexed field value plus the specified number of seconds. 
 
 If the field is an array, and there are multiple date values in the
 index, MongoDB uses *lowest* (i.e. earliest) date value in the array to
 calculate the expiration threshold.
 
+For time series collections, TTL indexes also remove a bucket of data
+when all documents inside it expire. This is equal to the upper
+timestamp limit of the bucket, plus the ``expireAfterSeconds`` value.
+For example, if a bucket covers data up until ``2023-03-27T18:29:59Z``
+and ``expireAfterSeconds`` is 300, the TTL index expires the
+bucket after ``2023-03-27T18:34:59Z``.
+
 If the indexed field in a document is not a
 :ref:`date <document-bson-type-date>` or an array that holds one or
 more date values, the document will not expire.
@@ -146,9 +194,9 @@ output of :method:`db.currentOp()` or in the data collected by the
 Timing of the Delete Operation
 ``````````````````````````````
 
-MongoDB begins removing expired documents as soon as the index
-finishes building on the :term:`primary`. For more information on the
-index build process, see :ref:`index-operations`.
+MongoDB begins removing expired documents or time series buckets as soon
+as the index finishes building on the :term:`primary`. For more
+information on the index build process, see :ref:`index-operations`.
 
 .. include:: /includes/fact-ttl-collection-background-timing.rst
 
@@ -177,10 +225,8 @@ Restrictions
 - You cannot create a TTL index on a :ref:`capped collection
   <manual-capped-collection>`.
 
-- You cannot create a TTL index on a :doc:`time series collection
-  </core/timeseries-collections>`. Similar functionality is provided
-  through :ref:`automatic removal on time series collections
-  <manual-timeseries-automatic-removal>` instead.
+- You can only create TTL indexes for a :ref:`time series collection
+  <manual-timeseries-landing>` on the collection ``timeField``.
 
 - You cannot use :method:`~db.collection.createIndex()` to change the
   value of ``expireAfterSeconds`` of an existing index. Instead use the

source/core/timeseries/timeseries-limitations.txt

@@ -93,10 +93,6 @@ These index types aren't supported:
 - :ref:`2d indexes <2d-index>`
 - :ref:`Unique indexes <index-type-unique>`
 
-The :ref:`TTL <index-feature-ttl>` index property is not supported. For
-TTL deletion, use :ref:`expireAfterSeconds
-<db.createCollection.expireAfterSeconds>`.
-
 You can only use the :ref:`multikey index <index-type-multikey>` type on
 the ``metaField``.
 

source/includes/fact-ttl-collection-background-timing.rst

@@ -1,6 +1,6 @@
-The TTL index does not guarantee that expired data will be deleted
-immediately upon expiration. There may be a delay between the time that a
-document expires and the time that MongoDB removes the document from
+The TTL index does not guarantee that expired data is deleted
+immediately upon expiration. There may be a delay between the time that
+a document expires and the time that MongoDB removes the document from
 the database.
 
 The background task that removes expired documents runs *every 60

source/indexes.txt

@@ -40,15 +40,14 @@ MongoDB creates a :ref:`unique index <index-type-unique>` on the
 :ref:`_id <document-id-field>` field during the creation of a
 collection. The ``_id`` index prevents clients from inserting two
 documents with the same value for the ``_id`` field. You cannot drop
-this index on the ``_id`` field.
+this index.
 
 .. note::
 
    In :term:`sharded clusters <sharded cluster>`, if you do *not* use
    the ``_id`` field as the :term:`shard key`, then your application
-   **must** ensure the uniqueness of the values in the ``_id`` field
-   to prevent errors.  This is most-often done by using a standard
-   auto-generated :term:`ObjectId`.
+   **must** ensure the uniqueness of the values in the ``_id`` field.
+   You can do this by using a field with an auto-generated :term:`ObjectId`.
 
 Create an Index
 ---------------
@@ -232,23 +231,24 @@ Sparse Indexes
 ~~~~~~~~~~~~~~
 
 The :ref:`sparse <index-type-sparse>` property of an index ensures
-that the index only contain entries for documents that have the indexed
+that the index only contains entries for documents that have the indexed
 field. The index skips documents that *do not* have the indexed field.
 
-You can combine the sparse index option with the unique index option
-to prevent inserting documents that have duplicate values for the indexed
-field(s) and skip indexing documents that lack the indexed field(s).
+You can combine the ``sparse`` index option with the ``unique`` index
+option to prevent inserting documents that have duplicate values for the
+indexed field(s) and skip indexing documents that lack the indexed
+field(s).
 
 .. _ttl-index:
 
 TTL Indexes
 ~~~~~~~~~~~
 
-:ref:`TTL indexes <index-feature-ttl>` are special indexes that MongoDB
-can use to automatically remove documents from a collection after a
-certain amount of time. This is ideal for certain types of information
-like machine generated event data, logs, and session information that
-only need to persist in a database for a finite amount of time.
+:ref:`TTL indexes <index-feature-ttl>` automatically remove documents
+from a collection after a certain amount of time. This is ideal for
+certain types of information like machine generated event data, logs,
+and session information that only need to persist in a database for a
+finite amount of time.
 
 See: :doc:`/tutorial/expire-data` for implementation instructions.