mongodb的upsert是原子性“查+插/改”操作，python中通过update_one()等方法传upsert=true启用；需建唯一索引、用$setoninsert补默认字段，并检查upserted_id判断是否插入。
什么是MongoDB的upsert，Python里怎么触发
MongoDB本身没有叫 upsert() 的独立方法，Python驱动（pymongo）里所有写操作方法都通过 upsert=True 参数启用upsert行为。关键不是调用哪个函数，而是选对写入方法并传对参数。
最常用的是 update_one() 和 update_many()；replace_one() 也能 upsert，但语义不同——它会整个文档替换，不保留未指定字段。
-
update_one({"_id": 123}, {"$set": {"name": "Alice"}}, upsert=True)：只更新匹配文档的name字段，没匹配到就新建一个带_id: 123和name: "Alice"的文档 -
replace_one({"email": "a@b.com"}, {"email": "a@b.com", "status": "active"}, upsert=True)：完全替换整条记录，旧字段（比如created_at）会被丢掉
为什么用 update_one() 而不是 insert_one() + 异常捕获
手动先查再插或捕获 DuplicateKeyError 看似直观，但有竞态风险：两个进程同时查不到、同时插入，必然失败一个。upsert 是原子操作，MongoDB 在服务端一次完成“查+插/改”，天然避免重复。
另外，异常捕获方式在高并发下性能更差——每次失败都要走一遍网络往返和异常栈开销。
- 必须确保查询条件字段（如
email）建了唯一索引，否则upsert=True不会阻止重复插入，只会多建几条 - 如果没建唯一索引，
upsert=True的行为等价于“只 update，不 insert”，不会报错也不会警告 - 索引命令示例：
db.users.createIndex({"email": 1}, {"unique": true})
upsert=True 下如何控制新文档的字段结构
upsert 新建文档时，只包含你显式写进更新器（第二个参数）里的字段。比如 update_one({"uid": 100}, {"$set": {"score": 95}}, upsert=True)，新建文档只有 uid 和 score，不会有 _id（MongoDB 自动加）、也不会有 created_at 这类你想默认带上的字段。
要保证新建文档结构完整，得把所有必需字段都塞进更新器里，或者用 $setOnInsert 操作符做条件赋值。
- 推荐写法：
update_one({"uid": 100}, {"$set": {"score": 95}, "$setOnInsert": {"created_at": datetime.now(), "status": "new"}}, upsert=True) -
$setOnInsert只在真正插入时生效，更新已有文档时被忽略，比硬编码所有字段更安全 - 注意：时间要用
datetime.utcnow()或带时区对象，避免本地时区导致数据不一致
常见错误：upsert 后拿不到新插入文档的 _id
update_one() 返回的是 UpdateResult 对象，它有 upserted_id 属性，但**仅当本次操作确实触发了插入时才有值**；如果只是更新，这个值是 None。
别想当然地认为每次 upsert 都能拿到 _id，也别试图从返回结果里取 inserted_id（那是 insert_one() 才有的）。
- 正确检查方式：
result = coll.update_one(...); if result.upserted_id is not None: print("新插入，_id =", result.upserted_id) - 如果业务强依赖新文档
_id，且查询条件不含_id，建议显式指定_id字段，比如{"_id": ObjectId(), "email": "x@y.com"}，这样即使 upsert 插入，也能提前知道 ID - 别用
find_one_and_update(..., upsert=True)试图“返回文档”——它只返回更新前或更新后的文档，不返回新插入文档的完整快照
upsert 看似简单，实际踩坑多在索引缺失、字段控制不严、以及误判返回值上。最稳的做法是：先建好唯一索引，用 $setOnInsert 补全默认字段，再严格检查 upserted_id 是否存在。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
