$out只能写入非分片集合且会覆盖目标集合,因其需原子性drop+重建,而分片集合元数据分散无法协调;正确用法是先$out到新非分片集合,再手动分片和建索引。

$out 是最直接的导出方式,但必须注意:它只能写入非分片集合,且会无条件覆盖目标集合。
为什么 $out 不能直接写入分片集合
在分片集群中执行 $out 到一个已分片的集合(或试图让输出集合自动分片),会立即报错:not supported on sharded collections。这不是权限或语法问题,而是 MongoDB 的底层限制:该操作需原子性地 drop + 重建集合,而分片集合的元数据分布在 config server 和多个 shard 上,无法安全协调这一过程。
- 目标集合若已存在且是分片的 → 必报错,不管是否为空
- 目标集合不存在 → MongoDB 自动创建,但默认建在主分片(primary shard)上,且是非分片状态
- 即使你提前用
sh.shardCollection()对空集合分片,$out仍会拒绝写入 —— 它只认“当前是否分片”,不看“是否可分片”
如何正确使用 $out 导出到新集合
核心是接受“先非分片、再分片”的两步逻辑。只要目标集合名未被占用,$out 就能快速完成数据落盘。
- 确保 pipeline 最后一个阶段是
$out,例如:{$out: "aggr_orders_2024_q3"}或{$out: {db: "reporting", coll: "aggr_orders_2024_q3"}} - 如果输出字段中包含计划用作分片键的字段(如
region、order_date),请在 pipeline 前期用$addFields显式补全并规范类型,避免后续sh.shardCollection()失败 - 聚合执行期间,目标集合不可见;失败则集合不会创建,原集合完全不受影响
- 不要依赖
$out做增量更新 —— 它总是整表替换,没有 upsert 语义
$out vs $merge:什么时候该换用 $merge
当你的目标集合**已经是分片的**,或者你需要保留历史数据、做增量合并时,$merge 是唯一可行替代方案。
-
$merge支持直接写入分片集合,但要求 pipeline 输出文档中必须包含与分片键完全匹配的字段(如{region: 1, order_date: 1}),且这些字段值不能为null或类型混乱 -
$merge默认行为是按on字段 upsert,不会自动清空旧数据 —— 如果你要“全量替换”,得先手动db.target_collection.deleteMany({}),或在$merge中配置whenMatched: "replace"并确保on覆盖全部文档 - 性能上,
$merge比$out慢,尤其在大集合上,因为它要逐条比对、更新或插入
容易被忽略的细节
很多人卡在最后一步:以为 $out 写完就万事大吉,结果发现新集合查不到索引、分片不均、甚至应用读取超时。
-
$out创建的新集合**不会继承源集合的任何索引**,必须手动重建;否则后续查询可能全表扫描 - 用
sh.shardCollection()分片前,务必确认输出文档中分片键字段值分布均匀;大量null或单一值会导致 chunk 无法分裂、写入集中在单个 shard - 如果目标数据库在分片集群中不存在,
$out会失败(与副本集不同);必须先use target_db或通过mongosh执行db.getSiblingDB("target_db").createCollection("dummy")触发库创建


















