com.mongodb

Class DBCursor

java.lang.Object

com.mongodb.DBCursor

All Implemented Interfaces:

Cursor, Closeable, AutoCloseable, Iterable<DBObject>, Iterator<DBObject>

@NotThreadSafe
public class DBCursor
extends Object
implements Cursor, Iterable<DBObject>

An iterator over database results. Doing a find() query on a collection returns a DBCursor thus

 DBCursor cursor = collection.find( query );
    if(cursor.hasNext()) {
     DBObject obj = cursor.next();
    }
 

Warning: Calling toArray or length on a DBCursor will irrevocably turn it into an array. This means that, if the cursor was iterating over ten million results (which it was lazily fetching from the database), suddenly there will be a ten-million element array in memory. Before converting to an array, make sure that there are a reasonable number of results using skip() and limit().

For example, to get an array of the 1000-1100th elements of a cursor, use

List<DBObject> obj = collection.find( query ).skip( 1000 ).limit( 100 ).toArray();
 

MongoDB documentation

Read Operations

Constructor Summary

Constructors

Constructor and Description
DBCursor(DBCollection collection, DBObject q, DBObject k, ReadPreference preference) Initializes a new database cursor.

Method Summary

Methods

Modifier and Type	Method and Description
DBCursor	addOption(int option) Adds a query option.
DBCursor	addSpecial(String name, Object o) Adds a special operator like $maxScan or $returnKey.
DBCursor	batchSize(int numberOfElements) Limits the number of elements returned in one batch.
void	close() Terminates this cursor on the server.
DBCursor	comment(String comment) Adds a comment to the query to identify queries in the database profiler output.
DBCursor	copy() Creates a copy of an existing database cursor.
int	count() Counts the number of objects matching the query.
DBObject	curr() Returns the element the cursor is at.
DBCursor	disableBatchSizeTracking() Deprecated. This method is being added temporarily, and will be removed along with getSizes() in the next major release
DBObject	explain() Returns an object containing basic information about the execution of the query that created this cursor.
int	getBatchSize() Gets the batch size.
DBCollection	getCollection() Gets the collection.
long	getCursorId() Gets the server's identifier for this Cursor.
DBDecoderFactory	getDecoderFactory() Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.
DBObject	getKeysWanted() Gets the fields to be returned.
int	getLimit() Gets the query limit.
int	getOptions() Gets the query options.
DBObject	getQuery() Gets the query.
ReadPreference	getReadPreference() Gets the default read preference.
ServerAddress	getServerAddress() Gets the Server Address of the server that data is pulled from.
List<Integer>	getSizes() Deprecated. there is no replacement for this method
boolean	hasNext() Checks if there is another object available.
DBCursor	hint(DBObject indexKeys) Informs the database of indexed fields of the collection in order to improve performance.
DBCursor	hint(String indexName) Informs the database of an indexed field of the collection in order to improve performance.
boolean	isBatchSizeTrackingDisabled() Deprecated. This method is being added temporarily, and will be removed along with getSizes() in the next major release
int	itcount() For testing only! Iterates cursor and counts objects
Iterator<DBObject>	iterator() Creates a copy of this cursor object that can be iterated.
int	length() Pulls back all items into an array and returns the number of objects.
DBCursor	limit(int limit) Limits the number of elements returned.
DBCursor	max(DBObject max) Specifies an exclusive upper limit for the index to use in a query.
DBCursor	maxScan(int max) Limits the number of documents a cursor will return for a query.
DBCursor	maxTime(long maxTime, TimeUnit timeUnit) Set the maximum execution time for operations on this cursor.
DBCursor	min(DBObject min) Specifies an inclusive lower limit for the index to use in a query.
DBObject	next() Returns the object the cursor is at and moves the cursor ahead by one.
int	numGetMores() Deprecated. there is no replacement for this method
int	numSeen() Returns the number of objects through which the cursor has iterated.
DBObject	one() Returns the first document that matches the query.
void	remove() Not implemented.
DBCursor	resetOptions() Resets the query options.
DBCursor	returnKey() Forces the cursor to only return fields included in the index.
DBCursor	setDecoderFactory(DBDecoderFactory fact) Sets the factory that will be used create a DBDecoder that will be used to decode BSON documents into DBObject instances.
DBCursor	setOptions(int options) Sets the query option - see Bytes.QUERYOPTION_* for list.
DBCursor	setReadPreference(ReadPreference readPreference) Sets the read preference for this cursor.
DBCursor	showDiskLoc() Modifies the documents returned to include references to the on-disk location of each document.
int	size() Counts the number of objects matching the query this does take limit/skip into consideration
DBCursor	skip(int numberOfElements) Discards a given number of elements at the beginning of the cursor.
DBCursor	slaveOk() Deprecated. Replaced with ReadPreference.secondaryPreferred()
DBCursor	snapshot() Use snapshot mode for the query.
DBCursor	sort(DBObject orderBy) Sorts this cursor's elements.
List<DBObject>	toArray() Converts this cursor to an array.
List<DBObject>	toArray(int max) Converts this cursor to an array.
String	toString()
DBObject	tryNext() Non blocking check for tailable cursors to see if another object is available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DBCursor

