/
expire-data.txt
128 lines (97 loc) · 4.68 KB
/
expire-data.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
.. _ttl-collections:
===========================================
Expire Data from Collections by Setting TTL
===========================================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
This document provides an introduction to MongoDB's "*time to live*"
or :term:`TTL` collection feature. TTL collections make it possible to
store data in MongoDB and have the :program:`mongod` automatically
remove data after a specified number of seconds or at a specific clock
time.
Data expiration is useful for some classes of information, including
machine generated event data, logs, and session information that only
need to persist for a limited period of time.
A special :doc:`TTL index property </core/index-ttl>` supports the
implementation of TTL collections. The TTL feature relies on a
background thread in :program:`mongod` that reads the date-typed values
in the index and removes expired :term:`documents <document>` from the
collection.
Procedures
----------
To create a :doc:`TTL index </core/index-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
:ref:`date values <document-bson-type-date>`.
.. note::
The TTL index is a single field index. Compound indexes do not
support the TTL property. For more information on TTL indexes, see
:doc:`/core/index-ttl`.
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
date type or an array of BSON date-typed objects *and* specify a
positive non-zero value in the ``expireAfterSeconds`` field. A document
will expire when the number of seconds in the ``expireAfterSeconds``
field has passed since the time specified in its indexed field.
[#field-is-array-of-dates]_
For example, the following operation creates an index on the
``log_events`` collection's ``createdAt`` field and specifies the
``expireAfterSeconds`` value of ``3600`` to set the expiration time to
be one hour after the time specified by ``createdAt``.
.. code-block:: javascript
db.log_events.createIndex( { "createdAt": 1 }, { expireAfterSeconds: 3600 } )
When adding documents to the ``log_events`` collection, set the
``createdAt`` field to the current time:
.. code-block:: javascript
db.log_events.insert( {
"createdAt": new Date(),
"logEvent": 2,
"logMessage": "Success!"
} )
MongoDB will automatically delete documents from the ``log_events``
collection when the document's ``createdAt`` value
[#field-is-array-of-dates]_ is older than the number of seconds
specified in ``expireAfterSeconds``.
.. [#field-is-array-of-dates] If the field contains an array of BSON
date-typed objects, data expires if at least one of BSON date-typed
object is older than the number of seconds specified in
``expireAfterSeconds``.
.. seealso:: :update:`$currentDate` operator
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
BSON date-typed objects *and* specify an ``expireAfterSeconds`` value
of ``0``. For each document in the collection, set the indexed date
field to a value corresponding to the time the document should expire.
If the indexed date field contains a date in the past, MongoDB
considers the document expired.
For example, the following operation creates an index on the
``log_events`` collection's ``expireAt`` field and specifies the
``expireAfterSeconds`` value of ``0``:
.. code-block:: javascript
db.log_events.createIndex( { "expireAt": 1 }, { expireAfterSeconds: 0 } )
For each document, set the value of ``expireAt`` to correspond to the
time the document should expire. For instance, the following
:method:`~db.collection.insert()` operation adds a document that should
expire at ``July 22, 2013 14:00:00``.
.. code-block:: javascript
db.log_events.insert( {
"expireAt": new Date('July 22, 2013 14:00:00'),
"logEvent": 2,
"logMessage": "Success!"
} )
MongoDB will automatically delete documents from the ``log_events``
collection when the documents' ``expireAt`` value is older than the
number of seconds specified in ``expireAfterSeconds``, i.e. ``0``
seconds older in this case. As such, the data expires at the specified
``expireAt`` value.