Class | Mongo::Cursor |
In: |
lib/mongo/cursor.rb
|
Parent: | Object |
A cursor over query results. Returned objects are hashes.
collection | [R] | |
comment | [R] | |
cursor_id | [R] | |
fields | [R] | |
full_collection_name | [R] | |
hint | [R] | |
options | [R] | |
order | [R] | |
read | [R] | |
selector | [R] | |
show_disk_loc | [R] | |
snapshot | [R] | |
tag_sets | [R] | |
timeout | [R] | |
transformer | [R] |
Create a new cursor.
Note: cursors are created when executing queries using [Collection#find] and other similar methods. Application developers shouldn‘t have to create cursors manually.
@return [Cursor]
@core cursors constructor_details
Add an option to the query options bitfield.
@param opt a valid query option
@raise InvalidOperation if this method is run after the cursor has bee
iterated for the first time.
@return [Integer] the current value of the options bitfield for this cursor.
@see www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-Mongo::Constants::OPQUERY
Guess whether the cursor is alive on the server.
Note that this method only checks whether we have a cursor id. The cursor may still have timed out on the server. This will be indicated in the next call to Cursor#next.
@return [Boolean]
Set the batch size for server responses.
Note that the batch size will take effect only on queries where the number to be returned is greater than 100.
This can not override MongoDB‘s limit on the amount of data it will return to the client. Depending on server version this can be 4-16mb.
@param [Integer] size either 0 or some integer greater than 1. If 0,
the server will determine the batch size.
@return [Cursor]
Close the cursor.
Note: if a cursor is read until exhausted (read until Mongo::Constants::OP_QUERY or Mongo::Constants::OP_GETMORE returns zero for the cursor id), there is no need to close it manually.
Note also: Collection#find takes an optional block argument which can be used to ensure that your cursors get closed.
@return [True]
Get the size of the result set for this query.
@param [Boolean] whether of not to take notice of skip and limit
@return [Integer] the number of objects in the result set for this query.
@raise [OperationFailure] on a database error.
Iterate over each document in this cursor, yielding it to the given block, if provided. An Enumerator is returned if no block is given.
Iterating over an entire cursor will close it.
@yield passes each document to a block for processing.
@example if ‘comments’ represents a collection of comments:
comments.find.each do |doc| puts doc['user'] end
Limit the number of results to be returned by this cursor.
This method overrides any limit specified in the Collection#find method, and only the last limit applied has an effect.
@return [Integer] the current number_to_return if no parameter is given.
@raise [InvalidOperation] if this cursor has already been used.
Returns an integer indicating which query options have been selected.
@return [Integer]
@see www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-Mongo::Constants::OPQUERY The MongoDB wire protocol.
Remove an option from the query options bitfield.
@param opt a valid query option
@raise InvalidOperation if this method is run after the cursor has bee
iterated for the first time.
@return [Integer] the current value of the options bitfield for this cursor.
@see www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-Mongo::Constants::OPQUERY
Skips the first number_to_skip results of this cursor. Returns the current number_to_skip if no parameter is given.
This method overrides any skip specified in the Collection#find method, and only the last skip applied has an effect.
@return [Integer]
@raise [InvalidOperation] if this cursor has already been used.
Sort this cursor‘s results.
This method overrides any sort order specified in the Collection#find method, and only the last sort applied has an effect.
@param [Symbol, Array, Hash, OrderedHash] order either 1) a key to sort by 2)
an array of [key, direction] pairs to sort by or 3) a hash of field => direction pairs to sort by. Direction should be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
@raise [InvalidOperation] if this cursor has already been used.
@raise [InvalidSortValueError] if the specified order is invalid.
Receive all the documents from this cursor as an array of hashes.
Notes:
If you‘ve already started iterating over the cursor, the array returned by this method contains only the remaining documents. See Cursor#rewind! if you need to reset the cursor.
Use of this method is discouraged - in most cases, it‘s much more efficient to retrieve documents as you need them by iterating over the cursor.
@return [Array] an array of documents.