MongoDB的集合在创建时会固化一些配置选项，比如文档校验规则、TTL过期时间等。传统的做法是删除集合或索引后重建，但这对线上业务来说代价太高。$collMod正是为了解决这个问题而存在的，它可以在不重建集合的前提下，动态修改这些选项，是DBA和后端开发做在线变更时的重要工具。
$collMod的基本语法与参数解析
$collMod是聚合管道中一个比较特殊的阶段，它并不参与文档的数据流转，而是作为管理指令执行。完整语法如下：
db.runCommand({
collMod: "集合名称",
validator: { ... }, // 文档校验规则
validationLevel: "strict", // 校验级别：strict 或 moderate
validationAction: "error", // 校验行为：error 或 warn
index: {
keyPattern: { createdAt: 1 }, // 定位要修改的索引
expireAfterSeconds: 3600, // 新的TTL时间
hidden: false // 是否隐藏索引
},
viewOn: "源集合名", // 视图相关
pipeline: [ ... ] // 视图的聚合管道
})其中collMod字段指定目标集合名，validator接收一个文档校验表达式，支持$query风格的查询操作符。validationLevel控制校验的严格程度，strict表示所有插入和更新都必须通过校验，moderate则只对已有的合法文档更新时强制校验。validationAction决定校验失败时的行为，error会拒绝写入，warn只记录日志不阻断。
也可以通过aggregate命令调用，写法略有不同：
db.getSiblingDB("admin").aggregate([
{
$collMod: {
collMod: "orders",
validator: { status: { $in: ["pending", "paid", "closed"] } }
}
}
])需要注意，通过aggregate调用时要求运行在admin数据库上，这是它与runCommand方式的一个重要区别。
典型应用场景与完整示例
场景一：动态调整TTL索引的过期时间
假设订单表有一个基于createdAt字段的TTL索引，初始设置为7天过期，现在业务要求缩短为1天。如果走删除索引重建的老路，在索引重建期间会有性能抖动。用$collMod的index修饰符则可以秒级完成：
// 先查看现有索引，确认keyPattern
db.orders.getIndexes()
// 使用collMod在线修改expireAfterSeconds
db.runCommand({
collMod: "orders",
index: {
keyPattern: { createdAt: 1 },
expireAfterSeconds: 86400 // 修改为1天
}
})执行成功后，MongoDB会立即采用新的过期时间对文档进行清理调度，已有索引结构完全不受影响。此外，index修饰符还支持ready、hidden、expireAfterSeconds三种选项的组合修改，hidden选项在评估索引是否可以被安全删除时特别有用，先把索引隐藏观察一段时间，确认没有查询依赖后再删除，风险可控得多。
场景二：为已有集合添加文档校验规则
集合创建时没有指定validator，后续想补充字段约束怎么办？$collMod可以直接追加：
db.runCommand({
collMod: "users",
validator: {
$jsonSchema: {
bsonType: "object",
required: ["name", "email"],
properties: {
age: { bsonType: "int", minimum: 0, maximum: 150 }
}
}
},
validationLevel: "strict",
validationAction: "error"
})
// 验证：插入缺少name字段的文档会被拒绝
db.users.insertOne({ email: "test@ipipp.com" })
// 报错：Document failed validation这里用了$jsonSchema来做结构化校验，表达能力强于普通的查询操作符。一个常见误区是：修改校验规则并不会校验集合中已有的历史数据，它只对后续的插入和更新生效。如果想温和过渡，可以先用validationAction为warn的方式上线观察，确认没有误伤后再切换为error。
场景三：修改视图的定义
如果目标是视图而非普通集合，collMod还能修改viewOn和pipeline，实现视图定义的热更新：
db.runCommand({
collMod: "activeUsers",
viewOn: "users",
pipeline: [
{ $match: { status: "active" } },
{ $project: { name: 1, email: 1 } }
]
})这种用法在报表视图逻辑调整时很实用，下游应用查询的视图名不变，内部逻辑可以随时替换。
使用限制、权限要求与常见报错排查
$collMod属于管理类操作，执行账户需要具备目标集合上的collMod权限，通常通过内置角色dbAdmin或更高权限角色获得。在分片集群环境下，需要在配置服务器上正确路由，mongos会自动处理，但副本集模式下必须在主节点执行，从节点执行会直接报错。
常见报错有以下几类。第一类是index modifier requires an existing index，说明keyPattern没有匹配到任何现有索引，用getIndexes仔细核对字段顺序和排序方向即可。第二类是validation rule is not compatible with existing documents，发生在将validationLevel设为moderate时集合存在大量不合规文档的场景，需要先清洗数据。第三类是权限不足的unauthorized错误，检查角色配置即可。
还有几个实践层面的建议：修改TTL时间前先评估清理速率，突然缩短过期时间可能引发删除风暴占用IO；修改校验规则建议先在测试环境用explain验证表达式语义；所有collMod操作都应该记录变更工单，因为这类操作不会像DDL那样留下明显的索引重建痕迹，出问题时排查依赖文档记录。对于关键业务集合，变更前用db.collection.stats保存一份当前状态快照，是稳妥的回滚依据。