Overview
在本指南中,您可以学习如何使用PyMongo(MongoDB同步Python驱动程序)通过读取操作从MongoDB集合中检索数据。您可以调用 find() 或 find_one() 方法来检索与一设立条件匹配的文档。
样本数据
本指南中的示例使用Atlas示例数据集中的sample_restaurants.restaurants集合。 要学习;了解如何创建免费的MongoDB Atlas 群集并加载示例数据集,请参阅PyMongo入门教程。
查找文档
PyMongo 包含两种从集合中检索文档的方法: find_one()和find() 。 这些方法采用查询筛选器并返回一个或多个匹配的文档。 查询筛选器是一个对象,用于指定要在查询中检索的文档。
如需了解有关查询过滤器的更多信息,请参阅指定查询。
查找一个文档
要查找集合中的单个文档,请调用find_one()方法并传递查询筛选器,其中指定要查找的文档条件。 如果有多个文档与查询筛选器匹配,则此方法会以 Python 字典的形式从检索到的结果中返回第一个匹配的文档。 如果没有与查询筛选器匹配的文档,该方法将返回None 。
提示
当您知道只有一个匹配文档或者您只对第一个匹配项感兴趣时, find_one()方法非常有用。
以下示例使用 find_one() 方法查找 "cuisine"字段值为 "Bakery" 的第一个文档。选择Synchronous或Asynchronous标签页以查看相应的代码:
restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
restaurant = await sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
查找多个文档
要查找集合中的多个文档,请将查询筛选器传递给 find() 方法,其中指定要检索的文档条件。
以下示例使用 find() 方法查找 "cuisine"字段值为 "Spanish" 的所有文档。
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})
您可以使用游标迭代 find() 方法返回的文档。游标机制允许应用程序迭代数据库结果,同时在给定时间仅将数据库结果的子集保留在内存中。当 find() 方法返回大量文档时,游标非常有用。
您可以使用 for-in 循环遍历游标中的文档,如以下示例所示。选择Synchronous或Asynchronous标签页以查看相应的代码:
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) for restaurant in cursor: ...
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"}) async for restaurant in cursor: ...
注意
查找所有文档
要查找集合中的所有文档,请将空筛选器传递给find()方法:
all_restaurants = sample_restaurants.restaurants.find({})
修改查找行为
您可以通过向find()和find_one()方法传递命名参数来修改它们的行为。 下表描述了常用参数:
Argument | 说明 |
|---|---|
| 限制给定时间游标中要保存的文档数量。 |
| 查找操作的排序规则选项。有关详细信息,请参阅排序规则指南。 |
| |
| 用于查询的索引。 |
| 此操作在服务器上的最长执行时间。 如果超过此时间,PyMongo 将中止操作并引发 |
以下示例使用find()方法查找"cuisine"字段值为"Italian"的所有文档,并将最长执行时间设置为10秒( 10 , 000毫秒):
cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000)
有关可用参数的完整列表,请参阅 API文档 的 find() method。
排序规则
执行查询时,可以指定排序规则,以便驱动程序在对结果进行排序时遵循。
排序规则是一设立特定于语言的字符串比较规则,例如字母大小写和重音符号规则。
要指定排序规则,请创建 Collation 类或Python字典的实例。有关要传递给 Collation 构造函数或作为键包含在字典中的选项列表,请参阅MongoDB Server手册中的排序规则。
提示
导入排序规则
要创建 Collation 类的实例,必须从 pymongo.collation 导入。
以下示例执行与上一示例相同的查找操作,但默认默认规则为 fr_CA:
cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000, collation=Collation(locale="fr_CA"))
或者,您可以通过将 collation() 方法链接到 find() 方法来指定排序规则:
cursor = sample_restaurants.restaurants.find({"cuisine": "Italian"}, max_time_ms=10000) .collation(Collation(locale="fr_CA"))
注意
操作排序规则覆盖默认值
当您在操作中指定排序规则时,它将覆盖集合的默认规则。
无效文档故障排除
如果您尝试查找的文档无效或已损坏,驱动程序会引发 InvalidBSON 异常。以下示例展示了如何对 InvalidBSON 异常进行故障排除并在集合中查找无效文档。
查找集合中的无效文档
以下示例演示如何在遍历集合时识别无效文档。选择 Synchronous 或 Asynchronous标签页,查看相应的代码:
import bson # Use RawBSONDocument to delay BSON decoding raw_coll = collection.with_options( codec_options=collection.codec_options.with_options( document_class=bson.raw_bson.RawBSONDocument ) ) # Iterate through documents and check for BSON errors for doc in raw_coll.find(): try: bson.decode(doc.raw) except bson.errors.InvalidBSON as exc: print(f"Invalid document {exc}, raw bson: {doc.raw}")
import bson # Use RawBSONDocument to delay BSON decoding raw_coll = collection.with_options( codec_options=collection.codec_options.with_options( document_class=bson.raw_bson.RawBSONDocument ) ) # Iterate through documents and check for BSON errors async for doc in raw_coll.find(): try: bson.decode(doc.raw) except bson.errors.InvalidBSON as exc: print(f"Invalid document {exc}, raw bson: {doc.raw}")
查找命令响应中的无效文档
以下示例演示如何处理数据库命令响应中的无效BSON 。选择 Synchronous 或 Asynchronous标签页,查看相应的代码:
import bson # Execute command with raw BSON options res = client.admin.command( "serverStatus", codec_options=bson.raw_bson.DEFAULT_RAW_BSON_OPTIONS ) # Check for BSON errors in the response try: bson.decode(res.raw) except bson.errors.InvalidBSON as exc: print(f"Invalid BSON found in serverStatus response {exc}, raw bson: {res.raw}")
import bson # Execute command with raw BSON options res = await client.admin.command( "serverStatus", codec_options=bson.raw_bson.DEFAULT_RAW_BSON_OPTIONS ) # Check for BSON errors in the response try: bson.decode(res.raw) except bson.errors.InvalidBSON as exc: print(f"Invalid BSON found in serverStatus response {exc}, raw bson: {res.raw}")
更多信息
PyMongoArrow 库允许您将MongoDB查询结果集加载为 Pandas DataFrames 、 NumPy ndarrays 或Apache Arrow Tables 。要学习;了解有关 PyMongoArrow 的更多信息,请参阅PyMongoArrow 文档。
如需了解有关查询过滤器的更多信息,请参阅指定查询。
有关使用PyMongo检索文档的可运行代码示例,请参阅查询。
API 文档
要进一步了解本指南所讨论的任何方法或类型,请参阅以下 API 文档: