gridfs 存文件时需通过 upload_from_stream 的 metadata 参数传自定义字段，如 metadata={"project_id": "p-123"}；查询时在 fs.files 集合中用 "metadata.field" 路径过滤，并建议建索引。
GridFS 存文件时怎么带自定义字段
GridFS 本身不支持直接给文件加“属性”，但它的 files 集合文档天然允许你写任意字段——关键在于别只调用 upload_from_stream 这类快捷方法，得手动构造 file_id 并插入元数据。
常见错误是：用 fs.put() 传一个 bytes 就完事，结果发现 files 里只有 filename、uploadDate 等默认字段，自定义的 tags 或 owner_id 全丢了。
- 必须用
fs.upload_from_stream()的metadata参数（不是 keyword args）传字典，例如metadata={"project_id": "p-123", "version": 2} - 不要试图在
upload_from_stream后再用fs.files.update_one()去补字段——GridFS 的原子性不保证文件内容和元数据同步更新，可能造成读取时元数据缺失 -
metadata里不能放二进制、函数、非 JSON 序列化类型；datetime可以，但Decimal不行
查询时怎么按自定义字段过滤
查的是 fs.files 集合，不是 fs.chunks。很多人误以为要聚合两个集合，其实只要对 files 做普通 find 就够了。
典型场景：找所有 status: "processed" 的 PDF 文件。
- 用
fs.bucket.files.find({"metadata.status": "processed", "filename": {"$regex": "\.pdf$"}}) - 注意字段路径写法：
metadata.status，不是status；GridFS 把你传的metadata整体塞进files文档的metadata字段下 - 如果字段值常用于查询，记得在
fs.files上建索引，比如db.fs.files.createIndex({"metadata.project_id": 1, "uploadDate": -1})
Python PyMongo 里 metadata 和额外参数容易混淆的点
upload_from_stream 有 4 个位置参数，第 4 个才是 metadata；但很多人把 chunk_size_bytes 和 metadata 顺序搞错，导致字典被当成了 chunk 大小，报 TypeError: 'dict' object cannot be interpreted as an integer。
正确调用姿势：
file_id = fs.upload_from_stream(
"report.pdf",
pdf_bytes,
chunk_size_bytes=255 * 1024,
metadata={"source": "crawler-v3", "retry_count": 0}
)
- 不要写成
upload_from_stream("a.pdf", data, {"tag": "x"})——这会把字典当chunk_size_bytes -
content_type是独立参数，在metadata外面传；它控制 HTTP Content-Type，不影响metadata字段内容 - PyMongo 4.0+ 中，
upload_from_stream返回的是ObjectId，不是整数；别拿它跟旧版返回值对比
更新已有文件的自定义属性安全吗
不安全。GridFS 没有“原子更新文件+元数据”的接口。你只能更新 fs.files 文档里的 metadata，但此时如果另一个客户端正在用 download_to_stream 读这个文件，它拿到的仍是旧元数据（因为读操作不锁 files）。
真正需要改属性的场景，比如打上 “verified: true”，建议：
- 用
fs.files.update_one({"_id": file_id}, {"$set": {"metadata.verified": True}})，但得接受短暂不一致 - 更稳妥的做法是：上传新版本文件，让旧文件留着（靠
filename+metadata.version区分），而不是覆盖 - 绝对不要用
replace_one去整个替换files文档——会丢失 GridFS 内部必需字段如length、chunkSize
最麻烦的其实是并发写同一文件名：GridFS 不校验 filename 唯一性，metadata 也完全由你控制，所以“覆盖”逻辑得自己用事务或应用层锁兜底。
