BSON文档大小上限为16MB，是MongoDB服务端强制执行的硬限制；PyMongo不提前校验，超限时抛出DocumentTooLarge异常；insert_one()和insert_many()均受此约束，需通过拆分、GridFS或外存引用解决。
BSON文档大小上限是硬限制，不是配置能调的
MongoDB 的 BSON 协议规定单个文档最大为 16MB，这是服务端强制执行的硬边界。PyMongo 在序列化时不会提前检查大小，而是在发送前或服务端接收时直接拒绝——错误通常表现为 DocumentTooLarge 或类似 OperationFailure: document is too large 的异常。这不是网络超时或连接问题，也跟 PyMongo 版本无关。
insert_one() 和 insert_many() 都受同一限制约束
无论用哪个插入方法，只要单条文档（含所有嵌套字段、数组、二进制数据）序列化后超过 16MB，就会失败。注意：insert_many() 的 ordered=False 参数只影响多文档间的错误传播，对单文档超限无效——它不会帮你拆分大文档。
- 常见误判：把“批量插入慢”等同于“文档太大”，其实可能是索引缺失或网络延迟
- 真实超限场景：存原始图像 base64 字符串、未压缩的 CSV 内容、完整日志块、大型 NumPy 数组（未降维）
- 验证方式：用
len(bson.encode(document))在插入前粗略估算（需先确保 document 已转为纯 Python 类型）
超过16MB必须主动拆分或换存储方案
没有绕过该限制的官方方式。强行修改 MongoDB 源码或启用实验性选项风险极高，生产环境禁止尝试。
- 拆分文档：按逻辑单元切分（如日志按小时、报告按章节），用
chunk_id+total_chunks关联 - 改用 GridFS：PyMongo 自带
gridfs.GridFS，自动分块存储并提供文件式 API，适合二进制大对象 - 外存+引用：把大内容存到对象存储（如 S3、MinIO），MongoDB 只存元数据和 URL
- 注意：Pandas
to_dict('records')后直接插入，若某行含未处理的 numpy.ndarray，可能隐式膨胀成超大 BSON 结构
容易被忽略的“伪大文档”陷阱
文档本身没超 16MB，但因类型未清洗导致序列化膨胀——最典型的是 numpy 类型未转原生。
立即学习“Python免费学习笔记（深入）”；
-
np.array([1,2,3], dtype=np.int64)直接插入 → 序列化后可能比[1,2,3]多出数倍体积 - 使用
.item()或.tolist()清洗后，体积回归正常，且避免TypeError - 嵌套结构里混用 pandas.Series 和 dict，也可能在序列化时触发隐式转换放大
