类：Mongo::Cursor Private

继承：
对象
  • 对象
显示全部
扩展方式：
可转发
包括：
可枚举、可重试
定义于：
lib/mongo/cursor.rb,
lib/mongo/cursor/kill_spec.rb,
lib/mongo/cursor/nontailable.rb

Overview

此类是私有 API 的一部分。 应尽可能避免使用此类，因为它将来可能会被删除或更改。

针对服务器上查询结果设立的迭代器的客户端表示形式。

Cursor 对象不直接公开给应用程序代码。 相反， Collection::View向应用程序公开Enumerable接口，并且枚举器由Cursor实例支持。

例子：

获取名为 Emily 的5用户大量。

users.find({:name => 'Emily'}).limit(5).to_a

在每个用户文档上调用一个区块。

users.find.each { |doc| puts doc }

直接已知子类

缓存游标

在命名空间下定义

模块： NonTailable 类： KillSpec

实例属性摘要折叠

类方法摘要折叠

实例方法摘要折叠

Retryable 中包含的方法

#read_worker 、 #select_server 、 #write_worker

构造函数详情

#initialize (view, result, server, options = {}) ⇒游标

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

创建一个Cursor对象。

例子：

实例化游标。

Mongo::Cursor.new(view, response, server)

参数：

  • 查看 ( CollectionView ) —

    定义查询的CollectionView 。

  • 结果 ( Operation::Result ) —

    第一次执行的结果。

  • server ( MongoDB Server ) —

    此游标锁定到的服务器。

  • 选项 （哈希） （默认为： {} ） —

    游标选项。

选项哈希 ( options )：

  • :context （Operation::Context） —

    此游标的操作上下文。

  • :disable_retry ( true , false ) —

    发送 getMore 操作时是否禁用出错重试（已弃用，不再重试 getMore 操作）

  • :retry_reads ( true , false ) —

    重试读取（遵循现代机制），默认值为 true

由于：

  • 2.0.0



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/ Mongo/ 游标.rb', 第 74 行

def 初始化(查看, 结果, server, 选项 = {})
  除非 结果.is_a?(操作::结果)
    提高 ArgumentError, "第二个参数必须是 Mongo::Operation::Result: #{ result .inspect } } "
  end

  @view = 查看
  @server = server
  @initial_result = 结果
  @namespace = 结果.namespace
  @remaining = limit if 有限？
  set_cursor_id(结果)
  if @cursor_id.nil?
    提高 ArgumentError, '游标 ID 必须出现在结果中'
  end
  @options = 选项
  @session = @options[:session]
  @connection_global_id = 结果.connection_global_id
  @context = @options[:context]&。通过(connection_global_id: connection_global_id_for_context) || fresh_context
  @explicitly_close = false
  锁 = 互斥锁.new
  if server.load_balancer？
    # 只有在负载均衡拓扑结构结构中，我们才需要游标中的连接；
    # 否则，我们不需要对它进行额外的引用。
    @connection = @initial_result.连接
  end
  if 已关闭？
    check_in_connection
  else
    报名
    ObjectSpace.define_finalizer(
      self,
      self.class.finalize(kill_spec(@connection_global_id), 集群)
    )
  end
end

实例属性详细信息

# 连接 ⇒ 对象（只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



117
118
119
 
# File 'lib/ Mongo/ 游标.rb', 第 117 行

def 连接
  @connection
end

# context ="Operation::Context (readonly)"

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回 context 此游标的上下文。

返回：



53
54
55
 
# File 'lib/ Mongo/ 游标.rb', 第 53 行

def 上下文
  @context
end

#initial_result ⇒对象（只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



114
115
116
 
# File 'lib/ Mongo/ 游标.rb', 第 114 行

def Initial_result
  @initial_result
end

#resume_token ⇒ BSON::Document | nil （只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

游标跟踪的用于变更流恢复的恢复令牌

返回：

  • ( BSON::Document | nil ) —

    游标恢复令牌。



50
51
52
 
# File 'lib/ Mongo/ 游标.rb', 第 50 行

def resume_token
  @resume_token
end

# server ⇒对象（只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



111
112
113
 
# File 'lib/ Mongo/ 游标.rb', 第 111 行

def server
  @server
end

# view ⇒ Collection::View (readonly)

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回视图集合视图。

返回：



44
45
46
 
# File 'lib/ Mongo/ 游标.rb', 第 44 行

def 查看
  @view
end

类方法详细信息

。 finalize (kill_spec, cluster) ⇒ Proc

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

完成游标以进行垃圾回收。 安排此游标包含在由集群的 CursorReaper 执行的 killCursors 操作中。

参数：

返回：

  • ( Proc ) —

    终结器。



128
129
130
131
132
133
134
135
 
