collMod

更改索引属性

要更改索引选项，指定要更改的现有索引选项的键模式或名称

db.runCommand( {
   collMod: <collection>,
   index: {
      keyPattern: <index_spec> | name: <index_name>,
      expireAfterSeconds: <number>,  // Set the TTL expiration threshold
      hidden: <boolean>,             // Change index visibility in the query planner
      prepareUnique: <boolean>,      // Reject new duplicate index entries
      unique: <boolean>              // Convert an index to a unique index
   },
   dryRun: <boolean>
} )

如果索引不存在，命令将报错，错误信息为 "无法找到名称为 <name|keyPattern> 的索引 for ns <db.collection>"。

index

索引选项 index 可以更改现有索引的以下属性：

索引属性	描述
expireAfterSeconds	确定 TTL 集合过期阈值的秒数。[TTL 集合](/docs/manual/tutorial/expire-data/#std-label-ttl-collections)。 如果成功，命令返回一个包含以下内容的文档： expireAfterSeconds_new，新的 expireAfterSeconds 值 expireAfterSeconds_old，旧的 expireAfterSeconds 值，如果索引在之前有 expireAfterSeconds 的值。 修改索引选项 expireAfterSeconds 会重置索引的 $indexStats。 如果您使用 MongoDB 5.0 之前的 TTL 索引，或者如果您想将 MongoDB 5.0 中创建的数据与低于 5.0 的安装同步，请参阅 [使用 NaN 配置的索引](/docs/manual/tutorial/expire-data/#std-label-expireData-warning)，以避免配置错误。 TTL 索引 expireAfterSeconds 值必须在 0 和 2147483647 之间（包含）。
hidden	一个布尔值，用于确定索引是否从查询计划器中隐藏。[隐藏索引](/docs/manual/core/index-hidden/#std-label-index-type-hidden)。 如果 hidden 值发生变化，命令将返回一个包含更改属性旧值和新值的文档：hidden_old 和 hidden_new。 但是，如果 hidden 值没有变化（即隐藏已隐藏的索引或取消隐藏已取消隐藏的索引），则命令将省略输出中的 hidden_old 和 hidden_new 字段。 要隐藏索引，您必须将 featureCompatibilityVersion 设置为 4.4 或更高。 如果值发生变化，则修改索引选项 hidden 会重置索引的 $indexStats。
prepareUnique	一个布尔值，用于确定索引是否接受新的重复条目。 当 prepareUnique 为 true 时，新重复条目会失败并返回 DuplicateKey 错误。生成的索引可以转换为唯一索引。要转换索引，请使用带有 unique 选项的 collMod。 如果更新现有索引，使 prepareUnique 为 true，则不会检查预存在的重复索引条目。 新版本6.0.
unique	一个布尔值，用于确定索引是否唯一。 false 的值不受支持。 当 unique 为 true 时，collMod 会扫描 keyPattern 索引以查找重复项，如果没有重复索引条目，则将其转换为唯一索引。 如果在初始扫描期间检测到重复项，collMod 会返回 CannotConvertIndexToUnique 和冲突文档列表。要将具有重复条目的索引转换为唯一索引，请纠正报告的冲突，然后重新运行 collMod。 要结束转换，请将 prepareUnique 设置为 false。 有关如何将非唯一索引转换为唯一索引的示例，请参阅 [将现有索引转换为唯一索引](/docs/manual/core/index-unique/convert-to-unique/#std-label-index-convert-to-unique)。 新版本6.0.

dryRun

默认值： false

仅在 index.unique 为 true 时使用。

在将非唯一索引转换为唯一索引之前，您可以运行带有 dryRun: true 的 collMod 命令。如果这样做，MongoDB 将检查集合中的重复键并返回任何违规。

使用 dryRun: true 以确认您可以无错误地将索引转换为唯一索引。

验证文档

validator

validator 允许用户为集合指定 验证规则或表达式。

验证器（validator）选项接受一个指定验证规则或表达式的文档。您可以使用与查询运算符相同的运算符来指定表达式，但除了$near、$nearSphere、$text和$where之外。

注意

• 验证发生在更新和插入过程中。现有文档在修改之前不会进行验证检查。

• 您不能为admin、local和config数据库中的集合指定验证器。

• 您不能为system.*集合指定验证器。

validationLevel

validationLevel决定MongoDB在更新期间对现有文档应用验证规则的程度。

"off"

不进行插入或更新的验证。

"strict"

默认值 对所有插入和所有更新应用验证规则。

"moderate"

对插入和现有有效文档的更新应用验证规则。不将规则应用于现有无效文档的更新。

要查看使用validationLevel的示例，请参阅为现有文档指定验证级别。

validationAction

validationAction 选项确定是否在无效文档上引发错误，还是仅对违规行为发出警告，但允许无效文档。

重要

文档验证仅适用于由 validationLevel 确定的文档。

要查看使用 validationAction 的示例，请参阅选择处理无效文档的方式。

修改视图

viewOn

基本源集合或视图。视图定义是通过将指定的 pipeline 应用到此源来确定的。

如果修改在启用访问控制的 MongoDB 部署上运行的视图，则必须指定。

pipeline

定义视图的 聚合管道。

注意

视图定义的 pipeline 不能包含 $out 或 $merge 阶段。此限制也适用于嵌入式管道，例如在 $lookup 或 $facet 阶段中使用的管道。

如果修改在启用访问控制的 MongoDB 部署上运行的视图，则必须指定。

视图定义是公开的；即 db.getCollectionInfos() 和对视图的 explain 操作将包括定义视图的管道。因此，请避免在视图定义中直接引用敏感字段和值。

db.runCommand( {
   collMod: "myView",
   viewOn: "activities",
   pipeline: [
     { $match: { status: "Q" } },
     { $project: { user: 1, date: 1, description: 1} } ]
} )

修改时间序列集合

expireAfterSeconds

注意

这不同于使用具有 expireAfterSeconds 属性的 index 选项来更改 TTL 集合 的过期时间。

要启用自动文档删除或修改时间序列集合的当前过期时间间隔，请更改 expireAfterSeconds 值。

db.runCommand( {
   collMod: <collection>,
   expireAfterSeconds: <number> | "off"
} )

将 expireAfterSeconds 设置为 "off" 以禁用自动删除，或设置为非负十进制数字（>=0）以指定文档过期的秒数。

granularity

要修改时间序列集合的粒度，可以将 timeseries.granularity 从较短的时间单位增加到较长时间单位。

db.runCommand( {
   collMod: "weather24h",
   timeseries: { granularity: "seconds" | "minutes" | "hours" }
} )

要更新自定义分桶字段 bucketRoundingSeconds 和 bucketMaxSpanSeconds 而不是 granularity，在 collMod 命令中包含这两个自定义字段并将它们设置为相同的值。

db.runCommand( {
   collMod: "weather24h",
   timeseries: {
      bucketRoundingSeconds: 86400,
      bucketMaxSpanSeconds: 86400
   }
} )

您不能减小粒度间隔或自定义分桶值。

重要

如果任何时间序列集合显式指定了自定义分桶字段 bucketMaxSpanSeconds 和 bucketRoundingSeconds，则不能将版本降级到 MongoDB 6.3 以下。如果可能，转换为相应的 granularity。如果无法转换，必须在降级之前删除集合。

要将集合从自定义分桶转换为 granularity，两个 bucketMaxSpanSeconds 和 bucketRoundingSeconds 必须小于或等于 granularity 等价值。

粒度	bucketRoundingSeconds 限制（包含）	bucketMaxSpanSeconds 限制（包含）
秒	60	3600
分钟	3600	86400
小时	86400	2592000

提示

另请参阅

为时间序列数据设置粒度

调整固定集合大小

从 MongoDB 6.0 版本开始，您可以调整固定集合的大小。要更改固定集合的最大字节数，请使用 cappedSize 选项。要更改现有固定集合中的最大文档数，请使用 cappedMax 选项。

cappedSize

指定一个capped集合的新最大大小（以字节为单位）。cappedSize必须大于0且小于1e+15（1 PB）。

cappedMax

指定capped集合中的新最大文档数。将cappedMax设置为小于或等于0表示无限制。

例如，以下命令将capped集合的最大大小设置为100000字节，并将集合中的最大文档数设置为500

db.runCommand( {
   collMod: <collection>,
   cappedSize: 100000,
   cappedMax: 500
} )

带有文档前和后图像的更改流

changeStreamPreAndPostImages

从MongoDB 6.0版本开始，您可以使用更改流事件来输出文档更改前后的版本（文档前后映像）

• 前映像是文档在替换、更新或删除之前的版本。对于插入的文档没有前映像。

• 后映像是文档在插入、替换或更新之后的版本。对于删除的文档没有后映像。

• 使用db.createCollection()、create或collMod.命令为集合启用changeStreamPreAndPostImages。

要使用collMod为集合启用更改流的前后映像，使用changeStreamPreAndPostImages字段

db.runCommand( {
   collMod: <collection>,
   changeStreamPreAndPostImages: { enabled: <boolean> }
} )

要为集合启用更改流的前后映像，将changeStreamPreAndPostImages设置为true。例如

db.runCommand( {
   collMod: "orders",
   changeStreamPreAndPostImages: { enabled: true }
} )

要为集合禁用更改流的前后映像，将changeStreamPreAndPostImages设置为false。例如

db.runCommand( {
   collMod: "orders",
   changeStreamPreAndPostImages: { enabled: false }
} )

如果图像在文档更新或删除操作时未被启用，则更改流事件中不可用前后映像

• 在集合中未启用

• 在expireAfterSeconds中设置的前后映像保留时间之后被删除。

  • 以下示例将整个集群上的expireAfterSeconds设置为100秒

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: {
             preAndPostImages: { expireAfterSeconds: 100 }
          } }
    } )

  • 以下示例返回当前的changeStreamOptions设置，包括expireAfterSeconds

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

  • 将expireAfterSeconds设置为off使用默认保留策略：前后映像保留，直到相应的更改流事件从oplog中删除。

  • 如果更改流事件从oplog中删除，则相应的前后映像也将被删除，无论expireAfterSeconds的前后映像保留时间。

