对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单

查找文档

在本指南中,您可以学习如何使用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" 的第一个文档。选择SynchronousAsynchronous标签页以查看相应的代码:

restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
restaurant = await sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})

提示

排序顺序

如果未指定排序条件,find_one() 方法将按自然顺序返回磁盘上的第一份文档。

要学习;了解有关排序的更多信息,请参阅排序指南。

要查找集合中的多个文档,请将查询筛选器传递给 find() 方法,其中指定要检索的文档条件。

以下示例使用 find() 方法查找 "cuisine"字段值为 "Spanish" 的所有文档。

cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})

您可以使用游标迭代 find() 方法返回的文档。游标机制允许应用程序迭代数据库结果,同时在给定时间仅将数据库结果的子集保留在内存中。当 find() 方法返回大量文档时,游标非常有用。

您可以使用 for-in 循环遍历游标中的文档,如以下示例所示。选择SynchronousAsynchronous标签页以查看相应的代码:

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
说明

batch_size

限制给定时间游标中要保存的文档数量。

collation

查找操作的排序规则选项。有关详细信息,请参阅排序规则指南。

comment

要附加到查询的字符串。这可以帮助您跟踪和解释服务器日志和配置文件数据中的操作。要学习;了解有关查询注释的更多信息,请参阅MongoDB Server手册中的游标.comment() 页面。

hint

用于查询的索引。

max_time_ms

此操作在服务器上的最长执行时间。 如果超过此时间,PyMongo 将中止操作并引发ExecutionTimeout

以下示例使用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 异常进行故障排除并在集合中查找无效文档。

以下示例演示如何在遍历集合时识别无效文档。选择 SynchronousAsynchronous标签页,查看相应的代码:

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 。选择 SynchronousAsynchronous标签页,查看相应的代码:

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 文档: