Package 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.

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 Details

    • DBCursor

      public DBCursor(DBCollection collection, DBObject query, @Nullable DBObject fields, @Nullable ReadPreference readPreference)
      Initializes a new database cursor.
      Parameters:
      collection - collection to use
      query - the query filter to apply
      fields - keys to return from the query
      readPreference - 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 use
      query - the query filter to apply
      fields - keys to return from the query
      readPreference - the read preference for this query
      retryReads - true if reads should be retried

  • Method Details

    • 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

    • 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 interface Iterator<DBObject>
      Returns:
      true if there is another object available
      MongoDB documentation
      Cursor Batches

    • next

      public DBObject 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 interface Iterator<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.

      Specified by:
      available in interface Cursor
      Returns:
      the number of results available locally without blocking
      Since:
      4.5

    • tryNext

      @Nullable 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 - if failed
      IllegalArgumentException - if the cursor is not tailable
      MongoDB documentation
      Cursor Batches

    • curr

      public DBObject curr()
      Returns the element the cursor is at.
      Returns:
      the current element

    • remove

      public void remove()
      Specified by:
      remove in interface Iterator<DBObject>

    • 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

      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

    • 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

    • 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
      Since:
      4.4
      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.
      timeUnit - the time unit
      Returns:
      same DBCursor for chaining operations
      Since:
      2.12.0
      MongoDB documentation
      $maxTimeMS

    • explain

      @Deprecated public DBObject explain()
      Deprecated.
      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 - if the operation failed
      MongoDB documentation
      Explain Output
      Since server release
      3.0

    • cursorType

      public DBCursor cursorType(CursorType cursorType)
      Sets the cursor type.
      Parameters:
      cursorType - the cursor type, which may not be null
      Returns:
      this
      Since:
      3.9

    • oplogReplay

      @Deprecated public DBCursor oplogReplay(boolean oplogReplay)
      Deprecated.
      oplogReplay has been deprecated in MongoDB 4.4.
      Users should not set this under normal circumstances.
      Parameters:
      oplogReplay - if oplog replay is enabled
      Returns:
      this
      Since:
      3.9

    • noCursorTimeout

      public DBCursor noCursorTimeout(boolean 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

      public DBCursor partial(boolean 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

      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

    • 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.

    • 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.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface 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

    • toArray

      public List<DBObject> toArray()
      Converts this cursor to an array.
      Returns:
      an array of elements
      Throws:
      MongoException - if failed

    • 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 - 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

      @Nullable public DBObject 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

      @Nullable 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

      @Nullable public ServerAddress 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 interface Cursor
      Returns:
      the address of the server that data is pulled from, or null if a cursor is no longer established

    • 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

    • getCollation

      @Nullable public Collation getCollation()
      Returns the collation options
      Returns:
      the collation options
      Since:
      3.4
      Since server release
      3.4

    • setCollation

      public DBCursor setCollation(@Nullable Collation collation)
      Sets the collation options

      A null value represents the server default.

      Parameters:
      collation - the collation options to use
      Returns:
      this
      Since:
      3.4
      Since server release
      3.4

    • setDecoderFactory

      public DBCursor setDecoderFactory(DBDecoderFactory factory)
      Sets the factory that will be used create a DBDecoder that will be used to decode BSON documents into DBObject instances.
      Parameters:
      factory - 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