[翻译]PyMongo官方文档

PyMongo官方文档翻译

周煦辰 2016-06-30

原文地址见链接：原文地址

PyMongo是一个用于MongoDB的Python工具，也是一个被推荐的Python操作MongoDB数据库的方式。

使用步骤

安装PyMongo

Linux或者OS X系统

你可以只用pip工具安装：

pip install pymongo

Windows系统下

使用Windows安装工具，详见https://pypi.python.org/pypi/pymongo/。

引入pymongo

在一个Python交互shell中完成此过程，或者也可以在其他Python环境中完成，例如Python脚本、Python模块、Python项目。

从pymongo中引入MongoClicent。

from pymongo import MongoClient

创建一个连接

使用MongoClient创建一个连接：

client = MongoClient()

如果你没有特别为MongoClient指定参数，MongoClient将使用MongoDB默认参数即localhost接口和27017端口。

你可以使用一个完整的MongoDB URI来定义连接：

client = MongoClient("mongodb://mongodb0.example.net:27019")

这个MongoClient代表了一个运行于mongodb.example.net端口号为27019的MongoDB连接。

访问数据库对象

第一个你用pymongo来交互的基本类是

Database

，它代表了MongoDB中的数据库(database)结构。数据库保存了逻辑上相关的集合组。MongoDB将在第一次使用新的数据库的时候自动创建它。

你可以使用属性访问的方式，赋值一个数据库（例如名字为

primer

）给本地变量

db

，如下所示：

db = client.primer

你也可以使用字典形式访问一个数据库，这会移除Python特有的命名限制，如下所示：

db = client['primer']

访问集合对象

第二个你将使用pymongo进行交互的基本类是

Collection

，它代表了MongoDB中的集合（collection）结构。集合（collection）保存了逻辑上相关的文档组。

你可以直接使用字典形式访问集合或者通过一个访问一个数据库对象的属性来访问集合，如下所示：

db.dataset
db['dataset']

你也可以给一个变量进行赋值，以在其他地方使用这个集合，如下所示：

coll = db.dataset
coll = db['dataset']

使用PyMongo插入数据

概览

你可以使用

insert_one()

方法和

insert_many()

方法来向MongoDB的集合中插入文档。如果你所插入的集合在MongoDB中不存在，MongoDB将为你自动创建一个集合。

先决条件

在Python命令行或者IDLE中，使用MongoClient连接一个正在运行的MongoDB实例，且已经打开

test

数据库。

from pymongo import MongoClient

client = MongoClient()
db = client.test

插入一个文档

向集合

restaurants

中插入一个文档。如果集合不存在，这个操作将创建一个新的集合。

from datetime import datetime
result = db.restaurants.insert_one(
{
"address": {
"street": "2 Avenue",
"zipcode": "10075",
"building": "1480",
"coord": [-73.9557413, 40.7720266]
},
"borough": "Manhattan",
"cuisine": "Italian",
"grades": [
{
"date": datetime.strptime("2014-10-01", "%Y-%m-%d"),
"grade": "A",
"score": 11
},
{
"date": datetime.strptime("2014-01-16", "%Y-%m-%d"),
"grade": "B",
"score": 17
}
],
"name": "Vella",
"restaurant_id": "41704620"
}
)

这个操作返回了一个InsertOneResult对象，它包括了

insert_id

属性表示被插入的文档的

_id

。访问

insert_id

的方式如下：

result.inserted_id

你插入的文档的ObjectId将和如下所示的不同。

ObjectId("54c1478ec2341ddf130f62b7")

如果你传递给

insert_one()

方法的参数不包含

_id

字段，MongoClient将自动添加这个字段并且生成一个ObjectId设置为这个字段的值。

使用PyMongo查询数据

概览

你可以通过

find()

方法产生一个查询来从MongoDB的集合中查询到数据。MongoDB中所有的查询条件在一个集合中都有一个范围。

