有一次我帮同事排查一个数据同步脚本全是用命令行写的。逻辑本身并不复杂但每一次改过滤条件都要在一串带转义的 JSON 里小心修改稍不注意少个引号整条命令就废了。当时同事说了一句话让我印象很深“这不是写程序这是手抄数据库。”后来我把这套逻辑换成 pymongo 实现同样的功能变成了几十行可以被调试、被复用、被测试的 Python 代码。这件事让我形成了一个明确判断pymongo 的真正价值不是让你用 Python 连上 MongoDB而是把数据库操作变成可调试、可复用、可纳入业务流程的程序逻辑。今天的主题就是 pymongo 操作 MongoDB 的基础和代码实战。我尽量按照真实项目中会用到的顺序来讲而不是把官方文档里的 CRUD 例子抄一遍。如果你正在跟着“100 天精通 Python”一类的学习计划走到第 40 天遇到数据库这块我希望这篇文章能帮你把“会写 mongo 命令”和“会在项目里用 MongoDB”之间的那道坎跨过去。1. 先想清楚pymongo 解决的到底是什么问题1.1 命令行再熟练也只是“临时操作”命令行工具适合做临时查询和快速验证这是它的优势也是它的局限。比如我想看某个集合里有多少条数据、某个字段的分布情况打开终端敲一条命令几秒钟就出结果。这种场景没有任何问题。但一旦操作开始变得复杂命令行的短板就暴露出来了。你要做条件判断、循环处理、嵌套查询、多步骤更新还要处理网络中断、重复写入、数据校验命令行写起来会非常别扭。你在终端里敲的命令本质上是一条条独立的指令出了错只能重新敲写不进业务系统也没法和别的代码协同工作。还有一个很实际的问题命令行操作数据库时命令本身很难做自动化测试。你没法为一段 mongo shell 命令写单元测试没法做版本管理没法在代码评审里讨论它的参数边界。这在学习和本地演示时没问题一旦进入真实项目就会变成维护成本很高的“手工操作”。1.2 pymongo 不是“翻译器”而是“编程入口”pymongo 做的事情表面上是把 MongoDB 的操作能力搬进 Python 生态。但更深一层它是把数据库操作从“命令”变成“代码模块”。同样是查出所有北京用户并把他们的省份字段补上用命令行写你只能得到一次性的执行结果用 pymongo 写你就可以把这段逻辑封装成函数def update_province_by_city(city: str, province: str): result collection.update_many( {city: city}, {$set: {province: province}} ) return result.modified_count之后你可以反复调用这个函数可以给它写单元测试可以在调用前加参数校验可以在调用后把处理结果写入日志。这才是 pymongo 真正改变的地方它把临时性的数据库操作变成了软件开发流程里一个有输入、有输出、可维护的组件。所以我的建议是学习 pymongo 的时候不要只盯着单条语法和命令行对应关系而是多想一想——“如果我这段数据库操作要放到项目里运行还缺什么”。能想清楚这个问题你的水平就已经超过了不少刚接触 MongoDB 的开发者。2. 环境准备装好驱动之后先确认 MongoDB 真的活着2.1 安装 pymongo先确认 Python 和 pip 环境pymongo 的安装本身很简单常规情况下执行pip install pymongo就够了。如果你用的是pipenv、poetry、conda这类环境管理工具就按对应工具的安装方式操作原理一样。这里有一个值得注意的点pymongo 对 Python 版本有要求。较新版本的 pymongo 通常要求 Python 3.7 或更高如果你还在用一个很老的 Python 版本装的时候可能会遇到依赖冲突。建议至少在 Python 3.10 及以上版本上学习和使用能让很多莫名其妙的小问题直接消失。另外如果你的连接字符串是mongodbsrv://这种 DNS Seedlist 形式还需要额外安装dnspythonpip install dnspython这个不是必选项但如果你用的是 MongoDB Atlas 或者通过 SRV 记录接入的 MongoDB 服务缺了它就会报DNS lookup failed之类的错误。所以安装完 pymongo 之后最好确认一下自己实际会用到的连接方式再决定是否要补装这个依赖。2.2 连接前的检查清单服务、端口、认证、网络很多第一次用 pymongo 的同学代码写得没问题但就是连不上或者拿到一个“假连接对象”后执行操作才报错。这里的原因大多不在 Python 端而在 MongoDB 服务本身。下面是一份连接前建议先确认的检查清单检查项怎么确认常见问题mongod 进程是否启动命令行执行mongod --version或查看系统进程服务没启动连接直接拒绝监听端口是否正常本机27017端口是否被占用netstat或lsof查看端口冲突或被防火墙拦截连接字符串是否正确确认 host、port、用户名、密码、认证库写错一个字符结果完全不同是否需要认证检查 MongoDB 是否启用了--auth或配置文件里的security.authorization没认证却传了账号或反过来网络是否通是否能 ping 通目标机器安全组是否放行分布式部署时最常见的问题排查顺序建议固定下来先看报错内容再看服务端状态再看连接字符串再看网络最后回到 Python 环境。不要一上来就怀疑是 pymongo 的问题。很多情况下pymongo 只是一个非常老实的客户端它把服务端、网络、认证的真实情况原封不动地抛给了你。3. 第一次连接理解三个对象和“懒惰创建”机制3.1 最小连接代码MongoClient、database、collectionpymongo 里有三个核心对象分别对应 MongoDB 里的三层结构from pymongo import MongoClient client MongoClient(mongodb://localhost:27017/) db client[mydb] collection db[users]第一行创建MongoClient表示和 MongoDB 服务端的连接入口第二行从客户端里拿到一个数据库对象注意这里的mydb即使还不存在也不会报错第三行拿到一个集合对象users集合同样可以是不存在的。这里值得多解释一句MongoClient(mongodb://localhost:27017/)这一行代码执行的时候并不会真的立刻发起网络连接。它是惰性的真正建立连接发生在第一次执行实际数据库操作时。这也是很多人“连接不报错但一操作就报错”的原因。如果你需要在创建客户端的时候就验证服务是否可达可以用ping命令client.admin.command(ping)这个方法会在客户端已经产生连接的前提下向 MongoDB 发送一个探测请求。如果服务不可达它会抛出ServerSelectionTimeoutError带你进入下一轮排查。3.2 “懒惰创建”是什么为什么数据库要插入之后才出现MongoDB 有一个和关系型数据库非常不一样的设计数据库和集合在使用之前不需要手动创建。你第一次向某个集合插入文档时如果数据库或集合还不存在它会自动创建。也就是说下面这段代码db client[mydb] collection db[users]执行完以后你去 MongoDB 里查可能根本找不到mydb和users。这很正常只有当你真正执行了insert_one或insert_many数据落盘之后数据库和集合才会实体化。这个机制带来了很大便利降低了起步门槛。但也容易产生误解有同学会以为是自己连接写错了或者 MongoDB 数据丢失了。实际上它只是“按照设计在运行”。注意MongoDB 只有在第一次写入文档时才会真正创建数据库和集合。连接时看不到库并不代表连错了。3.3 连接参数里值得先了解的三个超时、认证、连接池MongoClient的构造函数支持很多参数新手阶段不需要全记住但有三个建议先理解第一个是serverSelectionTimeoutMS。它控制“选择可用服务节点”的超时时间默认通常是 30000 毫秒。如果你的网络环境不太稳定或者不希望程序卡在数据库连接上太久可以把这个值调小比如client MongoClient( mongodb://localhost:27017/, serverSelectionTimeoutMS5000 )第二个是认证参数。如果 MongoDB 开启了账号认证连接字符串里通常写成这样client MongoClient(mongodb://user:passwordlocalhost:27017/admin)这里有个容易搞混的地方/admin表示认证库是admin而不是你要操作的业务库。如果账号是在某个特定业务库下创建的认证库就要指向那个库否则会报认证失败。第三个是连接池。MongoClient内部默认维护了一个连接池多个线程可以复用同一个客户端不需要每次操作都新建连接。默认的maxPoolSize通常够用你只要记住一点不要在每次请求里都 new 一个 MongoClient那是把连接池的价值直接浪费掉了。4. 增删改查代码实战从“会写命令”到“会写程序”4.1 插入insert_one 和 insert_many以及怎么使用返回结果先从一个最简单的插入开始user { name: 张三, age: 25, city: 北京 } result collection.insert_one(user) print(result.inserted_id)insert_one会为文档自动生成一个_id默认是ObjectId类型。返回值result.inserted_id就是这条新文档的主键。如果你想在插入后立即拿到文档的 ID用它最方便。批量插入用insert_manyusers [ {name: 李四, age: 30, city: 上海}, {name: 王五, age: 22, city: 广州}, ] result collection.insert_many(users) print(result.inserted_ids)批量插入的性能要比循环调用insert_one高很多因为它在一次网络请求里发送了多条数据。但也要注意单次批量插入的数据量不宜过大如果你有几十万条数据要写入最好分批提交避免单个请求体过大导致服务端拒绝或内存压力过高。4.2 查询find_one、find 和游标的基本规律查询的第一步是find_one它返回一个字典找不到时返回Noneuser collection.find_one({name: 张三}) print(user)find_one适合已知主键或唯一条件的场景。如果条件可能匹配多条数据而你只想要第一条它也够用。查询多条数据用findusers collection.find({age: {$gt: 20}}) for user in users: print(user)注意find返回的不是一个列表而是一个Cursor游标对象。游标是“惰性”的只有当你开始遍历它时数据才会从服务端分批取到本地。这个设计的好处是即使查询结果有几十万条内存也不会被一次性打满。在实际写代码时如果确实需要把所有结果放到列表里可以写list(collection.find(...))但要明确这样做会把全部数据加载到内存数据量大时要谨慎。4.3 更新update_one、update_many 与 $set 的使用边界更新操作是最容易踩坑的地方。很多人第一次写更新时会写成这样# 错误示例 collection.update_one({name: 张三}, {age: 26})这段代码的问题是MongoDB 会认为第二个参数是要替换成的新文档而不是对旧文档的修改指令。所以这种写法会直接报错因为更新文档里必须使用操作符开头比如$set、$inc、$push等。正确的写法是result collection.update_one( {name: 张三}, {$set: {age: 26}} ) print(result.modified_count)使用$set的含义是只修改匹配到的文档中的指定字段其他字段保持不变。这一点非常重要因为一旦你直接传一个新文档就会把整条文档替换掉之前存在的其他字段会全部丢失。批量更新用update_manyresult collection.update_many( {city: 北京}, {$set: {province: 北京市}} ) print(result.modified_count)modified_count表示实际发生了修改的文档数。如果匹配到了文档但内容和目标一致这个值可能是 0。另外update_one和update_many都支持upsertTrue参数含义是“如果匹配不到就插入一条新文档”适合某些“有则更新、无则写入”的业务场景。4.4 删除delete_one、delete_many以及“先查再删”的习惯删除操作相对简单result collection.delete_one({name: 张三}) print(result.deleted_count) result collection.delete_many({age: {$lt: 18}}) print(result.deleted_count)如果条件为空字典delete_many({})会清空整个集合这是一条很危险的操作。实际项目里除非你真的确定要清空数据否则不要这么写。建议在删除之前先使用find或count_documents确认一下影响范围删除操作没有撤销的余地。同时删除操作也会触发索引、日志、级联逻辑等连锁反应尤其是生产环境里有多个服务共用同一个库时更要谨慎。5. 进阶操作排序、分页、聚合和索引该怎么选5.1 排序和分页sort、skip、limit 的常见组合查询结果排序用sort分页用skip和limitusers collection.find( {city: 北京} ).sort(age, -1).skip(0).limit(10) for user in users: print(user)这里的sort(age, -1)表示按age字段倒序排列1表示升序。skip(0)表示跳过前 0 条limit(10)表示只取 10 条。这套写法很适合中小规模数据的常规分页。但它有一个隐患skip的 offset 越大MongoDB 需要扫描并丢弃的数据就越多性能会明显下降。如果你要处理的数据量很大更稳妥的方式是基于_id或某个时间字段做游标分页比如last_id ObjectId(64f1a2b3c4d5e6f7a8b9c0d1) users collection.find( {_id: {$gt: last_id}, city: 北京} ).sort(_id, 1).limit(10)这种方式能避免深分页的性能问题但实现起来会稍微复杂一点。学习阶段先用skip limit理解原理生产环境再根据数据规模决定是否改进。5.2 聚合管道什么时候真的需要用 aggregate普通的find只能做条件过滤、字段投影和排序如果要做分组统计、字段拼接、跨集合关联这类复杂计算就要用到聚合管道。聚合管道的核心是把多个处理步骤以列表的形式串联起来数据依次经过每个阶段被加工。一个简单的统计示例pipeline [ {$match: {city: 北京}}, {$group: {_id: $city, avg_age: {$avg: $age}}}, {$sort: {avg_age: -1}} ] for doc in collection.aggregate(pipeline): print(doc)这个管道先过滤出北京用户再按城市分组计算平均年龄最后按平均年龄倒序输出。和普通查询相比聚合管道更适合报表统计、数据清洗、跨集合关联等复杂场景。但我的建议是不要为了用聚合而用聚合。如果一条普通查询能解决就先用普通查询。聚合管道的学习成本和排查成本都更高而且某些复杂管道写完之后过几个月再回头看可能自己都看不懂。遇到性能问题也从简单的$match尽量前移开始排查。5.3 索引查询变慢时最优先检查的往往是索引当你发现某个查询越跑越慢第一反应不应该是去优化代码逻辑而是先看查询条件里的字段有没有建索引。MongoDB 的索引和关系型数据库类似它用额外的存储空间换取查询性能。创建索引的常见写法collection.create_index([(city, 1)]) collection.create_index([(city, 1), (age, -1)])第一条表示在city字段上创建升序索引第二条表示在city和age上创建联合索引其中age是倒序。索引创建好后查询引擎可以更快速地定位目标数据而不必全集合扫描。但索引也不是越多越好。每多一个索引写入数据时数据库都需要额外维护索引结构写性能会下降磁盘占用也会增加。在实际项目里先根据查询需求建索引再通过日志和慢查询观察效果避免盲目加索引。6. 最容易踩坑的五个细节提前避开比事后排查更重要6.1 ObjectId 不是字符串序列化时容易翻车MongoDB 默认生成的_id是ObjectId类型它在 Python 里不是字符串doc collection.find_one({name: 张三}) print(doc[_id]) # ObjectId(64f1a2b3c4d5e6f7a8b9c0d1) print(type(doc[_id])) # class bson.objectid.ObjectId如果你直接把这个字典交给json.dumps会报ObjectId is not JSON serializable。这是新手非常常见的问题。解决办法有几种转换时手动把_id转成字符串str(doc[_id])使用 pymongo 提供的工具bson.json_util.dumps(doc)它能序列化 ObjectId、datetime 等 BSON 类型在输出给前端前统一做一层数据格式化。6.2 更新时直接赋新文档会把未提到的字段全部丢掉这个坑在 4.3 已经提过但值得单独强调一次。很多人写更新时会自然联想到“查询到文档然后改一下”的过程于是写成了doc collection.find_one({name: 张三}) doc[age] 26 collection.update_one({name: 张三}, doc)这段逻辑本身没错但它有一个隐患如果在这段代码执行前另一个进程刚好修改了doc里其他字段你这样的整文档更新会把新改动覆盖掉。更安全的做法是始终使用$set只更新你关心的字段collection.update_one( {name: 张三}, {$set: {age: 26}} )这个差异在并发场景下尤其重要。单机学习时看不出来一上线就可能变成数据丢失事故。6.3 insert_many 大批量写入要理解 ordered 参数和部分成功insert_many默认是orderedTrue也就是按顺序插入一旦某一条出错后续所有插 
长河君 · 2026/9/1 19:31:44 · 阅读 1.2k pymongo实战指南：用Python高效操作MongoDB的核心技巧
有一次我帮同事排查一个数据同步脚本全是用命令行写的。逻辑本身并不复杂但每一次改过滤条件都要在一串带转义的 JSON 里小心修改稍不注意少个引号整条命令就废了。当时同事说了一句话让我印象很深“这不是写程序这是手抄数据库。”后来我把这套逻辑换成 pymongo 实现同样的功能变成了几十行可以被调试、被复用、被测试的 Python 代码。这件事让我形成了一个明确判断pymongo 的真正价值不是让你用 Python 连上 MongoDB而是把数据库操作变成可调试、可复用、可纳入业务流程的程序逻辑。今天的主题就是 pymongo 操作 MongoDB 的基础和代码实战。我尽量按照真实项目中会用到的顺序来讲而不是把官方文档里的 CRUD 例子抄一遍。如果你正在跟着“100 天精通 Python”一类的学习计划走到第 40 天遇到数据库这块我希望这篇文章能帮你把“会写 mongo 命令”和“会在项目里用 MongoDB”之间的那道坎跨过去。1. 先想清楚pymongo 解决的到底是什么问题1.1 命令行再熟练也只是“临时操作”命令行工具适合做临时查询和快速验证这是它的优势也是它的局限。比如我想看某个集合里有多少条数据、某个字段的分布情况打开终端敲一条命令几秒钟就出结果。这种场景没有任何问题。但一旦操作开始变得复杂命令行的短板就暴露出来了。你要做条件判断、循环处理、嵌套查询、多步骤更新还要处理网络中断、重复写入、数据校验命令行写起来会非常别扭。你在终端里敲的命令本质上是一条条独立的指令出了错只能重新敲写不进业务系统也没法和别的代码协同工作。还有一个很实际的问题命令行操作数据库时命令本身很难做自动化测试。你没法为一段 mongo shell 命令写单元测试没法做版本管理没法在代码评审里讨论它的参数边界。这在学习和本地演示时没问题一旦进入真实项目就会变成维护成本很高的“手工操作”。1.2 pymongo 不是“翻译器”而是“编程入口”pymongo 做的事情表面上是把 MongoDB 的操作能力搬进 Python 生态。但更深一层它是把数据库操作从“命令”变成“代码模块”。同样是查出所有北京用户并把他们的省份字段补上用命令行写你只能得到一次性的执行结果用 pymongo 写你就可以把这段逻辑封装成函数def update_province_by_city(city: str, province: str): result collection.update_many( {city: city}, {$set: {province: province}} ) return result.modified_count之后你可以反复调用这个函数可以给它写单元测试可以在调用前加参数校验可以在调用后把处理结果写入日志。这才是 pymongo 真正改变的地方它把临时性的数据库操作变成了软件开发流程里一个有输入、有输出、可维护的组件。所以我的建议是学习 pymongo 的时候不要只盯着单条语法和命令行对应关系而是多想一想——“如果我这段数据库操作要放到项目里运行还缺什么”。能想清楚这个问题你的水平就已经超过了不少刚接触 MongoDB 的开发者。2. 环境准备装好驱动之后先确认 MongoDB 真的活着2.1 安装 pymongo先确认 Python 和 pip 环境pymongo 的安装本身很简单常规情况下执行pip install pymongo就够了。如果你用的是pipenv、poetry、conda这类环境管理工具就按对应工具的安装方式操作原理一样。这里有一个值得注意的点pymongo 对 Python 版本有要求。较新版本的 pymongo 通常要求 Python 3.7 或更高如果你还在用一个很老的 Python 版本装的时候可能会遇到依赖冲突。建议至少在 Python 3.10 及以上版本上学习和使用能让很多莫名其妙的小问题直接消失。另外如果你的连接字符串是mongodbsrv://这种 DNS Seedlist 形式还需要额外安装dnspythonpip install dnspython这个不是必选项但如果你用的是 MongoDB Atlas 或者通过 SRV 记录接入的 MongoDB 服务缺了它就会报DNS lookup failed之类的错误。所以安装完 pymongo 之后最好确认一下自己实际会用到的连接方式再决定是否要补装这个依赖。2.2 连接前的检查清单服务、端口、认证、网络很多第一次用 pymongo 的同学代码写得没问题但就是连不上或者拿到一个“假连接对象”后执行操作才报错。这里的原因大多不在 Python 端而在 MongoDB 服务本身。下面是一份连接前建议先确认的检查清单检查项怎么确认常见问题mongod 进程是否启动命令行执行mongod --version或查看系统进程服务没启动连接直接拒绝监听端口是否正常本机27017端口是否被占用netstat或lsof查看端口冲突或被防火墙拦截连接字符串是否正确确认 host、port、用户名、密码、认证库写错一个字符结果完全不同是否需要认证检查 MongoDB 是否启用了--auth或配置文件里的security.authorization没认证却传了账号或反过来网络是否通是否能 ping 通目标机器安全组是否放行分布式部署时最常见的问题排查顺序建议固定下来先看报错内容再看服务端状态再看连接字符串再看网络最后回到 Python 环境。不要一上来就怀疑是 pymongo 的问题。很多情况下pymongo 只是一个非常老实的客户端它把服务端、网络、认证的真实情况原封不动地抛给了你。3. 第一次连接理解三个对象和“懒惰创建”机制3.1 最小连接代码MongoClient、database、collectionpymongo 里有三个核心对象分别对应 MongoDB 里的三层结构from pymongo import MongoClient client MongoClient(mongodb://localhost:27017/) db client[mydb] collection db[users]第一行创建MongoClient表示和 MongoDB 服务端的连接入口第二行从客户端里拿到一个数据库对象注意这里的mydb即使还不存在也不会报错第三行拿到一个集合对象users集合同样可以是不存在的。这里值得多解释一句MongoClient(mongodb://localhost:27017/)这一行代码执行的时候并不会真的立刻发起网络连接。它是惰性的真正建立连接发生在第一次执行实际数据库操作时。这也是很多人“连接不报错但一操作就报错”的原因。如果你需要在创建客户端的时候就验证服务是否可达可以用ping命令client.admin.command(ping)这个方法会在客户端已经产生连接的前提下向 MongoDB 发送一个探测请求。如果服务不可达它会抛出ServerSelectionTimeoutError带你进入下一轮排查。3.2 “懒惰创建”是什么为什么数据库要插入之后才出现MongoDB 有一个和关系型数据库非常不一样的设计数据库和集合在使用之前不需要手动创建。你第一次向某个集合插入文档时如果数据库或集合还不存在它会自动创建。也就是说下面这段代码db client[mydb] collection db[users]执行完以后你去 MongoDB 里查可能根本找不到mydb和users。这很正常只有当你真正执行了insert_one或insert_many数据落盘之后数据库和集合才会实体化。这个机制带来了很大便利降低了起步门槛。但也容易产生误解有同学会以为是自己连接写错了或者 MongoDB 数据丢失了。实际上它只是“按照设计在运行”。注意MongoDB 只有在第一次写入文档时才会真正创建数据库和集合。连接时看不到库并不代表连错了。3.3 连接参数里值得先了解的三个超时、认证、连接池MongoClient的构造函数支持很多参数新手阶段不需要全记住但有三个建议先理解第一个是serverSelectionTimeoutMS。它控制“选择可用服务节点”的超时时间默认通常是 30000 毫秒。如果你的网络环境不太稳定或者不希望程序卡在数据库连接上太久可以把这个值调小比如client MongoClient( mongodb://localhost:27017/, serverSelectionTimeoutMS5000 )第二个是认证参数。如果 MongoDB 开启了账号认证连接字符串里通常写成这样client MongoClient(mongodb://user:passwordlocalhost:27017/admin)这里有个容易搞混的地方/admin表示认证库是admin而不是你要操作的业务库。如果账号是在某个特定业务库下创建的认证库就要指向那个库否则会报认证失败。第三个是连接池。MongoClient内部默认维护了一个连接池多个线程可以复用同一个客户端不需要每次操作都新建连接。默认的maxPoolSize通常够用你只要记住一点不要在每次请求里都 new 一个 MongoClient那是把连接池的价值直接浪费掉了。4. 增删改查代码实战从“会写命令”到“会写程序”4.1 插入insert_one 和 insert_many以及怎么使用返回结果先从一个最简单的插入开始user { name: 张三, age: 25, city: 北京 } result collection.insert_one(user) print(result.inserted_id)insert_one会为文档自动生成一个_id默认是ObjectId类型。返回值result.inserted_id就是这条新文档的主键。如果你想在插入后立即拿到文档的 ID用它最方便。批量插入用insert_manyusers [ {name: 李四, age: 30, city: 上海}, {name: 王五, age: 22, city: 广州}, ] result collection.insert_many(users) print(result.inserted_ids)批量插入的性能要比循环调用insert_one高很多因为它在一次网络请求里发送了多条数据。但也要注意单次批量插入的数据量不宜过大如果你有几十万条数据要写入最好分批提交避免单个请求体过大导致服务端拒绝或内存压力过高。4.2 查询find_one、find 和游标的基本规律查询的第一步是find_one它返回一个字典找不到时返回Noneuser collection.find_one({name: 张三}) print(user)find_one适合已知主键或唯一条件的场景。如果条件可能匹配多条数据而你只想要第一条它也够用。查询多条数据用findusers collection.find({age: {$gt: 20}}) for user in users: print(user)注意find返回的不是一个列表而是一个Cursor游标对象。游标是“惰性”的只有当你开始遍历它时数据才会从服务端分批取到本地。这个设计的好处是即使查询结果有几十万条内存也不会被一次性打满。在实际写代码时如果确实需要把所有结果放到列表里可以写list(collection.find(...))但要明确这样做会把全部数据加载到内存数据量大时要谨慎。4.3 更新update_one、update_many 与 $set 的使用边界更新操作是最容易踩坑的地方。很多人第一次写更新时会写成这样# 错误示例 collection.update_one({name: 张三}, {age: 26})这段代码的问题是MongoDB 会认为第二个参数是要替换成的新文档而不是对旧文档的修改指令。所以这种写法会直接报错因为更新文档里必须使用操作符开头比如$set、$inc、$push等。正确的写法是result collection.update_one( {name: 张三}, {$set: {age: 26}} ) print(result.modified_count)使用$set的含义是只修改匹配到的文档中的指定字段其他字段保持不变。这一点非常重要因为一旦你直接传一个新文档就会把整条文档替换掉之前存在的其他字段会全部丢失。批量更新用update_manyresult collection.update_many( {city: 北京}, {$set: {province: 北京市}} ) print(result.modified_count)modified_count表示实际发生了修改的文档数。如果匹配到了文档但内容和目标一致这个值可能是 0。另外update_one和update_many都支持upsertTrue参数含义是“如果匹配不到就插入一条新文档”适合某些“有则更新、无则写入”的业务场景。4.4 删除delete_one、delete_many以及“先查再删”的习惯删除操作相对简单result collection.delete_one({name: 张三}) print(result.deleted_count) result collection.delete_many({age: {$lt: 18}}) print(result.deleted_count)如果条件为空字典delete_many({})会清空整个集合这是一条很危险的操作。实际项目里除非你真的确定要清空数据否则不要这么写。建议在删除之前先使用find或count_documents确认一下影响范围删除操作没有撤销的余地。同时删除操作也会触发索引、日志、级联逻辑等连锁反应尤其是生产环境里有多个服务共用同一个库时更要谨慎。5. 进阶操作排序、分页、聚合和索引该怎么选5.1 排序和分页sort、skip、limit 的常见组合查询结果排序用sort分页用skip和limitusers collection.find( {city: 北京} ).sort(age, -1).skip(0).limit(10) for user in users: print(user)这里的sort(age, -1)表示按age字段倒序排列1表示升序。skip(0)表示跳过前 0 条limit(10)表示只取 10 条。这套写法很适合中小规模数据的常规分页。但它有一个隐患skip的 offset 越大MongoDB 需要扫描并丢弃的数据就越多性能会明显下降。如果你要处理的数据量很大更稳妥的方式是基于_id或某个时间字段做游标分页比如last_id ObjectId(64f1a2b3c4d5e6f7a8b9c0d1) users collection.find( {_id: {$gt: last_id}, city: 北京} ).sort(_id, 1).limit(10)这种方式能避免深分页的性能问题但实现起来会稍微复杂一点。学习阶段先用skip limit理解原理生产环境再根据数据规模决定是否改进。5.2 聚合管道什么时候真的需要用 aggregate普通的find只能做条件过滤、字段投影和排序如果要做分组统计、字段拼接、跨集合关联这类复杂计算就要用到聚合管道。聚合管道的核心是把多个处理步骤以列表的形式串联起来数据依次经过每个阶段被加工。一个简单的统计示例pipeline [ {$match: {city: 北京}}, {$group: {_id: $city, avg_age: {$avg: $age}}}, {$sort: {avg_age: -1}} ] for doc in collection.aggregate(pipeline): print(doc)这个管道先过滤出北京用户再按城市分组计算平均年龄最后按平均年龄倒序输出。和普通查询相比聚合管道更适合报表统计、数据清洗、跨集合关联等复杂场景。但我的建议是不要为了用聚合而用聚合。如果一条普通查询能解决就先用普通查询。聚合管道的学习成本和排查成本都更高而且某些复杂管道写完之后过几个月再回头看可能自己都看不懂。遇到性能问题也从简单的$match尽量前移开始排查。5.3 索引查询变慢时最优先检查的往往是索引当你发现某个查询越跑越慢第一反应不应该是去优化代码逻辑而是先看查询条件里的字段有没有建索引。MongoDB 的索引和关系型数据库类似它用额外的存储空间换取查询性能。创建索引的常见写法collection.create_index([(city, 1)]) collection.create_index([(city, 1), (age, -1)])第一条表示在city字段上创建升序索引第二条表示在city和age上创建联合索引其中age是倒序。索引创建好后查询引擎可以更快速地定位目标数据而不必全集合扫描。但索引也不是越多越好。每多一个索引写入数据时数据库都需要额外维护索引结构写性能会下降磁盘占用也会增加。在实际项目里先根据查询需求建索引再通过日志和慢查询观察效果避免盲目加索引。6. 最容易踩坑的五个细节提前避开比事后排查更重要6.1 ObjectId 不是字符串序列化时容易翻车MongoDB 默认生成的_id是ObjectId类型它在 Python 里不是字符串doc collection.find_one({name: 张三}) print(doc[_id]) # ObjectId(64f1a2b3c4d5e6f7a8b9c0d1) print(type(doc[_id])) # class bson.objectid.ObjectId如果你直接把这个字典交给json.dumps会报ObjectId is not JSON serializable。这是新手非常常见的问题。解决办法有几种转换时手动把_id转成字符串str(doc[_id])使用 pymongo 提供的工具bson.json_util.dumps(doc)它能序列化 ObjectId、datetime 等 BSON 类型在输出给前端前统一做一层数据格式化。6.2 更新时直接赋新文档会把未提到的字段全部丢掉这个坑在 4.3 已经提过但值得单独强调一次。很多人写更新时会自然联想到“查询到文档然后改一下”的过程于是写成了doc collection.find_one({name: 张三}) doc[age] 26 collection.update_one({name: 张三}, doc)这段逻辑本身没错但它有一个隐患如果在这段代码执行前另一个进程刚好修改了doc里其他字段你这样的整文档更新会把新改动覆盖掉。更安全的做法是始终使用$set只更新你关心的字段collection.update_one( {name: 张三}, {$set: {age: 26}} )这个差异在并发场景下尤其重要。单机学习时看不出来一上线就可能变成数据丢失事故。6.3 insert_many 大批量写入要理解 ordered 参数和部分成功insert_many默认是orderedTrue也就是按顺序插入一旦某一条出错后续所有插