其他注意事项

• 启用前后映像会消耗存储空间并增加处理时间。只有在需要时才启用前后映像。

• 将更改流事件的大小限制在小于16兆字节。要限制事件大小，您可以

  • 将文档大小限制在8兆字节。如果其他变更流事件字段，如updateDescription，不是很大，您可以在变更流输出中同时请求预图像和后图像。

  • 如果其他变更流事件字段，如updateDescription，不是很大，则仅请求16兆字节文档的变更流输出中的后图像。

  • 如果

    • 文档更新只影响文档结构或内容的一小部分，并且

    • 不会引发replace变更事件。一个replace事件总是包含后图像。

• 要请求预图像，您在db.collection.watch()中将fullDocumentBeforeChange设置为required或whenAvailable。要请求后图像，使用相同的方法设置fullDocument。

• 预图像被写入到config.system.preimages集合。

  • 集合config.system.preimages可能会变得很大。为了限制集合大小，您可以像前面所示为预图像设置expireAfterSeconds时间。

  • 预图像由后台进程异步删除。

附加注释

注释

可选。您可以为此命令附加注释。注释必须是一个顶级字段，可以是任何有效的 BSON 类型。您指定的注释将显示在此命令记录的以下位置：

• mongod 日志消息，在 attr.command.cursor.comment 字段中。

