shardCollection命令必须在admin数据库执行，且分片键需预先建索引、非数组/嵌套字段；已有数据的集合须确保每文档均含合法分片键值，命令成功仅表示调度完成，分片实际由balancer异步执行。
shardCollection 命令必须发给 admin 数据库
PyMongo 里 shardCollection 是个管理命令，不是某个集合的方法，它只能在 admin 数据库上下文中执行。如果你连的是业务库（比如 myapp），直接调 db.command("shardCollection", ...) 会报 CommandNotFound 或权限错误。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
client.admin获取 admin 数据库句柄，再调command() - 确保连接用户有
clusterAdmin或至少shardManager角色 - 命令格式固定：
admin.command("shardCollection", "db.collection", key={"field": 1}, **opts)
分片键字段必须已建索引且不能是数组或嵌套文档
MongoDB 要求分片键字段在执行 shardCollection 前，已在目标集合上存在对应方向的单字段或复合索引。如果没建索引，会返回 Location13324 错误；如果字段值是数组、ObjectId 以外的 ObjectId-like 字符串、或含点号的嵌套路径（如 "user.profile.age"），操作会失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 先用
collection.create_index([("shard_key", 1)])显式建索引 - 避免用
_id当分片键——除非你明确设了自定义_id且已索引 - 时间戳类字段慎用递增分片键（如
"created_at"），易导致写入热点
shardCollection 不支持对已有数据的集合“追加”分片键
如果集合已有文档，shardCollection 会尝试自动迁移数据，但前提是：集合当前未分片 + 分片键能覆盖所有现有文档（即每条文档都含该字段，且值不为 null 或数组）。一旦有缺失或非法值，命令直接中止，不回滚，集合仍处于未分片状态。
常见错误现象：
Cannot shard collection with missing shard key valuecannot shard collection with array value for shard key- 命令卡住数分钟后超时（其实是 chunk 拆分阻塞）
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 新集合：先
shardCollection，再插入数据 - 存量集合：用
mongoshell 先跑db.collection.validate({full: true})检查字段完整性 - 必要时用
aggregate扫描异常文档：collection.aggregate([{"$match": {"shard_key": {"$exists": false}} }])
PyMongo 调用后要检查返回结果，不能只靠无异常就认为成功
admin.command() 即使返回字典也不代表分片已生效。MongoDB 的分片是异步触发的，命令返回只是表示“调度成功”，后续 chunk 拆分、迁移由 balancer 异步完成。你可能看到 {"ok": 1, "collectionsharded": "db.coll"}，但 sh.status() 里仍显示 0 个 chunk。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 调用后立刻查
admin.command("listShards")确认集群有可用分片 - 用
client.db.command("collStats", "coll")查"sharded"字段是否为True - 等待并轮询
admin.command("shardingState")或查 config 数据库：config.chunks.count_documents({"ns": "db.coll"})
分片不是开关一按就完事的事——键设计、索引、数据洁度、balancer 状态，漏掉任一环，shardCollection 就只是个漂亮的失败快照。