public DBCursor(DBCollection collection,
        DBObject q,
        DBObject k,
        ReadPreference preference)

Initializes a new database cursor.

Parameters:

collection - collection to use

q - query to perform

k - keys to return from the query

preference - the Read Preference for this query

Method Detail

comment

public DBCursor comment(String comment)

Adds a comment to the query to identify queries in the database profiler output.

Parameters:

comment - the comment that is to appear in the profiler output

Returns:

this so calls can be chained

Since:

2.12

MongoDB documentation

$comment

maxScan

public DBCursor maxScan(int max)

Limits the number of documents a cursor will return for a query.

Parameters:

max - the maximum number of documents to return

Returns:

this so calls can be chained

Since:

2.12

See Also:

limit(int)

MongoDB documentation

$maxScan

max

public DBCursor max(DBObject max)

Specifies an exclusive upper limit for the index to use in a query.

Parameters:

max - a document specifying the fields, and the upper bound values for those fields

Returns:

this so calls can be chained

Since:

2.12

MongoDB documentation

$max

min

public DBCursor min(DBObject min)

Specifies an inclusive lower limit for the index to use in a query.

Parameters:

min - a document specifying the fields, and the lower bound values for those fields

Returns:

this so calls can be chained

Since:

2.12

MongoDB documentation

$min

returnKey

public DBCursor returnKey()

Forces the cursor to only return fields included in the index.

Returns:

this so calls can be chained

Since:

2.12

MongoDB documentation

$returnKey

showDiskLoc

public DBCursor showDiskLoc()

Modifies the documents returned to include references to the on-disk location of each document. The location will be returned in a property named $diskLoc

Returns:

this so calls can be chained

Since:

2.12

MongoDB documentation

$showDiskLoc

copy

public DBCursor copy()

Creates a copy of an existing database cursor. The new cursor is an iterator, even if the original was an array.

Returns:

the new cursor

iterator

public Iterator<DBObject> iterator()

Creates a copy of this cursor object that can be iterated. Note: - you can iterate the DBCursor itself without calling this method - no actual data is getting copied.

Note that use of this method does not let you call close the underlying cursor in the case of either an exception or an early break. The preferred method of iteration is to use DBCursor as an Iterator, so that you can call close() on it in a finally block.

Specified by:

iterator in interface Iterable<DBObject>

Returns:

an iterator

sort

public DBCursor sort(DBObject orderBy)

Sorts this cursor's elements. This method must be called before getting any object from the cursor.

Parameters:

orderBy - the fields by which to sort

Returns:

a cursor pointing to the first element of the sorted results

addSpecial

public DBCursor addSpecial(String name,
                  Object o)

Adds a special operator like $maxScan or $returnKey. For example:

    addSpecial("$returnKey", 1)
    addSpecial("$maxScan", 100)
 

Parameters:

name - the name of the special query operator

o - the value of the special query operator

Returns:

this so calls can be chained

MongoDB documentation

Special Operators

hint

public DBCursor hint(DBObject indexKeys)

Informs the database of indexed fields of the collection in order to improve performance.

Parameters:

indexKeys - a DBObject with fields and direction

Returns:

same DBCursor for chaining operations

MongoDB documentation

$hint

hint

public DBCursor hint(String indexName)

Informs the database of an indexed field of the collection in order to improve performance.

Parameters:

indexName - the name of an index

Returns:

same DBCursor for chaining operations

MongoDB documentation

$hint

maxTime

public DBCursor maxTime(long maxTime,
               TimeUnit timeUnit)

Set the maximum execution time for operations on this cursor.

Parameters:

maxTime - the maximum time that the server will allow the query to run, before killing the operation. A non-zero value requires a server version >= 2.6

timeUnit - the time unit

Returns:

same DBCursor for chaining operations

Since:

2.12.0

MongoDB documentation

$maxTimeMS

Since server release

2.6

snapshot

public DBCursor snapshot()

Use snapshot mode for the query. Snapshot mode prevents the cursor from returning a document more than once because an intervening write operation results in a move of the document. Even in snapshot mode, documents inserted or deleted during the lifetime of the cursor may or may not be returned. Currently, snapshot mode may not be used with sorting or explicit hints.

Returns:

this so calls can be chained

See Also:

sort(DBObject), hint(DBObject)

MongoDB documentation

$snapshot

explain

public DBObject explain()

Returns an object containing basic information about the execution of the query that created this cursor. This creates a DBObject with a number of fields, including but not limited to:

• cursor: cursor type
• nScanned: number of records examined by the database for this query
• n: the number of records that the database returned
• millis: how long it took the database to execute the query

Returns:

a DBObject containing the explain output for this DBCursor's query

Throws:

MongoException

MongoDB documentation

Explain Output

limit

public DBCursor limit(int limit)

Limits the number of elements returned. Note: parameter limit should be positive, although a negative value is supported for legacy reason. Passing a negative value will call batchSize(int) which is the preferred method.

Parameters:

limit - the number of elements to return

Returns:

a cursor to iterate the results

MongoDB documentation

Limit

batchSize

public DBCursor batchSize(int numberOfElements)

Limits the number of elements returned in one batch. A cursor typically fetches a batch of result objects and store them locally.

If batchSize is positive, it represents the size of each batch of objects retrieved. It can be adjusted to optimize performance and limit data transfer.

If batchSize is negative, it will limit of number objects returned, that fit within the max batch size limit (usually 4MB), and cursor will be closed. For example if batchSize is -10, then the server will return a maximum of 10 documents and as many as can fit in 4MB, then close the cursor. Note that this feature is different from limit() in that documents must fit within a maximum size, and it removes the need to send a request to close the cursor server-side.

Parameters:

numberOfElements - the number of elements to return in a batch

Returns:

this so calls can be chained

skip

public DBCursor skip(int numberOfElements)

Discards a given number of elements at the beginning of the cursor.

Parameters:

numberOfElements - the number of elements to skip

Returns:

a cursor pointing to the new first element of the results

Throws:

IllegalStateException - if the cursor has started to be iterated through

getCursorId

public long getCursorId()

Description copied from interface: Cursor

Gets the server's identifier for this Cursor.

Specified by:

getCursorId in interface Cursor

Returns:

the cursor's ID, or 0 if there is no active cursor.

close

public void close()

Description copied from interface: Cursor

Terminates this cursor on the server.

Specified by:

close in interface Cursor

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

slaveOk

@Deprecated
public DBCursor slaveOk()

Deprecated. Replaced with ReadPreference.secondaryPreferred()

Declare that this query can run on a secondary server.

Returns:

a copy of the same cursor (for chaining)

See Also:

ReadPreference.secondaryPreferred(), ReadPreference.secondaryPreferred()

addOption

public DBCursor addOption(int option)

Adds a query option. See Bytes.QUERYOPTION_* for list.

Parameters:

option - the option to be added

Returns:

this so calls can be chained

See Also:

Bytes

MongoDB documentation

Query Flags

setOptions

public DBCursor setOptions(int options)

Sets the query option - see Bytes.QUERYOPTION_* for list.

Parameters:

options - the bitmask of options

Returns:

this so calls can be chained

See Also:

Bytes

MongoDB documentation

Query Flags

resetOptions

public DBCursor resetOptions()

Resets the query options.

Returns:

this so calls can be chained

MongoDB documentation

Query Flags

getOptions

public int getOptions()

Gets the query options.

Returns:

the bitmask of options

MongoDB documentation

Query Flags

getLimit

public int getLimit()

Gets the query limit.

Returns:

the limit, or 0 if no limit is set

getBatchSize

public int getBatchSize()

Gets the batch size.

Returns:

the batch size

numGetMores

@Deprecated
public int numGetMores()

Deprecated. there is no replacement for this method

Gets the number of times, so far, that the cursor retrieved a batch from the database

Returns:

The number of times OP_GET_MORE has been called

getSizes

@Deprecated
public List<Integer> getSizes()

Deprecated. there is no replacement for this method

Gets a list containing the number of items received in each batch

Returns:

a list containing the number of items received in each batch

disableBatchSizeTracking

@Deprecated
public DBCursor disableBatchSizeTracking()

