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

Instance Method Summary collapse

Methods included from Retryable

#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
 
# File 'lib/mongo/cursor.rb', line 55

def initialize(view, result, server)
  @view = view
  @server = server
  @initial_result = result
  @remaining = limit if limited?
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

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



100
101
102
 
# File 'lib/mongo/cursor.rb', line 100

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



112
113
114
 
# File 'lib/mongo/cursor.rb', line 112

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



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

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



84
85
86
87
88
89
90
 
# 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 ⇒ 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



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

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



70
71
72
 
# File 'lib/mongo/cursor.rb', line 70

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



151
152
153
 
# File 'lib/mongo/cursor.rb', line 151

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