Class: Mongo::Cursor

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable, Retryable
Defined in:
lib/mongo/cursor.rb,
lib/mongo/cursor/builder/op_get_more.rb,
lib/mongo/cursor/builder/op_kill_cursors.rb,
lib/mongo/cursor/builder/get_more_command.rb,
lib/mongo/cursor/builder/kill_cursors_command.rb

Overview

Note:

The Cursor API is semipublic.

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.

Examples:

Get an array of 5 users named Emily.

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

Call a block on each user doc.

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

Defined Under Namespace

Modules: Builder

Constant Summary

Constants included from Retryable

Retryable::COULD_NOT_CONTACT_PRIMARY, Retryable::NOT_MASTER

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Retryable

#read_with_one_retry, #read_with_retry, #write_with_retry

Constructor Details

#initialize(view, result, server) ⇒ Cursor

Creates a Cursor object.

Examples:

Instantiate the cursor.

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

Parameters:

  • view (CollectionView) —

    The CollectionView defining the query.

  • result (Operation::Result) —

    The result of the first execution.

  • server (Server) —

    The server this cursor is locked to.

Since:

  • 2.0.0



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/mongo/cursor.rb', line 55

def initialize(view, result, server)
  @view = view
  @server = server
  @initial_result = result
  @remaining = limit if limited?
  @cursor_id = result.cursor_id
  register
  ObjectSpace.define_finalizer(self, self.class.finalize(result.cursor_id,
                                                         cluster,
                                                         kill_cursors_op_spec,
                                                         server))
end

Instance Attribute Details

#view ⇒ Collection::View (readonly)

Returns view The collection view.

Returns:



43
44
45
 
# File 'lib/mongo/cursor.rb', line 43

def view
  @view
end

Class Method Details

.finalize(cursor_id, cluster, op_spec, server) ⇒ Proc

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

Examples:

Finalize the cursor.

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

Parameters:

  • cursor_id (Integer) —

    The cursor’s id.

  • cluster (Mongo::Cluster) —

    The cluster associated with this cursor and its server.

  • op_spec (Hash) —

    The killCursors operation specification.

  • server (Mongo::Server) —

    The server to send the killCursors operation to.

Returns:

  • (Proc) —

    The Finalizer.

Since:

  • 2.3.0



83
84
85
 
# File 'lib/mongo/cursor.rb', line 83

def self.finalize(cursor_id, cluster, op_spec, server)
  proc { cluster.schedule_kill_cursor(cursor_id, op_spec, server) }
end

Instance Method Details

#batch_size ⇒ Integer

Get the batch size.

Examples:

Get the batch size.

cursor.batch_size

Returns:

  • (Integer) —

    The batch size.

Since:

  • 2.2.0



125
126
127
 
# File 'lib/mongo/cursor.rb', line 125

def batch_size
  @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
end

#closed? ⇒ true, false

Is the cursor closed?

Examples:

Is the cursor closed?

cursor.closed?

Returns:

  • (true, false) —

    If the cursor is closed.

Since:

  • 2.2.0



137
138
139
 
# File 'lib/mongo/cursor.rb', line 137

def closed?
  !more?
end

#collection_name ⇒ String

Get the parsed collection name.

Examples:

Get the parsed collection name.

cursor.coll_name

Returns:

  • (String) —

    The collection name.

Since:

  • 2.2.0



149
150
151
 
# File 'lib/mongo/cursor.rb', line 149

def collection_name
  @coll_name || collection.name
end

#each ⇒ Enumerator

Iterate through documents returned from the query.

Examples:

Iterate over the documents in the cursor.

cursor.each do |doc|
  ...
end

Returns:

  • (Enumerator) —

    The enumerator.

Since:

  • 2.0.0



109
110
111
112
113
114
115
 
# File 'lib/mongo/cursor.rb', line 109

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 ⇒ Integer

Note:

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

Get the cursor id.

Examples:

Get the cursor id.

cursor.id

Returns:

  • (Integer) —

    The cursor id.

Since:

  • 2.2.0



163
164
165
 
# File 'lib/mongo/cursor.rb', line 163

def id
  @cursor_id
end

#inspect ⇒ String

Get a human-readable string representation of Cursor.

Examples:

Inspect the cursor.

cursor.inspect

Returns:

  • (String) —

    A string representation of a Cursor instance.

Since:

  • 2.0.0



95
96
97
 
# File 'lib/mongo/cursor.rb', line 95

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

#to_return ⇒ Integer

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

Examples:

Get the number to return.

cursor.to_return

Returns:

  • (Integer) —

    The number of documents to return.

Since:

  • 2.2.0



176
177
178
 
# File 'lib/mongo/cursor.rb', line 176

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