查询可以返回在集合中的所有数据或者只返回符合筛选条件（filter）或者标准（criteria）的文档。你可以在文档中指定过滤器或者标准，并作为参数传递给

find()

方法。

find()

方法返回一个查询结果的游标，这是一个产生文档的迭代对象。

先决条件

本示例中使用

test

数据库中的

restaurants

集合。与使用示例数据填充集合有关的介绍请见Import Example Dataset。

在Python命令行或者IDLE中，使用MongoClient连接一个正在运行的MongoDB实例，且已经打开

test

数据库。

from pymongo import MongoClient

client = MongoClient()
db = client.test

在一个集合中查询所有文档

调用

find()

方式不需要传值即可得到集合中所有的文档。举例来说，如下所示的操作即是返回

restaurants

集合中所有文档。

cursor = db.restaurants.find()

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果包含了所有

restaurants

集合中的所有文档。

指定相等条件

对某一个字段的相等条件查询有如下形式：

{ <field1>: <value1>, <field2>: <value2>, ... }

如果字段（

<field>

）在某个文档的某一个数组内，则使用点操作符（dot notation）去访问该字段。

使用一个顶级字段进行查询

如下所示的操作将查询

borough

字段等于

Manhattan

的文档。

cursor = db.restaurants.find({"borough": "Manhattan"})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

在一个嵌入式的文档中查询

要指定嵌入文档中的字段的查询条件，需要使用点操作符。使用点操作符需要使用双引号将字段名包裹。下面的操作将指定一个文档的地址字典中的邮编字段的一个相等的条件。

cursor = db.restaurants.find({"address.zipcode": "10075"})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

更多的关于嵌入式文档的查询条件信息，请参阅Embedded Documents。

在一个数组中查询

grades

数组包含一个嵌入式文档作为其元素。在该文档的字段上指定一个相等条件需要用到点操作符。使用点操作符需要使用双引号将字段名包裹。如下所示的查询将查询一个有嵌入式文档的

grades

字段，该字段中的

grade

等于

B

。

cursor = db.restaurants.find({"grades.grade": "B"})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

更多的关于数组内查询条件的信息，例如数组中特殊的混合条件，请参阅Array及$elemMatch操作符。

使用操作符指定条件

MongoDB支持使用操作符指定查询条件，例如比较操作符。虽然这其中有一些例外，例如

$or

和

$and

条件操作符。使用操作符进行查询一般有如下形式：

{ <field1>: { <operator1>: <value1> } }

完整的操作符列表请查阅

query opeartors