# File 'lib/ Mongo/ 游标.rb', 第 128 行

def self.finalize(kill_spec, 集群)
  除非 KillSpec === kill_spec
    提高 ArgumentError, " 第一个参数必须是 KillSpec: # { kill_spec .inspect } } "
  end
  proc do
    集群.schedule_kill_cursor(kill_spec)
  end
end

实例方法详细信息

# batch_size ⇒整数

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取批处理大小。

例子：

获取批处理大小。

cursor.batch_size

返回：

  • ( Integer ) —

    批量大小。

由于：

  • 2.2.0



279
280
281
282
283
284
285
286
 
# File 'lib/ Mongo/ 游标.rb', 第 279 行

def batch_size
  值 = @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
  if 值 == 0
    nil
  else
    值
  end
end

# close (opts = {}) ⇒ nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

关闭此游标，从而释放客户端和服务器上的所有关联资源。

返回：

  • ( nil ) —

    始终为零。



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/ Mongo/ 游标.rb', 第 305 行

def 关闭(opts = {})
  return if 已关闭？

  ctx = 上下文 ? 上下文.刷新(timeout_ms: opts[:timeout_ms]) : fresh_context(opts)

  取消注册
  read_with_one_retry do
    spec = {
      coll_name: collection_name,
      db_name: database.名称,
      cursor_id: [id],
    }
    op = 操作::killCursors.new(spec)
    execute_operation(op, 上下文： ctx)
  end

  nil
救援 错误::OperationFailure::家庭情况, 错误::SocketError, 错误::SocketTimeoutError, 错误::ServerNotUsable
  # 错误被吞掉，因为无法通过处理错误来完成。
确保
  end_session
  @cursor_id = 0
  锁.同步 do
    @explicitly_close = true
  end
  check_in_connection
end

#已关闭？ ⇒ true , false

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

游标是否已关闭？

例子：

游标是否已关闭？

cursor.closed?

返回：

  • ( true , false ) —

    如果游标已关闭。

由于：

  • 2.2.0



296
297
298
299
 
# File 'lib/ Mongo/ 游标.rb', 第 296 行

def 已关闭？
  # 原则上，@cursor_id 不应为 nil
  @cursor_id.nil? || @cursor_id == 0
end

# collection_name ⇒ string

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取解析的集合名称。

例子：

获取解析的集合名称。

cursor.coll_name

返回：

  • ( string ) —

    collection名称。

由于：

  • 2.2.0



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/ Mongo/ 游标.rb', 第 341 行

def collection_name
  # 在大多数情况下，这相当于集合的名称
  #驾驶员中的对象。 但是，在某些情况下（例如，当连接
  # 到Atlas Data Lake），find 命令返回的命名空间
  # 可能不同，这就是为什么我们要使用基于集合名称的
  # 命令结果中的命名空间。
  if @namespace
    # 通常，命名空间的集合为“ 数据库 ”。
    # 但是，有时集合名称会包含句点，这
    # 就是该方法连接第一个之后的所有命名空间组件的原因。
    ns_components = @namespace.拆分(' 。 ')
    ns_components[1...ns_components.长度].连接 (JOIN)(' 。 ')
  else
    集合.名称
  end
end

#each ⇒枚举器

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

遍历从查询返回的文档。

一个游标最多只能迭代一次。 不完整迭代也是允许的。 尝试多次迭代游标会引发 InvalidCursorOperation。

例子：

遍历游标中的文档。

cursor.each do |doc|
  ...
end

返回：

  • (枚举器) —

    枚举器。

由于：

  • 2.0.0



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ Mongo/ 游标.rb', 第 163 行

def 每

  # 如果我们已经遍历了第一批（即调用了 get_more
  # 至少一次），服务器端的游标已前进到
  # 第一个批处理，然后从头开始重新启动迭代
  # 返回初始结果会丢失第二批处理中的文档
  # 和后续批处理，直到游标所在的位置。 检测此
  # 条件并中止迭代。
  #
  # 在未来的驾驶员版本中，每个驱动程序要么从
  # 上一次迭代结束，或者始终从
  # 开始。
  if @get_more_used
    提高 错误::InvalidCursorOperation, '无法重新启动发出 getMore 的游标的迭代'
  end

  # 保持与2.10之前版本的兼容性 驱动程序版本，重置
  # 每次开始新的迭代时，文档大量。
  @documents = nil

  if block_given?
    # 由 try_next 引发的 StopIteration 会结束此循环。
    循环 do
      文档 = try_next
      if 明确关闭？
        提高 错误::InvalidCursorOperation, '游标已显式关闭'
      end
      产量 文档 if 文档
    end
    self
  else
    文档 = []
    # 由 try_next 引发的 StopIteration 会结束此循环。
    循环 do
      文档 = try_next
      if 明确关闭？
        提高 错误::InvalidCursorOperation, '游标已显式关闭'
      end
      文档 << 文档 if 文档
    end
    文档
  end
