Class DBCursor
- All Implemented Interfaces:
Cursor
,Closeable
,AutoCloseable
,Iterable<DBObject>
,Iterator<DBObject>
An iterator over database results. Doing a find()
query on a collection returns a DBCursor
.
An application should ensure that a cursor is closed in all circumstances, e.g. using a try-with-resources statement:
try (DBCursor cursor = collection.find(query)) { while (cursor.hasNext()) { System.out.println(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();
See MongoClient.getDB(String)
for further information about the effective deprecation of this class.- MongoDB documentation
- Read Operations
-
Constructor Summary
ConstructorDescriptionDBCursor
(DBCollection collection, DBObject query, DBObject fields, ReadPreference readPreference) Initializes a new database cursor.DBCursor
(DBCollection collection, DBObject query, DBObject fields, ReadPreference readPreference, boolean retryReads) Initializes a new database cursor. -
Method Summary
Modifier and TypeMethodDescriptionint
Gets the number of results available locally without blocking, which may be 0.batchSize
(int numberOfElements) Limits the number of elements returned in one batch.void
close()
Terminates this cursor on the server.Adds a comment to the query to identify queries in the database profiler output.copy()
Creates a copy of an existing database cursor.int
count()
Counts the number of objects matching the query.curr()
Returns the element the cursor is at.cursorType
(CursorType cursorType) Sets the cursor type.explain()
Returns an object containing basic information about the execution of the query that created this cursor.int
Gets the batch size.Returns the collation optionsGets the collection.long
Gets the server's identifier for this Cursor.Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.Gets the fields to be returned.int
getLimit()
Gets the query limit.getQuery()
Gets the query.Gets the default read preference.Gets the address of the server that data is pulled from.boolean
hasNext()
Checks if there is another object available.Informs the database of indexed fields of the collection in order to improve performance.Informs the database of an indexed field of the collection in order to improve performance.int
itcount()
For testing only! Iterates cursor and counts objectsiterator()
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.limit
(int limit) Limits the number of elements returned.Specifies an exclusive upper limit for the index to use in a query.Set the maximum execution time for operations on this cursor.Specifies an inclusive lower limit for the index to use in a query.next()
Returns the object the cursor is at and moves the cursor ahead by one.noCursorTimeout
(boolean noCursorTimeout) The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use.int
numSeen()
Returns the number of objects through which the cursor has iterated.one()
Returns the first document that matches the query.partial
(boolean partial) Get partial results from a sharded cluster if one or more shards are unreachable (instead of throwing an error).void
remove()
Forces the cursor to only return fields included in the index.setCollation
(Collation collation) Sets the collation optionssetDecoderFactory
(DBDecoderFactory factory) Sets the factory that will be used create aDBDecoder
that will be used to decode BSON documents into DBObject instances.setReadPreference
(ReadPreference readPreference) Sets the read preference for this cursor.int
size()
Counts the number of objects matching the query this does take limit/skip into considerationskip
(int numberOfElements) Discards a given number of elements at the beginning of the cursor.Sorts this cursor's elements.toArray()
Converts this cursor to an array.toArray
(int max) Converts this cursor to an array.toString()
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
Methods inherited from interface java.lang.Iterable
forEach, spliterator
Methods inherited from interface java.util.Iterator
forEachRemaining
-
Constructor Details
-
DBCursor
public DBCursor(DBCollection collection, DBObject query, @Nullable DBObject fields, @Nullable ReadPreference readPreference) Initializes a new database cursor.- Parameters:
collection
- collection to usequery
- the query filter to applyfields
- keys to return from the queryreadPreference
- the read preference for this query
-
DBCursor
public DBCursor(DBCollection collection, DBObject query, @Nullable DBObject fields, @Nullable ReadPreference readPreference, boolean retryReads) Initializes a new database cursor.- Parameters:
collection
- collection to usequery
- the query filter to applyfields
- keys to return from the queryreadPreference
- the read preference for this queryretryReads
- true if reads should be retried
-
-
Method Details
-
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
-
hasNext
public boolean hasNext()Checks if there is another object available.Note: Automatically turns cursors of type Tailable to TailableAwait. For non-blocking tailable cursors see
tryNext()
.- Specified by:
hasNext
in interfaceIterator<DBObject>
- Returns:
- true if there is another object available
- MongoDB documentation
- Cursor Batches
-
next
Returns the object the cursor is at and moves the cursor ahead by one.Note: Automatically turns cursors of type Tailable to TailableAwait. For non-blocking tailable cursors see
tryNext()
.- Specified by:
next
in interfaceIterator<DBObject>
- Returns:
- the next element
- MongoDB documentation
- Cursor Batches
-
available
public int available()Gets the number of results available locally without blocking, which may be 0.If the cursor is known to be exhausted, returns 0. If the cursor is closed before it's been exhausted, it may return a non-zero value.
-
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
- if failedIllegalArgumentException
- if the cursor is not tailable- MongoDB documentation
- Cursor Batches
-
curr
Returns the element the cursor is at.- Returns:
- the current element
-
remove
public void remove() -
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
-
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
-
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
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
Forces the cursor to only return fields included in the index.- Returns:
this
so calls can be chained- Since:
- 2.12
- MongoDB documentation
- $returnKey
-
hint
Informs the database of indexed fields of the collection in order to improve performance.- Parameters:
indexKeys
- aDBObject
with fields and direction- Returns:
- same DBCursor for chaining operations
- MongoDB documentation
- $hint
-
hint
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
- Since:
- 4.4
- MongoDB documentation
- $hint
-
maxTime
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.timeUnit
- the time unit- Returns:
- same DBCursor for chaining operations
- Since:
- 2.12.0
- MongoDB documentation
- $maxTimeMS
-
explain
Returns an object containing basic information about the execution of the query that created this cursor. This creates aDBObject
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
- if the operation failed- MongoDB documentation
- Explain Output
- Since server release
- 3.0
-
cursorType
Sets the cursor type.- Parameters:
cursorType
- the cursor type, which may not be null- Returns:
- this
- Since:
- 3.9
-
noCursorTimeout
The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that.- Parameters:
noCursorTimeout
- true if cursor timeout is disabled- Returns:
- this
- Since:
- 3.9
-
partial
Get partial results from a sharded cluster if one or more shards are unreachable (instead of throwing an error).- Parameters:
partial
- if partial results for sharded clusters is enabled- Returns:
- this
- Since:
- 3.9
-
sort
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
-
limit
Limits the number of elements returned. Note: parameterlimit
should be positive, although a negative value is supported for legacy reason. Passing a negative value will callbatchSize(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
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 ifbatchSize
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
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 interfaceCursor
- Returns:
- the cursor's ID, or 0 if there is no active cursor.
-
numSeen
public int numSeen()Returns the number of objects through which the cursor has iterated.- Returns:
- the number of objects seen
-
close
public void close()Description copied from interface:Cursor
Terminates this cursor on the server. -
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.
-
toArray
Converts this cursor to an array.- Returns:
- an array of elements
- Throws:
MongoException
- if failed
-
toArray
Converts this cursor to an array.- Parameters:
max
- the maximum number of objects to return- Returns:
- an array of objects
- Throws:
MongoException
- if failed
-
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
- if the operation failed- See Also:
-
one
Returns the first document that matches the query.- Returns:
- the first matching document
- Since:
- 2.12
-
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
- if failed- See Also:
-
itcount
public int itcount()For testing only! Iterates cursor and counts objects- Returns:
- num objects
- Throws:
MongoException
- if failed- See Also:
-
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
- if the operation failed- See Also:
-
getKeysWanted
Gets the fields to be returned.- Returns:
- the field selector that cursor used
-
getQuery
Gets the query.- Returns:
- the query that cursor used
-
getCollection
Gets the collection.- Returns:
- the collection that data is pulled from
-
getServerAddress
Description copied from interface:Cursor
Gets the 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 interfaceCursor
- Returns:
- the address of the server that data is pulled from, or null if a cursor is no longer established
-
setReadPreference
Sets the read preference for this cursor. See the documentation forReadPreference
for more information.- Parameters:
readPreference
- read preference to use- Returns:
this
so calls can be chained
-
getReadPreference
Gets the default read preference.- Returns:
- the readPreference used by this cursor
-
getCollation
Returns the collation options- Returns:
- the collation options
- Since:
- 3.4
- Since server release
- 3.4
-
setCollation
Sets the collation optionsA null value represents the server default.
- Parameters:
collation
- the collation options to use- Returns:
- this
- Since:
- 3.4
- Since server release
- 3.4
-
setDecoderFactory
Sets the factory that will be used create aDBDecoder
that will be used to decode BSON documents into DBObject instances.- Parameters:
factory
- the DBDecoderFactory- Returns:
this
so calls can be chained
-
getDecoderFactory
Gets the decoder factory that creates the decoder this cursor will use to decode objects from MongoDB.- Returns:
- the decoder factory.
-
toString
-