Database Manual / Reference / Database Commands / Administration

convertToCapped (database command数据库命令)

Definition定义

convertToCapped

Warning

Do Not Run This Command On Sharded Collections不要在分片集合上运行此命令

MongoDB does not support the convertToCapped command on sharded collections.MongoDB不支持对分片集合执行convertToCapped命令。

The convertToCapped command converts an existing, non-capped collection to a capped collection within the same database.convertToCapped命令将同一数据库中现有的非封顶集合转换为封顶集合。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务
  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

db.runCommand(
   {
     convertToCapped: <collection>,
     size: <capped size>,
     writeConcern: <document>,
     comment: <any>
   }
)

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Description描述
convertToCappedThe name of the existing collection to convert.要转换的现有集合的名称。
sizeThe maximum size, in bytes, for the capped collection.上限集合的最大大小（以字节为单位）。
writeConcernOptional. 可选。A document expressing the write concern of the drop command. Omit to use the default write concern.表示drop命令写入关注的文档。省略使用默认写入关注。
comment

Optional. 可选。A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:用户提供了要附加到此命令的注释。设置后，此注释将与此命令的记录一起出现在以下位置：

A comment can be any valid BSON type (string, integer, object, array, etc).注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。

convertToCapped takes an existing collection (<collection>) and transforms it into a capped collection with a maximum size in bytes, specified by the size argument (<capped size>).接受一个现有的集合（<collection>），并将其转换为一个有上限的集合，最大大小为字节，由size参数（<capped size>）指定。

During the conversion process, the convertToCapped command exhibits the following behavior:在转换过程中，convertToCapped命令显示以下行为：

  • MongoDB traverses the documents in the original collection in natural order and loads the documents into a new capped collection.MongoDB以自然顺序遍历原始集合中的文档，并将文档加载到一个新的封顶集合中。
  • If the capped size specified for the capped collection is smaller than the size of the original uncapped collection, then MongoDB will overwrite documents in the capped collection based on insertion order, or first in, first out order.如果为封顶集合指定的上限大小小于原始非封顶集合的大小，则MongoDB将根据插入顺序或先进先出顺序覆盖上限集合中的文档。

  • Internally, to convert the collection, MongoDB uses the following procedure在内部，为了转换集合，MongoDB使用以下过程

    • cloneCollectionAsCapped command creates the capped collection and imports the data.命令创建上限集合并导入数据。
    • MongoDB drops the original collection.MongoDB删除了原始集合。
    • renameCollection renames the new capped collection to the name of the original collection.将新的上限集合重命名为原始集合的名称。
  • This holds a database exclusive lock for the duration of the operation. Other operations which lock the same database will be blocked until the operation completes. See What locks are taken by some common client operations? for operations that lock the database.这将在操作期间保持数据库独占锁。锁定同一数据库的其他操作将被阻止，直到操作完成。请参阅一些常见的客户端操作会占用哪些锁？用于锁定数据库的操作。

Warning

The convertToCapped will not recreate indexes from the original collection on the new collection, other than the index on the _id field. If you need indexes on this collection you will need to create these indexes after the conversion is complete.convertToCapped不会在新集合上从原始集合重新创建索引，除了_id字段上的索引。如果您需要此集合的索引，则需要在转换完成后创建这些索引。

Example示例

Convert a Collection转换集合

The following example uses db.collection.insertOne() to create an events collection, and db.collection.stats() to obtain information about the collection:以下示例使用db.collection.insertOne()创建events集合，并使用db.collection.stats()获取有关该集合的信息：

db.events.insertOne( { click: 'button-1', time: new Date() } )
db.events.stats()

MongoDB will return the following:MongoDB将返回以下内容：

{
        "ns" : "test.events",
        ...
        "capped" : false,
        ...
}

To convert the events collection into a capped collection and view the updated collection information, run the following commands:要将events集合转换为上限集合并查看更新的集合信息，请运行以下命令：

db.runCommand( { convertToCapped: 'events', size: 8192 } )
db.events.stats()

MongoDB will return the following:MongoDB将返回以下内容：

{
     "ns" : "test.events",
     ...
     "capped" : true,
     "max" : Long("9223372036854775807"),
     "maxSize" : 8192,
     ...
}

The convertToCapped will not recreate indexes from the original collection on the new collection, other than the index on the _id field. If you need indexes on this collection you will need to create these indexes after the conversion is complete.convertToCapped不会在新集合上从原始集合重新创建索引，除了_id字段上的索引。如果您需要此集合的索引，则需要在转换完成后创建这些索引。

Tip

create