end

# full_iterated? ⇒布尔

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回：

  • （布尔值） 


416
417
418
 
# File 'lib/ Mongo/ 游标.rb', 第 416 行

def full_iterated?
  !!@Fully_iterated
end

# get_more ⇒ Array<BSON::Document>

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

执行 getMore 命令并返回从服务器获取的批处理文档。

返回：

  • ( Array<BSON::Document> ) —

    批处理文档



391
392
393
394
395
396
397
398
399
400
 
# File 'lib/ Mongo/ 游标.rb', 第 391 行

def get_more
  @get_more_used = true

  # 现代可重试读取规范禁止重试 getMores。
  # 用于重试 getMores 的传统可重试读取逻辑，但由于
  # 这样做可能会导致静默数据丢失，驾驶员不再重试
  # 在任何情况下都可以执行 getMore 操作。
  # https://github.com/mongodb/species/blob/master/source/retryable-reads/retryable-reads.md#qa
  处理(execute_operation(get_more_operation))
end

#id ⇒ Integer

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

游标ID 为0表示游标已在服务器上关闭。

获取游标 ID。

例子：

获取游标 ID。

cursor.id

返回：

  • ( Integer ) —

    游标 ID。

由于：

  • 2.2.0



368
369
370
 
# File 'lib/ Mongo/ 游标.rb', 第 368 行

def id
  @cursor_id
end

#检查⇒ string

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取 Cursor 的人类可读string表示形式。

例子：

检查游标。

cursor.inspect

返回：

  • ( string ) —

    Cursor 实例的string表示形式。

由于：

  • 2.0.0



145
146
147
 
# File 'lib/ Mongo/ 游标.rb', 第 145 行

def 检查
  " #<Mongo::Cursor: 0 x #{ object_id } @view= #{ @view .inspect } } > "
end

# kill_spec (connection_global_id) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/ Mongo/ 游标.rb', 第 403 行

def kill_spec(connection_global_id)
  KillSpec.new(
    cursor_id: id,
    coll_name: collection_name,
    db_name: database.名称,
    connection_global_id: connection_global_id,
    server_address: server.地址,
    会话： @session,
    连接： @connection
  )
end

#to_return ⇒ Integer

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取要返回的文档数量。 用于3.0及更低版本的服务器。

例子：

获取要返回的数字。

cursor.to_return

返回：

  • ( Integer ) —

    要返回的文档数量。

由于：

  • 2.2.0



381
382
383
 
# File 'lib/ Mongo/ 游标.rb', 第 381 行

def to_return
  use_limit? ? @remaining : (batch_size || 0)
end

# try_next ⇒ BSON::Document | nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

此方法是实验性的，可能会发生变化。

从查询中返回一份文档（如果有）。

此方法将等待来自服务器的更改长达 max_await_time_ms 毫秒，如果没有收到更改，将返回 nil。 如果没有更多文档可从服务器返回，或者游标已耗尽，则会引发 StopIteration 异常。

返回：

  • ( BSON::Document | nil ) —

    一个文档。

引发：

  • ( StopIteration ) —

    在游标完全迭代后进行调用时引发此警报。



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/ Mongo/ 游标.rb', 第 223 行

def try_next
  if @documents.nil?
    # 由于已发布的 Mongoid 版本具有旧驾驶员游标的副本
    # 代码，当 Mongoid查询时，不会调用 #进程中的 dup 调用
    # 缓存处于活动状态。 通过在此处同时调用 dup 来解决此问题
    # 可能来自 Mongoid 代码的 #进程的结果。
    @documents = 处理(@initial_result).dup
    # 这里的文档可以是空数组，因此
    # 我们最终可能会在第一次 try_next 调用中发出 getMore
  end

  if @documents.空？
    # 对于空批次，我们缓存批处理恢复令牌
    cache_batch_resume_token

    除非 已关闭？
      if 精疲力尽？
        关闭
        @Fully_iterated = true
        提高 StopIteration
      end
      @documents = get_more
    else
      @Fully_iterated = true
      提高 StopIteration
    end
  else
    # 游标在此处已关闭
    # 将文档保留为空大量
  end

  # 如果至少有一个文档，则缓存其_id
  if @documents[0]
    cache_resume_token(@documents[0])
  end

  # 如果要迭代，则缓存批处理恢复令牌
  # 超过最后一个文档，或者如果批次为空
  if @documents.size <= 1
    cache_batch_resume_token
    if 已关闭？
      @Fully_iterated = true
    end
  end

  return @documents.转变
end