• 数据库分析器输出，在 command.comment 字段中。

• currentOp 输出，在 command.comment 字段中。

写关注

w

可选。表示 collMod 命令的写关注的文档。

省略以使用默认写关注。

资源锁定

collMod 命令在操作期间锁定指定集合上的集合锁。

更改索引的过期值

以下示例更新了名为 user_log 的集合上现有 TTL 索引 { lastAccess: 1 } 的 expireAfterSeconds 属性。该索引当前 expireAfterSeconds 属性设置为 1800 秒（或 30 分钟），示例将值更改为 3600 秒（或 60 分钟）。

db.runCommand({
   collMod: "user_log",
   index: {
      keyPattern: { lastAccess: 1 },
      expireAfterSeconds: 3600
   }
})

如果操作成功，将返回一个文档，其中包含更改属性的旧值和新值

{ "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 }

从查询计划中隐藏索引

以下示例 隐藏 了 orders 集合上的现有索引。具体来说，该操作隐藏了具有指定 { shippedDate: 1 } 的索引，使其不被查询计划器考虑。

db.runCommand( {
   collMod: "orders",
   index: {
      keyPattern: { shippedDate: 1 },
      hidden: true
   }
} )

如果操作成功，将返回一个文档，其中包含更改属性的旧值和新值

{ "hidden_old" : false, "hidden_new" : true, "ok" : 1 }

要隐藏文本索引，您必须通过 name 指定索引，而不是通过 keyPattern。