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

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, options = {}) ⇒ 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.

  • options (Hash) (defaults to: {}) —

    The cursor options.

Options Hash (options):

  • :disable_retry (true, false) —

    Whether to disable retrying on error when sending getMores.

Since:

  • 2.0.0



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/mongo/cursor.rb', line 59

def initialize(view, result, server, options = {})
  @view = view
  @server = server
  @initial_result = result
  @remaining = limit if limited?
  @cursor_id = result.cursor_id
  @coll_name = nil
  @options = options
  @session = @options[:session]
  register
  if @cursor_id && @cursor_id > 0
    ObjectSpace.define_finalizer(self, self.class.finalize(@cursor_id,
      cluster,
      kill_cursors_op_spec,
      server,
      @session))
  end
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, session) ⇒ 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



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

def self.finalize(cursor_id, cluster, op_spec, server, session)
  proc do
    cluster.schedule_kill_cursor(cursor_id, op_spec, server)
    session.end_session if session && session.implicit?
  end
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



178
179
180
 
# File 'lib/mongo/cursor.rb', line 178

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



190
191
192
 
# File 'lib/mongo/cursor.rb', line 190

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



202
203
204
 
# File 'lib/mongo/cursor.rb', line 202

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



122
123
124
125
126
127
128
 
# File 'lib/mongo/cursor.rb', line 122

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



216
217
218
 
# File 'lib/mongo/cursor.rb', line 216

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



108
109
110
 
# File 'lib/mongo/cursor.rb', line 108

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



229
230
231
 
# File 'lib/mongo/cursor.rb', line 229

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

#try_next ⇒ BSON::Document | nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

This method is experimental and subject to change.

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.

Returns:

  • (BSON::Document | nil) —

    A document.



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/mongo/cursor.rb', line 142

def try_next
  if @documents.nil?
    @documents = process(@initial_result)
    # the documents here can be an empty array, hence
    # we may end up issuing a getMore in the first try_next call
  end

  if @documents.empty?
    if more?
      if exhausted?
        kill_cursors
        return nil
      end

      @documents = get_more
    end
  else
    # cursor is closed here
    # keep documents as an empty array
  end

  if @documents
    return @documents.shift
  end

  nil
end