Deprecated. This method is being added temporarily, and will be removed along with getSizes() in the next major release

Disable tracking of batch sizes in order to reduce memory consumption with high-frequency tailable cursors. This method must be called before iterating the cursor.

Returns:

this

See Also:

getSizes()

isBatchSizeTrackingDisabled

@Deprecated
public boolean isBatchSizeTrackingDisabled()

Deprecated. This method is being added temporarily, and will be removed along with getSizes() in the next major release

Returns true if tracking of batch sizes is disabled in order to reduce memory consumption with high-frequency tailable cursors.

Returns:

true if tracking of batch sizes is disabled

See Also:

getSizes(), disableBatchSizeTracking()

numSeen

public int numSeen()

Returns the number of objects through which the cursor has iterated.

Returns:

the number of objects seen

hasNext

public boolean hasNext()

Checks if there is another object available.

Note: Automatically adds the Bytes.QUERYOPTION_AWAITDATA option to any cursors with the Bytes.QUERYOPTION_TAILABLE option set. For non blocking tailable cursors see tryNext().

Specified by:

hasNext in interface Iterator<DBObject>

Returns:

true if there is another object available

Throws:

MongoException

MongoDB documentation

Cursor Batches

tryNext

public DBObject tryNext()

Non blocking check for tailable cursors to see if another object is available.

Returns the object the cursor is at and moves the cursor ahead by one or return null if no documents is available.

Returns:

the next element or null

Throws:

MongoException

MongoDB documentation

Cursor Batches

next

public DBObject next()

Returns the object the cursor is at and moves the cursor ahead by one.

Note: Automatically adds the Bytes.QUERYOPTION_AWAITDATA option to any cursors with the Bytes.QUERYOPTION_TAILABLE option set. For non blocking tailable cursors see tryNext().

Specified by:

next in interface Iterator<DBObject>

Returns:

the next element

MongoDB documentation

Cursor Batches

curr

public DBObject curr()

Returns the element the cursor is at.

Returns:

the current element

remove

public void remove()

Not implemented.

Specified by:

remove in interface Iterator<DBObject>

length

public int length()

Pulls back all items into an array and returns the number of objects. Note: this can be resource intensive.

Returns:

the number of elements in the array

Throws:

MongoException

See Also:

count(), size()

toArray

public List<DBObject> toArray()

Converts this cursor to an array.

Returns:

an array of elements

Throws:

MongoException

toArray

public List<DBObject> toArray(int max)

Converts this cursor to an array.

Parameters:

max - the maximum number of objects to return

Returns:

an array of objects

Throws:

MongoException

itcount

public int itcount()

For testing only! Iterates cursor and counts objects

Returns:

num objects

Throws:

MongoException

See Also:

count()

count

public int count()

Counts the number of objects matching the query. This does not take limit/skip into consideration, and does initiate a call to the server.

Returns:

the number of objects

Throws:

MongoException

See Also:

size()

one

public DBObject one()

Returns the first document that matches the query.

Returns:

the first matching document

Since:

2.12

size

public int size()

Counts the number of objects matching the query this does take limit/skip into consideration

Returns:

the number of objects

Throws:

MongoException

See Also:

count()

getKeysWanted

public DBObject getKeysWanted()

Gets the fields to be returned.

Returns:

the field selector that cursor used

getQuery

public DBObject getQuery()

Gets the query.

Returns:

the query that cursor used

getCollection

public DBCollection getCollection()

Gets the collection.

Returns:

the collection that data is pulled from

getServerAddress

public ServerAddress getServerAddress()

Gets the Server Address of the server that data is pulled from. Note that this information may not be available until hasNext() or next() is called.

Specified by:

getServerAddress in interface Cursor

Returns:

the address of the server

setReadPreference

public DBCursor setReadPreference(ReadPreference readPreference)

Sets the read preference for this cursor. See the documentation for ReadPreference for more information.

Parameters:

readPreference - read preference to use

Returns:

this so calls can be chained

getReadPreference

public ReadPreference getReadPreference()

Gets the default read preference.

Returns:

the readPreference used by this cursor

setDecoderFactory

public DBCursor setDecoderFactory(DBDecoderFactory fact)

Sets the factory that will be used create a DBDecoder that will be used to decode BSON documents into DBObject instances.

Parameters:

fact - the DBDecoderFactory

Returns:

this so calls can be chained

getDecoderFactory

public DBDecoderFactory getDecoderFactory()

Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.

Returns:

the decoder factory.

toString

public String toString()

Overrides:

toString in class Object