Class Mongo::Cursor
In: lib/mongo/cursor.rb
lib/mongo/cursor/builder/get_more_command.rb
lib/mongo/cursor/builder/kill_cursors_command.rb
lib/mongo/cursor/builder/op_kill_cursors.rb
lib/mongo/cursor/builder/op_get_more.rb
Parent: Object

Client-side representation of an iterator over a query result set on the server.

A Cursor is not created directly by a user. Rather, CollectionView creates a Cursor in an Enumerable module method.

@example Get an array of 5 users named Emily. 

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

@example Call a block on each user doc. 

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

@note The Cursor API is semipublic. @api semipublic

Methods

batch_size   closed?   collection_name   each   finalize   id   inspect   new   to_return   try_next  

Included Modules

Enumerable Retryable

Classes and Modules

Module Mongo::Cursor::Builder

Attributes

view  [R]  @return [ Collection::View ] view The collection view.

Public Class methods

finalize(cursor_id, cluster, op_spec, server, session)

Finalize the cursor for garbage collection. Schedules this cursor to be included in a killCursors operation executed by the Cluster‘s CursorReaper.

@example Finalize the cursor. 

  Cursor.finalize(id, cluster, op, server)

@param [ Integer ] cursor_id The cursor‘s id. @param [ Mongo::Cluster ] cluster The cluster associated with this cursor and its server. @param [ Hash ] op_spec The killCursors operation specification. @param [ Mongo::Server ] server The server to send the killCursors operation to.

@return [ Proc ] The Finalizer.

@since 2.3.0

new(view, result, server, options = {})

Creates a Cursor object.

@example Instantiate the cursor. 

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

@param [ CollectionView ] view The CollectionView defining the query. @param [ Operation::Result ] result The result of the first execution. @param [ Server ] server The server this cursor is locked to. @param [ Hash ] options The cursor options.

@option options [ true, false ] :disable_retry Whether to disable 

  retrying on error when sending getMores.

@since 2.0.0

Public Instance methods

batch_size()

Get the batch size.

@example Get the batch size. 

  cursor.batch_size

@return [ Integer ] The batch size.

@since 2.2.0

closed?()

Is the cursor closed?

@example Is the cursor closed? 

  cursor.closed?

@return [ true, false ] If the cursor is closed.

@since 2.2.0

collection_name()

Get the parsed collection name.

@example Get the parsed collection name. 

  cursor.coll_name

@return [ String ] The collection name.

@since 2.2.0

each() {|doc| ...}

Iterate through documents returned from the query.

@example Iterate over the documents in the cursor. 

  cursor.each do |doc|
    ...
  end

@return [ Enumerator ] The enumerator.

@since 2.0.0

id()

Get the cursor id.

@example Get the cursor id. 

  cursor.id

@note A cursor id of 0 means the cursor was closed on the server.

@return [ Integer ] The cursor id.

@since 2.2.0

inspect()

Get a human-readable string representation of Cursor.

@example Inspect the cursor. 

  cursor.inspect

@return [ String ] A string representation of a Cursor instance.

@since 2.0.0

to_return()

Get the number of documents to return. Used on 3.0 and lower server versions.

@example Get the number to return. 

  cursor.to_return

@return [ Integer ] The number of documents to return.

@since 2.2.0

try_next()

Return one document from the query, if one is available.

Retries once on a resumable error.

This method will wait up to max_await_time_ms milliseconds for changes from the server, and if no changes are received it will return nil.

@note This method is experimental and subject to change.

@return [ BSON::Document | nil ] A document. @api private

[Validate]