diff --git a/source/core/index-ttl.txt b/source/core/index-ttl.txt index c21b185f467..103bea606dd 100644 --- a/source/core/index-ttl.txt +++ b/source/core/index-ttl.txt @@ -29,6 +29,9 @@ of time or at a specific clock time. Data expiration is useful for certain types 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 ` or an array that contains :ref:`date values @@ -43,6 +46,70 @@ the following operation in :binary:`~bin.mongosh`: db.eventlog.createIndex( { "lastModifiedDate": 1 }, { expireAfterSeconds: 3600 } ) +.. _convert-non-ttl-single-field-index-into-ttl: + +Convert a non-TTL single-field Index into a TTL Index +----------------------------------------------------- + +Starting in MongoDB 5.1, you can add the ``expireAfterSeconds`` option +to an existing single-field index. To change a non-TTL single-field +index to a TTL index, use the :dbcommand:`collMod` database command: + +.. code-block:: javascript + + db.runCommand({ + "collMod": , + "index": { + "keyPattern": , + "expireAfterSeconds": + } + }) + +The following example converts a non-TTL single-field index with the +pattern ``{ "lastModifiedDate": 1 }`` into a TTL index: + +.. code-block:: javascript + + db.runCommand({ + "collMod": "tickets", + "index": { + "keyPattern": { "lastModifiedDate": 1 }, + "expireAfterSeconds": 100 + } + }) + +.. _change-ttl-expireafterseconds-value: + +Change the ``expireAfterSeconds`` value for a TTL Index +------------------------------------------------------- + +To change the ``expireAfterSeconds`` value for a TTL Index, use the +:dbcommand:`collMod` database command: + +.. code-block:: javascript + + db.runCommand({ + "collMod": , + "index": { + "keyPattern": , + "expireAfterSeconds": + } + }) + +The following example changes the ``expireAfterSeconds`` value for an +index with the pattern ``{ "lastModifiedDate": 1 }`` on the ``tickets`` +collection: + +.. code-block:: javascript + + db.runCommand({ + "collMod": "tickets", + "index": { + "keyPattern": { "lastModifiedDate": 1 }, + "expireAfterSeconds": 100 + } + }) + Behavior -------- @@ -99,7 +166,7 @@ A TTL index supports queries in the same way non-TTL indexes do. Restrictions ------------ -- TTL indexes are a single-field indexes. :ref:`Compound indexes +- TTL indexes are single-field indexes. :ref:`Compound indexes ` do not support TTL and ignore the ``expireAfterSeconds`` option. @@ -116,17 +183,16 @@ Restrictions - You cannot use :method:`~db.collection.createIndex()` to change the value of ``expireAfterSeconds`` of an existing index. Instead use the - :dbcommand:`collMod` database command in conjunction with the - :collflag:`index` collection flag. Otherwise, to change the value of - the option of an existing index, you must drop the index first and - recreate. + :dbcommand:`collMod` database command. See + :ref:`change-ttl-expireafterseconds-value`. - If a non-TTL single-field index already exists for a field, you cannot create a TTL index on the same field since you cannot create indexes that have the same key specification and differ only by the - options. To change a non-TTL single-field index to a TTL index, you - must drop the index first and recreate with the - ``expireAfterSeconds`` option. + options. To :ref:`change a non-TTL single-field index to a TTL index + `, use the + :dbcommand:`collMod` database command. + .. toctree:: :titlesonly: diff --git a/source/reference/command/collMod.txt b/source/reference/command/collMod.txt index ffc65f7c103..a8a80aa43db 100644 --- a/source/reference/command/collMod.txt +++ b/source/reference/command/collMod.txt @@ -67,15 +67,13 @@ Index Options - The number of seconds that determines the expiration threshold of a :doc:`TTL Collection `. - If successful, the command returns a document that contains - both the old and new values for the changed property: - ``expireAfterSeconds_old`` and ``expireAfterSeconds_new``. + If successful, the command returns a document that contains: - You can only modify an existing TTL index; i.e. an index with - an existing ``expireAfterSeconds`` property. If the index - does not have an existing ``expireAfterSeconds`` property, - the operation errors with ``no expireAfterSeconds field to - update``. + - ``expireAfterSeconds_new``, the new value for + ``expireAfterSeconds`` + - ``expireAfterSeconds_old``, the old value for + ``expireAfterSeconds``, if the index had a value for + ``expireAfterSeconds`` before. Modifying the index option ``expireAfterSeconds`` resets the :pipeline:`$indexStats` for the index. @@ -377,7 +375,7 @@ To hide a text index, you must specify the index by ``name`` and not by - :doc:`/core/index-hidden` - :method:`db.collection.hideIndex()` - :method:`db.collection.unhideIndex()` - + Add Document Validation to an Existing Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -420,7 +418,7 @@ validation rules to insert operations and to update operationss to existing documents that already fulfill the validation criteria. Updates to existing documents that do not fulfill the validation criteria are not checked for validity. - + With the ``warn`` :collflag:`validationAction`, MongoDB logs any violations but allows the insertion or update to proceed. diff --git a/source/release-notes/5.1.txt b/source/release-notes/5.1.txt index 03b56bb56e3..8825deab21f 100644 --- a/source/release-notes/5.1.txt +++ b/source/release-notes/5.1.txt @@ -12,6 +12,18 @@ Release Notes for MongoDB 5.1 .. include:: /includes/in-dev.rst +Indexes +------- + +Convert a non-TTL single-field Index into a TTL Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.1, you can use the :dbcommand:`collMod` database +command to add the ``expireAfterSeconds`` option to an existing +single-field non-TTL index. + +.. _5.1-rel-notes-general: + General Improvements --------------------