cursor --用于迭代MongoDB查询结果的工具

在Mongo查询结果上迭代的Cursor类。

class pymongo.cursor.CursorType
NON_TAILABLE

标准光标类型。

TAILABLE

可裁剪光标类型。

可裁剪游标仅用于带帽集合。当检索到最后一个数据时,它们不会关闭,而是保持打开状态,光标位置标记最终文档位置。如果收到更多的数据,光标的迭代将从最后一个收到的文档开始继续。

TAILABLE_AWAIT

设置了等待选项的可裁剪光标。

创建一个可裁剪的游标,它将在返回完整结果集后等待几秒钟,以便捕获和返回在查询期间添加的其他数据。

EXHAUST

排气管光标。

MongoDB将批处理结果流式传输到客户端,而不等待客户端请求每个批处理,从而减少延迟。

class pymongo.cursor.Cursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, manipulate=True, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None)

创建新光标。

不应由应用程序开发人员直接调用-请参阅 find() 相反。

参见

MongoDB文档

cursors

c[index]

__getitem__() .

__getitem__(index)

从该光标获取单个文档或文档片段。

加薪 InvalidOperation 如果此光标已被使用。

要获取单个文档,请使用整型索引,例如:

>>> db.test.find()[50]

IndexError 如果索引为负数或大于此游标中的文档数,则将引发。先前应用于此游标的任何限制都将被忽略。

要获取文档切片,请使用切片索引,例如:

>>> db.test.find()[20:25]

这将返回此光标,限制为 5 跳过 20 应用。使用切片索引将覆盖之前应用于此游标的任何限制或跳过(包括通过以前对此方法的调用应用的限制或跳过)。加薪 IndexError 当切片具有步长、负起始值或小于或等于起始值的停止值时。

参数
  • index :要应用于此光标的整数或切片索引

add_option(mask)

使用位掩码设置任意查询标志。

设置可裁剪标志:cursor.add_选项(二)

property address

使用的服务器的(主机、端口)或无。

在 3.0 版更改: 从“conn_id”重命名。

property alive

这个游标有可能返回更多的数据吗?

这对 tailable cursors 因为他们会停止迭代,即使他们 may 以后返回更多结果。

对于常规游标,只需使用for循环而不是 alive ::

for doc in collection.find():
    print(doc)

注解

即使 alive 是真的, next() 可以提高 StopIteration . alive 在从发生故障的服务器迭代游标时也可以为True。在这种情况下 alive 将在之后返回False next() 无法从服务器检索下一批结果。

allow_disk_use(allow_disk_use)

指定MongoDB在处理阻塞排序操作时是否可以使用临时磁盘文件。

加薪 TypeError 如果 allow_disk_use 不是布尔值。

注解

allow_disk_use 需要服务器版本 >= 4.4

参数
  • allow_disk_use :如果为True,MongoDB可能会在处理分块排序操作时使用临时磁盘文件来存储超过系统内存限制的数据。

3.11 新版功能.

batch_size(batch_size)

限制一批中返回的文档数。每批处理都需要往返服务器。可以对其进行调整以优化性能并限制数据传输。

注解

批处理大小不能覆盖MongoDB在单个批处理中返回给客户端的数据量的内部限制(即,如果将批处理大小设置为1000000000,则MongoDB当前每批只返回4-16MB的结果)。

加薪 TypeError 如果 batch_size 不是整数。加薪 ValueError 如果 batch_size 小于 0 . 加薪 InvalidOperation 如果这样 Cursor 已被使用。最后 batch_size 应用于此光标的优先级为。

参数
  • batch_size :请求的每批结果的大小。

clone()

获取此光标的克隆。

返回一个新的游标实例,其中的选项与在当前实例上设置的选项相匹配。克隆将完全未计算,即使当前实例已部分或完全求值。

close()

显式关闭/终止此光标。

collation(collation)

添加一个 Collation 对此查询。

此选项仅在MongoDB 3.4及更高版本上受支持。

加薪 TypeError 如果 collation 不是的实例 Collation 或A dict . 加薪 InvalidOperation 如果这样 Cursor 已被使用。只有应用于此游标的最后一个排序规则才有任何效果。

参数
property collection

这个 Collection 这个 Cursor 正在迭代。

comment(comment)

向光标添加“注释”。

http://docs.mongodb.org/manual/reference/operator/comment/

参数
  • comment :附加到查询以帮助解释和跟踪服务器日志和配置文件数据中的操作的字符串。

2.7 新版功能.

count(with_limit_and_skip=False)

DEPRECATED -获取此查询的结果集大小。

这个 count() 方法已弃用,并且 not 在事务中支持。请使用 count_documents() 相反。

返回此查询的结果集中的文档数。不需要 limit()skip() 默认情况下计入帐户-设置 with_limit_and_skipTrue 如果这是你想要的行为。加薪 OperationFailure 数据库错误。

当与MongoDB>=2.6一起使用时, count() 使用任何 hint() 应用于查询。在以下示例中,将提示传递给count命令:

集合.查找({'field':'value'}).hint('field_1').count()

这个 count() 方法遵循 read_preferenceCollection 在其上的实例 find() 被叫来。

参数
  • with_limit_and_skip (可选):随便拿 limit()skip() 在获取计数时已将其应用于此游标

注解

这个 with_limit_and_skip 参数需要服务器版本 >= 1.1.4-

在 3.7 版更改: 已弃用。

在 2.8 版更改: 这个 count() 方法现在支持 hint() .

property cursor_id

返回光标的id

如果您需要管理游标ID并希望使用 kill_cursors()

2.2 新版功能.

distinct(key)

获取的不同值列表 key 在此查询的结果集中的所有文档中。

Raises TypeError if key is not an instance of basestring (str in python 3).

这个 distinct() 方法遵循 read_preferenceCollection 在其上的实例 find() 被叫来。

参数
  • key :要获取其不同值的键的名称

explain()

返回此游标的解释计划记录。

注解

从MongoDB 3.2开始 explain() 使用的默认详细模式 explain commandallPlansExecution . 使用不同的详细用法 command() 直接运行explain命令。

参见

MongoDB文档

explain

hint(index)

添加一个“hint”,告诉Mongo用于查询的正确索引。

明智地使用提示可以极大地提高查询性能。对多个字段(至少其中一个字段已编制索引)执行查询时,将索引字段作为提示传递给查询。加薪 OperationFailure 如果提供的提示需要此集合上不存在的索引,则引发 InvalidOperation 如果此光标已被使用。

index 应该是传递给的索引 create_index() (例如) [('field', ASCENDING)] )或者索引的名称。如果 indexNone 此查询的任何现有提示都将被清除。应用于此光标的最后一个提示优先于所有其他提示。

参数
  • index :要提示的索引(作为索引说明符)

在 2.8 版更改: 这个 hint() 方法接受索引的名称。

limit(limit)

限制此光标返回的结果数。

加薪 TypeError 如果 limit 不是整数。加薪 InvalidOperation 如果这样 Cursor 已被使用。最后 limit 应用于此光标的优先级为。限制 0 相当于没有限制。

参数
  • limit :要返回的结果数

参见

MongoDB文档

limit

max(spec)

添加 max 运算符,指定特定索引的上限。

使用时 maxhint() 还应该配置为确保查询使用预期的索引并从mongodb4.2开始 hint() 将是必需的。

参数
  • spec :按顺序指定特定索引的所有键的独占上限的字段、限制对的列表。

在 3.8 版更改: 不推荐使用的游标 max 没有 hint() .

2.7 新版功能.

max_await_time_ms(max_await_time_ms)

上的getMore操作指定时间限制 TAILABLE_AWAIT 光标。对于所有其他类型的游标,最大等待时间忽略。

加薪 TypeError 如果 max_await_time_ms 不是整数或 None . 加薪 InvalidOperation 如果这样 Cursor 已被使用。

注解

max_await_time_ms 需要服务器版本 >= 3.2

参数
  • max_await_time_ms :操作中止后的时间限制

3.2 新版功能.

max_scan(max_scan)

DEPRECATED -限制执行查询时要扫描的文档数。

加薪 InvalidOperation 如果此光标已被使用。只有最后一个 max_scan() 应用于此光标有任何效果。

参数
  • max_scan :要扫描的最大文档数

在 3.7 版更改: 已弃用 max_scan() . MongoDB 4.0不支持此选项。使用 max_time_ms() 而是限制服务器端的执行时间。

max_time_ms(max_time_ms)

指定查询操作的时间限制。如果超过指定的时间,操作将中止,并且 ExecutionTimeout 提高了。如果 max_time_msNone 无限制。

加薪 TypeError 如果 max_time_ms 不是整数或 None . 加薪 InvalidOperation 如果这样 Cursor 已被使用。

参数
  • max_time_ms :操作中止后的时间限制

min(spec)

添加 min 指定特定索引下限的运算符。

使用时 minhint() 还应该配置为确保查询使用预期的索引并从mongodb4.2开始 hint() 将是必需的。

参数
  • spec :按顺序指定特定索引的所有键的包含下限的字段、限制对的列表。

在 3.8 版更改: 不推荐使用的游标 min 没有 hint() .

2.7 新版功能.

next()

向前移动光标。

remove_option(mask)

使用位掩码取消设置任意查询标志。

要取消可裁剪标志:cursor.remove_选项(二)

property retrieved

到目前为止检索到的文档数。

rewind()

将此光标倒回其未赋值状态。

如果已部分或完全计算此光标,请重置它。光标上的任何选项都将保持有效。将来对该游标执行的迭代将导致向服务器发送新的查询,即使结果数据已被此游标检索到。

property session

光标的 ClientSession 或者没有。

3.6 新版功能.

skip(skip)

跳过第一个 skip 此光标的结果。

加薪 TypeError 如果 skip 不是整数。加薪 ValueError 如果 skip 小于 0 . 加薪 InvalidOperation 如果这样 Cursor 已被使用。最后 skip 应用于此光标的优先级为。

参数
  • skip :要跳过的结果数

sort(key_or_list, direction=None)

对该光标的结果进行排序。

传递字段名和方向 ASCENDINGDESCENDING ::

for doc in collection.find().sort('field', pymongo.ASCENDING):
    print(doc)

要按多个字段排序,请传递(键、方向)对的列表:

for doc in collection.find().sort([
        ('field1', pymongo.ASCENDING),
        ('field2', pymongo.DESCENDING)]):
    print(doc)

从MongoDB 2.6版开始,文本搜索结果可以按相关性排序:

cursor = db.test.find(
    {'$text': {'$search': 'some words'}},
    {'score': {'$meta': 'textScore'}})

# Sort by 'score' field.
cursor.sort([('score', {'$meta': 'textScore'})])

for doc in cursor:
    print(doc)

有关更高级的文本搜索功能,请参阅MongoDB Atlas Search .

加薪 InvalidOperation 如果此光标已被使用。只有最后一个 sort() 应用于此光标有任何效果。

参数
  • key_or_list :指定要排序的键的单个键或(键、方向)对列表

  • direction (可选):仅在以下情况下使用 key_or_list 是一个单键,如果没有给出 ASCENDING 假设

where(code)

添加一个 $where 子句。

The code argument must be an instance of basestring (str in python 3) or Code containing a JavaScript expression. This expression will be evaluated for each document scanned. Only those documents for which the expression evaluates to true will be returned as results. The keyword this refers to the object currently being scanned. For example:

# Find all documents where field "a" is less than "b" plus "c".
for doc in db.test.find().where('this.a < (this.b + this.c)'):
    print(doc)

Raises TypeError if code is not an instance of basestring (str in python 3). Raises InvalidOperation if this Cursor has already been used. Only the last call to where() applied to a Cursor has any effect.

注解

MongoDB 4.4放弃了对 Code 使用范围变量。考虑使用 $expr 相反。

参数
  • code :用作筛选器的JavaScript表达式

class pymongo.cursor.RawBatchCursor(collection, filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None)

在BSON数据的原始批上创建一个新的游标/迭代器。

不应由应用程序开发人员直接调用-请参阅 find_raw_batches() 相反。

参见

MongoDB文档

cursors