class Mongo::Cursor

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

Attributes

view[R]

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

Public Class Methods

new(view, result, server) click to toggle source

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.

@since 2.0.0

# File lib/mongo/cursor.rb, line 55
def initialize(view, result, server)
  @view = view
  @server = server
  @initial_result = result
  @remaining = limit if limited?
end

Public Instance Methods

batch_size() click to toggle source

Get the batch size.

@example Get the batch size.

cursor.batch_size

@return [ Integer ] The batch size.

@since 2.2.0

# File lib/mongo/cursor.rb, line 100
def batch_size
  @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
end
closed?() click to toggle source

Is the cursor closed?

@example Is the cursor closed?

cursor.closed?

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

@since 2.2.0

# File lib/mongo/cursor.rb, line 112
def closed?
  !more?
end
collection_name() click to toggle source

Get the parsed collection name.

@example Get the parsed collection name.

cursor.coll_name

@return [ String ] The collection name.

@since 2.2.0

# File lib/mongo/cursor.rb, line 124
def collection_name
  @coll_name || collection.name
end
each() { |doc| ... } click to toggle source

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

# File lib/mongo/cursor.rb, line 84
def each
  process(@initial_result).each { |doc| yield doc }
  while more?
    return kill_cursors if exhausted?
    get_more.each { |doc| yield doc }
  end
end
id() click to toggle source

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

# File lib/mongo/cursor.rb, line 138
def id
  @cursor_id
end
inspect() click to toggle source

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

# File lib/mongo/cursor.rb, line 70
def inspect
  "#<Mongo::Cursor:0x#{object_id} @view=#{@view.inspect}>"
end
to_return() click to toggle source

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

# File lib/mongo/cursor.rb, line 151
def to_return
  use_limit? ? @remaining : (batch_size || 0)
end

Private Instance Methods

exhausted?() click to toggle source
# File lib/mongo/cursor.rb, line 157
def exhausted?
  limited? ? @remaining <= 0 : false
end
get_more() click to toggle source
# File lib/mongo/cursor.rb, line 161
def get_more
  read_with_retry do
    process(get_more_operation.execute(@server.context))
  end
end
get_more_operation() click to toggle source
# File lib/mongo/cursor.rb, line 167
def get_more_operation
  if @server.features.find_command_enabled?
    Operation::Commands::GetMore.new(Builder::GetMoreCommand.new(self).specification)
  else
    Operation::Read::GetMore.new(Builder::OpGetMore.new(self).specification)
  end
end
kill_cursors() click to toggle source
# File lib/mongo/cursor.rb, line 175
def kill_cursors
  read_with_retry do
    kill_cursors_operation.execute(@server.context)
  end
end
kill_cursors_operation() click to toggle source
# File lib/mongo/cursor.rb, line 181
def kill_cursors_operation
  if @server.features.find_command_enabled?
    Operation::Commands::Command.new(Builder::KillCursorsCommand.new(self).specification)
  else
    Operation::KillCursors.new(Builder::OpKillCursors.new(self).specification)
  end
end
limited?() click to toggle source
# File lib/mongo/cursor.rb, line 189
def limited?
  limit ? limit > 0 : false
end
more?() click to toggle source
# File lib/mongo/cursor.rb, line 193
def more?
  @cursor_id != 0
end
process(result) click to toggle source
# File lib/mongo/cursor.rb, line 197
def process(result)
  @remaining -= result.returned_count if limited?
  @cursor_id = result.cursor_id
  @coll_name ||= result.namespace.sub("#{database.name}.", '') if result.namespace
  result.documents
end
use_limit?() click to toggle source
# File lib/mongo/cursor.rb, line 204
def use_limit?
  limited? && batch_size >= @remaining
end