(http://docs.mongodb.org/manual/reference/operator/query)。

大于（$gt）操作符

查询字段

grades

包含一个嵌入式文档，其中

score

大于30。

cursor = db.restaurants.find({"grades.score": {"$gt": 30}})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

小于（$lt）操作符

查询字段

grades

包含一个嵌入式文档，其中

score

小于10。

cursor = db.restaurants.find({"grades.score": {"$lt": 10}})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

组合条件

你可以使用逻辑与（AND）或者逻辑或（OR）组合多个查询条件。

逻辑与

你可以使用一个列表指定一个逻辑与条件查询操作，使用逗号分隔条件。

cursor = db.restaurants.find({"cuisine": "Italian", "address.zipcode": "10075"})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

逻辑或

你可以使用

$or

操作符进行逻辑或条件的指定。

cursor = db.restaurants.find(
{"$or": [{"cuisine": "Italian"}, {"address.zipcode": "10075"}]})

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件的文档。

对结果进行排序

要指定结果集的顺序，可以通过追加

sort()

方法进行查询。给

sort()

方法传递需要排序的字段和配需类型等。

pymongo.ASCENDING

表示升序排序。

pymongo.DESCENDING

表示降序排序。

如果要通过多个键星星排序，可以传递键的列表和以及对应的排序类型的列表。举例来说，如下操作将返回

restaurants

集合中所有的文档，并且先通过

borough

字段进行升序排序，然后在每个

borough

内，通过

"address.zipcode"

字段进行升序排序。

import pymongo
cursor = db.restaurants.find().sort([
("borough", pymongo.ASCENDING),
("address.zipcode", pymongo.ASCENDING)
])

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将只包含符合条件且经过排序的文档。

使用PyMongo更新数据

概览

你可以使用

update_one()

和

update_many

方法更新集合中的文档。

update_one()

方法一次更新一个文档。使用

update_many()

方法可以更新所有符合条件的文档。方法接受以下三个参数：

一个筛选器，可以对符合条件的文档进行更新。

一个指定的修改语句

自定义更新时的操作参数

要指定更新时的过滤器，使用和查询条件时相同的结构即可。参见使用PyMongo查询数据获取查询条件的信息。

你不能更新

_id

字段。

先决条件

本示例中使用

test

数据库中的

restaurants

集合。与使用示例数据填充集合有关的介绍请见Import Example Dataset。

在Python命令行或者IDLE中，使用MongoClient连接一个正在运行的MongoDB实例，且已经打开

test

数据库。

from pymongo import MongoClient

client = MongoClient()
db = client.test

更新特定的字段

要改变一个特定字段的值，MongoDB提供了更新操作符，例如

$set

操作符可以修改值。例如

$set

之类的操作符将在没有该字段的时候新建这个字段。可以查阅update operators作为参考。

更新顶级字段

如下操作将更新第一个符合

name

等于

Juni

这个条件的文档。使用

$set

操作符更新

cuisine

字段且将

lastModified

修改为当前日期。

result = db.restaurants.update_one(
{"name": "Juni"},
{
"$set": {
"cuisine": "American (New)"
},
"$currentDate": {"lastModified": True}
}
)

这个操作返回了一个UpdateResult对象。这个对象报告了符合条件的文档数目以及被修改的文档数目。

要查看符合筛选器条件的文档数目，通过访问

UpdateResult

对象的

matched_count

属性。

result.matched_count

matched_count

值为：

1

要查看更新操作中被修改的文档数目，通过访问

UpdateResult

对象的

modified_count

属性。

modified_count

值为：

1

更新嵌入式文档中的字段

要更新一个嵌入式文档中的字段，需要使用点操作符。当使用点操作符时，使用点操作符需要使用双引号将字段名包裹。下面的操作将更新

address

字段中的

street

值。

result = db.restaurants.update_one(
{"restaurant_id": "41156888"},
{"$set": {"address.street": "East 31st Street"}}
)

这个操作返回了一个

UpdateResult

对象。这个对象报告了符合条件的文档数目以及被修改的文档数目。

要查看符合筛选器条件的文档数目，通过访问

UpdateResult

对象的

matched_count

属性。

result.matched_count

matched_count

值为：

1

要查看更新操作中被修改的文档数目，通过访问

UpdateResult

对象的

modified_count

属性。

modified_count

值为：

1

更新多个文档

update_one()

方法更新了一个文档，要更新多个文档，需要使用

update_many()

方法。下面的操作将更新所有的

address.zipcode

等于

10016

以及

cuisine

等于

Other

的文档，将

cuisine

字段设置为

Category To Be Determined

以及将

lastModified

更新为当前日期。

result = db.restaurants.update_many(
{"address.zipcode": "10016", "cuisine": "Other"},
{
"$set": {"cuisine": "Category To Be Determined"},
"$currentDate": {"lastModified": True}
}
)

这个操作返回了一个

UpdateResult

对象。这个对象报告了符合条件的文档数目以及被修改的文档数目。

要查看符合筛选器条件的文档数目，通过访问

UpdateResult

对象的

matched_count

属性。

result.matched_count

matched_count

值为：

20

要查看更新操作中被修改的文档数目，通过访问

UpdateResult

对象的

modified_count

属性。

modified_count

值为：

20

替换一个文档

要替换整个文档（除了

_id

字段），将一个完整的文档作为第二个参数传给

update()

方法。替代文档对应原来的文档可以有不同的字段。在替代文档中，你可以忽略

_id

字段因为它是不变的。如果你包含了

_id

字段，那它必须和原文档的值相同。


在如下的更新操作后，被修改的文档将只剩下

_id

、

name

和

address

字段。该文档将不再包含

restaurant_id

、

cuisine

、

grades

以及

borough

字段。

result = db.restaurants.replace_one(
{"restaurant_id": "41704620"},
{
"name": "Vella 2",
"address": {
"coord": [-73.9557413, 40.7720266],
"building": "1480",
"street": "2 Avenue",
"zipcode": "10075"
}
}
)

replace_one

操作返回了一个

UpdateResult

对象。这个对象报告了符合条件的文档数目以及被修改的文档数目。

要查看符合筛选器条件的文档数目，通过访问

UpdateResult

对象的

matched_count

属性。

result.matched_count

matched_count

值为：

20

要查看更新操作中被修改的文档数目，通过访问

UpdateResult

对象的

modified_count

属性。

modified_count

值为：

20

使用PyMongo删除数据

概览

你可以使用

delete_one()

以及

delete_many()

方法从集合中删除文档。方法需要一个条件来确定需要删除的文档。

要指定一个删除条件，使用和查询条件时相同的结构即可。参见使用PyMongo查询数据获取查询条件的信息。

先决条件

本示例中使用

test

数据库中的

restaurants

集合。与使用示例数据填充集合有关的介绍请见Import Example Dataset。

在Python命令行或者IDLE中，使用MongoClient连接一个正在运行的MongoDB实例，且已经打开

test

数据库。

from pymongo import MongoClient

client = MongoClient()
db = client.test

步骤

删除所有符合条件的文档

下面的操作将删除所有复合条件的文档。

result = db.restaurants.delete_many({"borough": "Manhattan"})

这个操作返回了一个DeleteResult对象。这个对象报告了被删除的文档数目。

要查看被删除的文档数目，通过访问

DeleteResult

对象的

deleted_count

属性。

result.deleted_count

deleted_count

值为：

10259

如果你已经插入或者更新了文档，那么你得到的结果将和示例不同。

删除所有文档

要删除一个集合中的所有文档，给

delete_many()

方法传递一个空的条件参数即可。

result = db.restaurants.delete_many({})

这个操作返回了一个DeleteResult对象。这个对象报告了被删除的文档数目。

要查看被删除的文档数目，通过访问

DeleteResult

对象的

deleted_count

属性。

result.deleted_count

deleted_count

值为：

15100

如果你已经插入或者更新了文档，那么你得到的结果将和示例不同。

销毁一个集合

删除所有文档的操作只会清空集合中的文档。该集合以及集合的索引将依旧存在。要清空一个集合，销毁该集合以及它的索引并且重建集合和索引可能是相比于清空一个集合更加高效的操作方式。使用

drop()

方法可以销毁一个集合，包括它所有的索引。

db.restaurants.drop()

使用PyMongo进行数据聚合

概览

MongoDB可以进行数据聚合操作，例如可以针对某一字段进行分组或者对某一字段不同的值进行统计。

使用

aggregate()

方法可以使用基于步骤的聚合操作。

appregate()

方法接受多个数组作为每一步的操作。每一个阶段按照顺序处理，描述了对数据操作的步骤。

db.collection.aggregate([<stage1>, <stage2>, ...])

先决条件

这部分的例子使用了

test

数据库中的

restaurants

集合。需要查看在集合中填充的实例数据，请参阅Import Example Dataset。

在Python命令行或者IDLE中，使用MongoClient连接一个正在运行的MongoDB实例，且已经打开

test

数据库。

from pymongo import MongoClient

client = MongoClient()
db = client.test

根据一个字段分组文件并计算总数

使用

$group

操作符去利用一个指定的键进行分组。在

$group

操作中，指定需要分组的字段为

_id

。

$group

通过字段路径访问字段，该字段需要有一个美元符号

$

作为前缀。

$group

操作可以使用累加器对本次分组进行计算。下面的例子将使用

borough

字段对

restaurants

集合进行操作，并且使用

$sum

累加器进行文档的统计计算。

cursor = db.restaurants.aggregate(
[
{"$group": {"_id": "$borough", "count": {"$sum": 1}}}
]
)

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将由如下文档组成：

{u'count': 969, u'_id': u'Staten Island'}
{u'count': 6086, u'_id': u'Brooklyn'}
{u'count': 10259, u'_id': u'Manhattan'}
{u'count': 5656, u'_id': u'Queens'}
{u'count': 2338, u'_id': u'Bronx'}
{u'count': 51, u'_id': u'Missing'}

_id

字段包含了不同的

borough

值，即根据键的值进行了分组。

筛选并分组文档

使用

$match

操作来删选文档。

$match

使用MongoDB查询语法。下面的管道使用

$match

来对

restaurants

进行一个

borough

等于

"Queens"

且

cuisine

等于

Brazilian

的查询。接着

$group

操作对命中的文档使用

address.zipcode

字段分组并使用

$sum

进行统计。

$group

通过字段路径访问字段，该字段需要有一个美元符号

$

作为前缀。

cursor = db.restaurants.aggregate(
[
{"$match": {"borough": "Queens", "cuisine": "Brazilian"}},
{"$group": {"_id": "$address.zipcode", "count": {"$sum": 1}}}
]
)

迭代游标（cursor）并且打印文档内容。

for document in cursor:
print(document)

结果将由如下文档组成：

{u'count': 1, u'_id': u'11368'}
{u'count': 3, u'_id': u'11106'}
{u'count': 1, u'_id': u'11377'}
{u'count': 1, u'_id': u'11103'}
{u'count': 2, u'_id': u'11101'}

_id

字段包含了不同的

zipcode

值，即根据键的值进行了分组。

PyMongo上的索引

概览

索引可以对查询的高效执行起到支持。如果没有索引，MongoDB必须进行全表扫描，即扫描集合中的每个文档，来选择符合查询条件的文档。如果一个适当的索引存在于一个查询中，MongoDB可以使用索引限制必须检查文档的数量。

使用

create_index()

方法来为一个集合创建索引。所以可以对查询的高效执行起到支持。MongoDB会在创建文档的时候自动为

_id

字段创建索引。

要为一个或多个字段创建索引，使用一个包含字段和索引类型的列表作为参数：

[ ( <field1>: <type1> ), ... ]

要创建一个升序的索引，指定

pymongo.ASCENDING

为索引类型（）。

要创建一个降序的索引，指定

pymongo.DESCENDING

为索引类型（）。

create_index()

只会在索引不存在的时候创建一个索引。

先决条件

下面的例子将使用

test

数据库中的

restaurants

集合。需要查看在集合中填充的实例数据，请参阅Import Example Dataset。

在Python命令行或者IDLE中，使用MongoClient连接一个正在运行的MongoDB实例，且已经打开

test

数据库。

from pymongo import MongoClient

client = MongoClient()
db = client.test

创建一个单字段索引

在

restaurants

集合中的

cuisine

字段上创建自增的索引。

import pymongo
db.restaurants.create_index([("cuisine", pymongo.ASCENDING)])

该方法将返回被创建的索引的名字。

"u'cuisine_1'"

创建一个复合索引

MongoDB支持在多个字段上创建符合索引。这几个字段的命令将声明这个索引包含的键。举个例子，下面的操作将在

cuisine

字段和

address.zipcode

字段上创建一个复合索引。该索引将先对

cuisine

的值输入一个升序的命令，然后对

address.zipcode

的值输入一个降序命令。

import pymongo
db.restaurants.create_index([
("cuisine", pymongo.ASCENDING),
("address.zipcode", pymongo.DESCENDING)
])

该方法将返回被创建的索引的名字。

"u'cuisine_1_address.zipcode_-1'"