使用 Azure Cosmos DB 的用于 MongoDB 的 API 过期数据Expire data with Azure Cosmos DB's API for MongoDB

生存时间 (TTL) 功能允许数据库将数据自动过期。Time-to-live (TTL) functionality allows the database to automatically expire data. Azure Cosmos DB 的用于 MongoDB 的 API 使用了 Cosmos DB 的核心 TTL 功能。Azure Cosmos DB's API for MongoDB utilizes Cosmos DB's core TTL capabilities. 支持两种模式:一是在整个集合上设置默认的 TTL 值,二是为每个文档设置单独的 TTL 值。Two modes are supported: setting a default TTL value on the whole collection, and setting individual TTL values for each document. Cosmos DB 的用于 MongoDB 的 API 中的控制 TTL 索引和按文档 TTL 值的逻辑与 Cosmos DB 中的相同The logic governing TTL indexes and per-document TTL values in Cosmos DB's API for MongoDB is the same as in Cosmos DB.

TTL 索引TTL indexes

若要在集合上普遍启用 TTL,需创建“TTL 索引”(生存时间索引)To enable TTL universally on a collection, a "TTL index" (time-to-live index) needs to be created. TTL 索引是 _ts 字段上的索引,其值为“expireAfterSeconds”。The TTL index is an index on the _ts field with an "expireAfterSeconds" value.

示例:Example:

globaldb:PRIMARY> db.coll.createIndex({"_ts":1}, {expireAfterSeconds: 10})
{
        "_t" : "CreateIndexesResponse",
        "ok" : 1,
        "createdCollectionAutomatically" : true,
        "numIndexesBefore" : 1,
        "numIndexesAfter" : 4
}

以上示例中的命令将通过 TTL 功能创建一个索引。The command in the above example will create an index with TTL functionality. 创建索引以后,数据库会自动删除集合中未在过去 10 秒内修改的任何文档。Once the index is created, the database will automatically delete any documents in that collection that have not been modified in the last 10 seconds.

备注

_ts 是特定于 Cosmos DB 的字段,不可从 MongoDB 客户端访问。_ts is a Cosmos DB-specific field and is not accessible from MongoDB clients. 它是一个保留(系统)属性,其中包含文档上一次修改的时间戳。It is a reserved (system) property that contains the timestamp of the document's last modification.

另外,C# 示例可以:Additionally, a C# example:

var options = new CreateIndexOptions {ExpireAfter = TimeSpan.FromSeconds(10)}; 
var field = new StringFieldDefinition<BsonDocument>("_ts"); 
var indexDefinition = new IndexKeysDefinitionBuilder<BsonDocument>().Ascending(field); 
await collection.Indexes.CreateOneAsync(indexDefinition, options); 

设置文档的生存时间值Set time to live value for a document

按文档 TTL 值也受支持。Per-document TTL values are also supported. 文档必须包含根级属性“ttl”(小写),系统必须为该集合创建如上所述的 TTL 索引。The document(s) must contain a root-level property "ttl" (lower-case), and a TTL index as described above must have been created for that collection. 在文档上设置的 TTL 值将替代集合的 TTL 值。TTL values set on a document will override the collection's TTL value.

TTL 值必须是 int32。The TTL value must be an int32. 也可以是属于 int32 的 int64,或者是没有任何小数部分属于 int32 的 double。Alternatively, an int64 that fits in an int32, or a double with no decimal part that fits in an int32. 不符合这些规范的 TTL 属性值是允许的,但不会被系统视为有意义的文档 TTL 值。Values for the TTL property that do not conform to these specifications are allowed but not treated as a meaningful document TTL value.

文档的 TTL 值为可选;没有 TTL 值的文档可以插入集合中。The TTL value for the document is optional; documents without a TTL value can be inserted into the collection. 在这种情况下,将使用集合的 TTL 值。In this case, the collection's TTL value will be honored.

以下文档具有有效的 TTL 值。The following documents have valid TTL values. 插入文档以后,文档 TTL 值会替代集合的 TTL 值。Once the documents are inserted, the document TTL values override the collection's TTL values. 因此,会在 20 秒后删除文档。So, the documents will be removed after 20 seconds.

globaldb:PRIMARY> db.coll.insert({id:1, location: "Paris", ttl: 20.0}) 
globaldb:PRIMARY> db.coll.insert({id:1, location: "Paris", ttl: NumberInt(20)}) 
globaldb:PRIMARY> db.coll.insert({id:1, location: "Paris", ttl: NumberLong(20)}) 

以下文档的 TTL 值无效。The following documents have invalid TTL values. 文档可以插入,但文档 TTL 值不会被接受。The documents will be inserted, but the document TTL value will not be honored. 因此,文档会在 10 秒后被删除,因为使用的是集合的 TTL 值。So, the documents will be removed after 10 seconds because of the collection's TTL value.

globaldb:PRIMARY> db.coll.insert({id:1, location: "Paris", ttl: 20.5}) //TTL value contains non-zero decimal part. 
globaldb:PRIMARY> db.coll.insert({id:1, location: "Paris", ttl: NumberLong(2147483649)}) //TTL value is greater than Int32.MaxValue (2,147,483,648). 

如何激活按文档 TTL 功能How to activate the per-document TTL feature

可以使用 Azure Cosmos DB 的用于 MongoDB 的 API 激活每个文档的 TTL 功能。The per-document TTL feature can be activated with Azure Cosmos DB's API for MongoDB.

在门户中激活按文档 TTL 功能的屏幕截图

后续步骤Next steps