复合分片键必须在sh.shardCollection时一次性指定,不支持事后添加或升级;需提前创建对应复合索引,字段必须存在且类型一致,仅支持范围分片,不支持哈希分片。

复合分片键必须在创建集合时指定,不能事后添加
MongoDB 7.0 不支持对已有非分片集合直接启用复合分片键;更不能对已分片但使用单字段键的集合“升级”为复合键。你必须在 shardCollection 命令中一次性声明完整键结构,且该键必须是集合中已存在的字段(或其前缀),且所有字段都需有索引支撑。
常见错误现象:cannot shard collection unless the shard key is specified 或 the shard key must be prefixed by an existing index —— 这通常是因为漏建索引,或字段类型不匹配(比如用 Date 字段做第二级键,但文档里存的是字符串)。
- 确保目标字段已存在于所有待插入文档中(空值或缺失字段会导致 chunk 分配失败)
- 先在主分片上为复合键创建升序索引,例如:
db.orders.createIndex({ "region": 1, "order_id": 1 }) - 执行分片命令时,键名顺序和索引顺序必须严格一致:
sh.shardCollection("mydb.orders", { "region": 1, "order_id": 1 }) - 如果集合已有数据,必须保证现有文档中这两个字段组合能支撑均匀分布(避免出现大量
region: "CN"却没有二级区分)
插入文档时字段顺序无关,但值必须完整且类型一致
MongoDB 不校验插入时字段定义顺序,但会严格检查复合分片键字段是否全部存在、类型是否与索引一致。例如,若分片键是 { "tenant_id": 1, "created_at": 1 },则每条插入文档都必须包含这两个字段,且 created_at 不能是字符串(即使格式正确)。
容易踩的坑:用 ORM 或客户端自动生成文档时,可能默认省略 undefined 或 null 字段,导致实际插入缺失键字段,进而触发 Document does not contain shard key 错误。
- 插入前显式检查字段存在性:
if (!doc.tenant_id || !doc.created_at) throw new Error("shard key fields missing") - 避免用
Date.now()直接赋值给时间字段,应统一转为new Date()实例 - 批量插入(
insertMany)同样受约束,任一文档违规都会导致整批失败(除非启用ordered: false)
哈希分片不支持复合键,范围分片才是唯一选择
MongoDB 7.0 中,hashed 分片策略只接受单字段键,尝试传入复合对象(如 { "a": "hashed", "b": 1 })会直接报错:cannot use hashed index on compound key。复合分片键只能配合范围分片(即升序/降序索引)使用。
这意味着你必须接受潜在的数据倾斜风险——比如 region 值高度集中("US" 占 80%),即使第二级键 order_id 分布均匀,也仍可能导致 US 对应的 chunk 持续变大、迁移困难。
- 优先选高基数字段作为第一级键(如
tenant_id>region) - 避免用递增字段(如自增 ID、毫秒时间戳)作第二级键,否则新写入永远落在同一个 chunk
- 可通过
sh.status()观察 chunk 分布,重点关注region维度下各 chunk 的文档数差异
预分片(pre-splitting)对复合键插入很关键
刚启用复合分片键后,所有数据默认写入一个初始 chunk。如果立即高并发插入,这个 chunk 很快达到 64MB 或 250000 文档上限,触发自动分裂 —— 但分裂过程会阻塞写入,且初期 chunk 边界不合理,易加剧不均衡。
真实生产环境中,建议在首次插入前手动预分片,尤其当第一级键已知有限取值时(如 region ∈ ["US", "EU", "AP"])。
- 用
sh.splitAt("mydb.orders", { "region": "EU", "order_id": ObjectId(...) })切出边界 - 更稳妥的做法是先用
sh.addShardToZone+sh.updateZoneKeyRange配合预分片,把不同 region 映射到不同 zone - 预分片后插入,可跳过冷启动阶段的性能抖动,也能让 balancer 更早介入均衡
MongoDB 7.0 的复合分片键本身不难设,真正复杂的是键设计决策:哪两个字段组合既满足查询模式,又能扛住写入压力,还不被索引限制卡住。很多问题不是出在语法,而是出现在第一次 insertOne 前没想清楚数据生命周期。











