Package com.mongodb

Class DBCollection


  • @ThreadSafe
    public class DBCollection
    extends Object
    Implementation of a database collection. A typical invocation sequence is thus:
     
     MongoClient mongoClient = new MongoClient(new ServerAddress("localhost", 27017));
     DB db = mongoClient.getDB("mydb");
     DBCollection collection = db.getCollection("test"); 
     
    To get a collection to use, just specify the name of the collection to the getCollection(String collectionName) method:
     
     DBCollection coll = db.getCollection("testCollection"); 
     
    Once you have the collection object, you can insert documents into the collection:
     
     BasicDBObject doc = new BasicDBObject("name", "MongoDB").append("type", "database")
                                                             .append("count", 1)
                                                             .append("info", new BasicDBObject("x", 203).append("y", 102));
     coll.insert(doc); 
     
    To show that the document we inserted in the previous step is there, we can do a simple findOne() operation to get the first document in the collection:
     
     DBObject myDoc = coll.findOne();
     System.out.println(myDoc); 
     
    See MongoClient.getDB(String) for further information about the effective deprecation of this class.
    MongoDB documentation
    Collection
    • Constructor Detail

      • DBCollection

        protected DBCollection​(DB database,
                               String name)
        Initializes a new collection. No operation is actually performed on the database.
        Parameters:
        database - database in which to create the collection
        name - the name of the collection
    • Method Detail

      • insert

        public WriteResult insert​(DBObject document,
                                  WriteConcern writeConcern)
        Insert a document into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        document - DBObject to be inserted
        writeConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(DBObject... documents)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added. Collection wide WriteConcern will be used.
        Parameters:
        documents - DBObject's to be inserted
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(WriteConcern writeConcern,
                                  DBObject... documents)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        documents - DBObject's to be inserted
        writeConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the write failed due some other failure
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(DBObject[] documents,
                                  WriteConcern writeConcern)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        documents - DBObject's to be inserted
        writeConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(List<? extends DBObject> documents)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        documents - list of DBObject to be inserted
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(List<? extends DBObject> documents,
                                  WriteConcern aWriteConcern)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        documents - list of DBObject's to be inserted
        aWriteConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(DBObject[] documents,
                                  WriteConcern aWriteConcern,
                                  DBEncoder encoder)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        documents - DBObject's to be inserted
        aWriteConcern - WriteConcern to be used during operation
        encoder - DBEncoder to be used
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(List<? extends DBObject> documents,
                                  WriteConcern aWriteConcern,
                                  @Nullable
                                  DBEncoder dbEncoder)
        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.
        Parameters:
        documents - a list of DBObject's to be inserted
        aWriteConcern - WriteConcern to be used during operation
        dbEncoder - DBEncoder to be used
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • insert

        public WriteResult insert​(List<? extends DBObject> documents,
                                  InsertOptions insertOptions)

        Insert documents into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an '_id' field, it will be added.

        If the value of the continueOnError property of the given InsertOptions is true, that value will override the value of the continueOnError property of the given WriteConcern. Otherwise, the value of the continueOnError property of the given WriteConcern will take effect.

        Parameters:
        documents - a list of DBObject's to be inserted
        insertOptions - the options to use for the insert
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Insert Documents
      • save

        public WriteResult save​(DBObject document)
        Update an existing document or insert a document depending on the parameter. If the document does not contain an '_id' field, then the method performs an insert with the specified fields in the document as well as an '_id' field with a unique objectId value. If the document contains an '_id' field, then the method performs an upsert querying the collection on the '_id' field:
        • If a document does not exist with the specified '_id' value, the method performs an insert with the specified fields in the document.
        • If a document exists with the specified '_id' value, the method performs an update, replacing all field in the existing record with the fields from the document.
        Parameters:
        document - DBObject to save to the collection.
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert or update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Save
      • save

        public WriteResult save​(DBObject document,
                                WriteConcern writeConcern)
        Update an existing document or insert a document depending on the parameter. If the document does not contain an '_id' field, then the method performs an insert with the specified fields in the document as well as an '_id' field with a unique objectId value. If the document contains an '_id' field, then the method performs an upsert querying the collection on the '_id' field:
        • If a document does not exist with the specified '_id' value, the method performs an insert with the specified fields in the document.
        • If a document exists with the specified '_id' value, the method performs an update, replacing all field in the existing record with the fields from the document.
        Parameters:
        document - DBObject to save to the collection.
        writeConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the insert or update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Save
      • update

        public WriteResult update​(DBObject query,
                                  DBObject update,
                                  boolean upsert,
                                  boolean multi,
                                  WriteConcern aWriteConcern)
        Modify an existing document or documents in collection. The query parameter employs the same query selectors, as used in find().
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        upsert - when true, inserts a document if no document matches the update query criteria
        multi - when true, updates all documents in the collection that match the update query criteria, otherwise only updates one
        aWriteConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Modify Documents
      • update

        public WriteResult update​(DBObject query,
                                  DBObject update,
                                  boolean upsert,
                                  boolean multi,
                                  WriteConcern concern,
                                  @Nullable
                                  DBEncoder encoder)
        Modify an existing document or documents in collection. By default the method updates a single document. The query parameter employs the same query selectors, as used in find().
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        upsert - when true, inserts a document if no document matches the update query criteria
        multi - when true, updates all documents in the collection that match the update query criteria, otherwise only updates one
        concern - WriteConcern to be used during operation
        encoder - DBEncoder to be used
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Modify Documents
      • update

        public WriteResult update​(DBObject query,
                                  DBObject update,
                                  boolean upsert,
                                  boolean multi,
                                  WriteConcern concern,
                                  @Nullable
                                  Boolean bypassDocumentValidation,
                                  @Nullable
                                  DBEncoder encoder)
        Modify an existing document or documents in collection. By default the method updates a single document. The query parameter employs the same query selectors, as used in find(DBObject).
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        upsert - when true, inserts a document if no document matches the update query criteria
        multi - when true, updates all documents in the collection that match the update query criteria, otherwise only updates one
        concern - WriteConcern to be used during operation
        bypassDocumentValidation - whether to bypass document validation.
        encoder - the DBEncoder to use
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        2.14
        MongoDB documentation
        Modify
      • update

        public WriteResult update​(DBObject query,
                                  DBObject update,
                                  boolean upsert,
                                  boolean multi)
        Modify an existing document or documents in collection. The query parameter employs the same query selectors, as used in find().
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        upsert - when true, inserts a document if no document matches the update query criteria
        multi - when true, updates all documents in the collection that match the update query criteria, otherwise only updates one
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Modify Documents
      • update

        public WriteResult update​(DBObject query,
                                  DBObject update)
        Modify an existing document. The query parameter employs the same query selectors, as used in find().
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Modify Documents
      • updateMulti

        public WriteResult updateMulti​(DBObject query,
                                       DBObject update)
        Modify documents in collection. The query parameter employs the same query selectors, as used in find().
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Modify Documents
      • update

        public WriteResult update​(DBObject query,
                                  DBObject update,
                                  DBCollectionUpdateOptions options)
        Modify an existing document or documents in collection.
        Parameters:
        query - the selection criteria for the update
        update - the modifications to apply
        options - the options to apply to the update operation
        Returns:
        the result of the operation
        Throws:
        DuplicateKeyException - if the write failed to a duplicate unique key
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        3.4
        MongoDB documentation
        Modify
      • remove

        public WriteResult remove​(DBObject query)
        Remove documents from a collection.
        Parameters:
        query - the deletion criteria using query operators. Omit the query parameter or pass an empty document to delete all documents in the collection.
        Returns:
        the result of the operation
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the delete command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Remove Documents
      • remove

        public WriteResult remove​(DBObject query,
                                  WriteConcern writeConcern)
        Remove documents from a collection.
        Parameters:
        query - the deletion criteria using query operators. Omit the query parameter or pass an empty document to delete all documents in the collection.
        writeConcern - WriteConcern to be used during operation
        Returns:
        the result of the operation
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the delete command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Remove Documents
      • remove

        public WriteResult remove​(DBObject query,
                                  WriteConcern writeConcern,
                                  DBEncoder encoder)
        Remove documents from a collection.
        Parameters:
        query - the deletion criteria using query operators. Omit the query parameter or pass an empty document to delete all documents in the collection.
        writeConcern - WriteConcern to be used during operation
        encoder - DBEncoder to be used
        Returns:
        the result of the operation
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the delete command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Remove Documents
      • remove

        public WriteResult remove​(DBObject query,
                                  DBCollectionRemoveOptions options)
        Remove documents from a collection.
        Parameters:
        query - the deletion criteria using query operators. Omit the query parameter or pass an empty document to delete all documents in the collection.
        options - the options to apply to the delete operation
        Returns:
        the result of the operation
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the delete command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        3.4
        MongoDB documentation
        Remove Documents
      • find

        public DBCursor find​(DBObject query)
        Select documents in collection and get a cursor to the selected documents.
        Parameters:
        query - the selection criteria using query operators. Omit the query parameter or pass an empty document to return all documents in the collection.
        Returns:
        A cursor to the documents that match the query criteria
        MongoDB documentation
        Querying
      • find

        public DBCursor find​(DBObject query,
                             DBObject projection)
        Select documents in collection and get a cursor to the selected documents.
        Parameters:
        query - the selection criteria using query operators. Omit the query parameter or pass an empty document to return all documents in the collection.
        projection - specifies which fields MongoDB will return from the documents in the result set.
        Returns:
        A cursor to the documents that match the query criteria
        MongoDB documentation
        Querying
      • find

        public DBCursor find()
        Select all documents in collection and get a cursor to the selected documents.
        Returns:
        A cursor to the documents that match the query criteria
        MongoDB documentation
        Querying
      • find

        public DBCursor find​(@Nullable
                             DBObject query,
                             DBCollectionFindOptions options)
        Select documents in collection and get a cursor to the selected documents.
        Parameters:
        query - the selection criteria using query operators. Omit the query parameter or pass an empty document to return all documents in the collection.
        options - the options for the find operation.
        Returns:
        A cursor to the documents that match the query criteria
        Since:
        3.4
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne()
        Get a single document from collection.
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(DBObject query)
        Get a single document from collection.
        Parameters:
        query - the selection criteria using query operators.
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(DBObject query,
                                DBObject projection)
        Get a single document from collection.
        Parameters:
        query - the selection criteria using query operators.
        projection - specifies which fields MongoDB will return from the documents in the result set.
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(DBObject query,
                                DBObject projection,
                                DBObject sort)
        Get a single document from collection.
        Parameters:
        query - the selection criteria using query operators.
        projection - specifies which fields MongoDB will return from the documents in the result set.
        sort - A document whose fields specify the attributes on which to sort the result set.
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(DBObject query,
                                DBObject projection,
                                ReadPreference readPreference)
        Get a single document from collection.
        Parameters:
        query - the selection criteria using query operators.
        projection - specifies which fields MongoDB will return from the documents in the result set.
        readPreference - ReadPreference to be used for this operation
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(@Nullable
                                DBObject query,
                                @Nullable
                                DBObject projection,
                                @Nullable
                                DBObject sort,
                                ReadPreference readPreference)
        Get a single document from collection.
        Parameters:
        query - the selection criteria using query operators.
        projection - specifies which projection MongoDB will return from the documents in the result set.
        sort - A document whose fields specify the attributes on which to sort the result set.
        readPreference - ReadPreference to be used for this operation
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(Object id)
        Get a single document from collection by '_id'.
        Parameters:
        id - value of '_id' field of a document we are looking for
        Returns:
        A document with '_id' provided as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(Object id,
                                DBObject projection)
        Get a single document from collection by '_id'.
        Parameters:
        id - value of '_id' field of a document we are looking for
        projection - specifies which projection MongoDB will return from the documents in the result set.
        Returns:
        A document that satisfies the query specified as the argument to this method.
        MongoDB documentation
        Querying
      • findOne

        @Nullable
        public DBObject findOne​(@Nullable
                                DBObject query,
                                DBCollectionFindOptions findOptions)
        Get a single document from collection.
        Parameters:
        query - the selection criteria using query operators.
        findOptions - the options for the find operation.
        Returns:
        A document that satisfies the query specified as the argument to this method.
        Since:
        3.4
        MongoDB documentation
        Querying
      • count

        public long count()
        Same as getCount()
        Returns:
        the number of documents in collection
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Count
      • count

        public long count​(@Nullable
                          DBObject query)
        Get the count of documents in collection that would match a criteria.
        Parameters:
        query - specifies the selection criteria
        Returns:
        the number of documents that matches selection criteria
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Count
      • count

        public long count​(@Nullable
                          DBObject query,
                          ReadPreference readPreference)
        Get the count of documents in collection that would match a criteria.
        Parameters:
        query - specifies the selection criteria
        readPreference - ReadPreference to be used for this operation
        Returns:
        the number of documents that matches selection criteria
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Count
      • count

        public long count​(@Nullable
                          DBObject query,
                          DBCollectionCountOptions options)
        Get the count of documents in collection that would match a criteria.
        Parameters:
        query - specifies the selection criteria
        options - the options for the count operation.
        Returns:
        the number of documents that matches selection criteria
        Throws:
        MongoException - if the operation failed
        Since:
        3.4
        MongoDB documentation
        Count
      • getCount

        public long getCount()
        Get the count of documents in collection.
        Returns:
        the number of documents in collection
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Count
      • getCount

        public long getCount​(@Nullable
                             DBObject query)
        Get the count of documents in collection that would match a criteria.
        Parameters:
        query - specifies the selection criteria
        Returns:
        the number of documents that matches selection criteria
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Count
      • getCount

        public long getCount​(@Nullable
                             DBObject query,
                             DBCollectionCountOptions options)
        Get the count of documents in collection that would match a criteria.
        Parameters:
        query - specifies the selection criteria
        options - the options for the count operation.
        Returns:
        the number of documents that matches selection criteria
        Throws:
        MongoException - if the operation failed
        Since:
        3.4
        MongoDB documentation
        Count
      • rename

        public DBCollection rename​(String newName)
        Change the name of an existing collection.
        Parameters:
        newName - specifies the new name of the collection
        Returns:
        the collection with new name
        Throws:
        MongoException - if newName is the name of an existing collection.
        MongoDB documentation
        Rename Collection
      • rename

        public DBCollection rename​(String newName,
                                   boolean dropTarget)
        Change the name of an existing collection.
        Parameters:
        newName - specifies the new name of the collection
        dropTarget - If true, mongod will drop the collection with the target name if it exists
        Returns:
        the collection with new name
        Throws:
        MongoException - if target is the name of an existing collection and dropTarget=false.
        MongoDB documentation
        Rename Collection
      • distinct

        public List distinct​(String fieldName)
        Find the distinct values for a specified field across a collection and returns the results in an array.
        Parameters:
        fieldName - Specifies the field for which to return the distinct values.
        Returns:
        a List of the distinct values
        MongoDB documentation
        Distinct Command
      • distinct

        public List distinct​(String fieldName,
                             ReadPreference readPreference)
        Find the distinct values for a specified field across a collection and returns the results in an array.
        Parameters:
        fieldName - Specifies the field for which to return the distinct values
        readPreference - ReadPreference to be used for this operation
        Returns:
        a List of the distinct values
        MongoDB documentation
        Distinct Command
      • distinct

        public List distinct​(String fieldName,
                             DBObject query)
        Find the distinct values for a specified field across a collection and returns the results in an array.
        Parameters:
        fieldName - Specifies the field for which to return the distinct values
        query - specifies the selection query to determine the subset of documents from which to retrieve the distinct values
        Returns:
        an array of the distinct values
        MongoDB documentation
        Distinct Command
      • distinct

        public List distinct​(String fieldName,
                             DBObject query,
                             ReadPreference readPreference)
        Find the distinct values for a specified field across a collection and returns the results in an array.
        Parameters:
        fieldName - Specifies the field for which to return the distinct values
        query - specifies the selection query to determine the subset of documents from which to retrieve the distinct values
        readPreference - ReadPreference to be used for this operation
        Returns:
        A List of the distinct values
        MongoDB documentation
        Distinct Command
      • distinct

        public List distinct​(String fieldName,
                             DBCollectionDistinctOptions options)
        Find the distinct values for a specified field across a collection and returns the results in an array.
        Parameters:
        fieldName - Specifies the field for which to return the distinct values
        options - the options to apply for this operation
        Returns:
        A List of the distinct values
        Since:
        3.4
        MongoDB documentation
        Distinct Command
      • mapReduce

        public MapReduceOutput mapReduce​(String map,
                                         String reduce,
                                         String outputTarget,
                                         DBObject query)
        Allows you to run map-reduce aggregation operations over a collection.
        Parameters:
        map - a JavaScript function that associates or "maps" a value with a key and emits the key and value pair.
        reduce - a JavaScript function that "reduces" to a single object all the values associated with a particular key.
        outputTarget - specifies the location of the result of the map-reduce operation.
        query - specifies the selection criteria using query operators for determining the documents input to the map function.
        Returns:
        a MapReduceOutput which contains the results of this map reduce operation
        MongoDB documentation
        Map-Reduce
      • mapReduce

        public MapReduceOutput mapReduce​(String map,
                                         String reduce,
                                         String outputTarget,
                                         MapReduceCommand.OutputType outputType,
                                         DBObject query)
        Allows you to run map-reduce aggregation operations over a collection and saves to a named collection.
        Parameters:
        map - a JavaScript function that associates or "maps" a value with a key and emits the key and value pair.
        reduce - a JavaScript function that "reduces" to a single object all the values associated with a particular key.
        outputTarget - specifies the location of the result of the map-reduce operation.
        outputType - specifies the type of job output
        query - specifies the selection criteria using query operators for determining the documents input to the map function.
        Returns:
        a MapReduceOutput which contains the results of this map reduce operation
        MongoDB documentation
        Map-Reduce
      • mapReduce

        public MapReduceOutput mapReduce​(String map,
                                         String reduce,
                                         String outputTarget,
                                         MapReduceCommand.OutputType outputType,
                                         DBObject query,
                                         ReadPreference readPreference)
        Allows you to run map-reduce aggregation operations over a collection and saves to a named collection.
        Parameters:
        map - a JavaScript function that associates or "maps" a value with a key and emits the key and value pair.
        reduce - a JavaScript function that "reduces" to a single object all the values associated with a particular key.
        outputTarget - specifies the location of the result of the map-reduce operation.
        outputType - specifies the type of job output
        query - specifies the selection criteria using query operators for determining the documents input to the map function.
        readPreference - the read preference specifying where to run the query. Only applied for Inline output type
        Returns:
        a MapReduceOutput which contains the results of this map reduce operation
        MongoDB documentation
        Map-Reduce
      • mapReduce

        public MapReduceOutput mapReduce​(MapReduceCommand command)
        Allows you to run map-reduce aggregation operations over a collection.
        Parameters:
        command - specifies the details of the Map Reduce operation to perform
        Returns:
        a MapReduceOutput containing the results of the map reduce operation
        MongoDB documentation
        Map-Reduce
      • aggregate

        public Cursor aggregate​(List<? extends DBObject> pipeline,
                                AggregationOptions options)
        Method implements aggregation framework.
        Parameters:
        pipeline - operations to be performed in the aggregation pipeline
        options - options to apply to the aggregation
        Returns:
        the aggregation operation's result set
        MongoDB documentation
        Aggregation
        Since server release
        2.2
      • aggregate

        public Cursor aggregate​(List<? extends DBObject> pipeline,
                                AggregationOptions options,
                                ReadPreference readPreference)
        Method implements aggregation framework.
        Parameters:
        pipeline - operations to be performed in the aggregation pipeline
        options - options to apply to the aggregation
        readPreference - ReadPreference to be used for this operation
        Returns:
        the aggregation operation's result set
        MongoDB documentation
        Aggregation
        Since server release
        2.2
      • explainAggregate

        public CommandResult explainAggregate​(List<? extends DBObject> pipeline,
                                              AggregationOptions options)
        Return the explain plan for the aggregation pipeline.
        Parameters:
        pipeline - the aggregation pipeline to explain
        options - the options to apply to the aggregation
        Returns:
        the command result. The explain output may change from release to release, so best to simply log this.
        MongoDB documentation
        Aggregation
        Explain query
        Since server release
        3.6
      • getName

        public String getName()
        Get the name of a collection.
        Returns:
        the name of a collection
      • getFullName

        public String getFullName()
        Get the full name of a collection, with the database name as a prefix.
        Returns:
        the name of a collection
        MongoDB documentation
        Namespace
      • getCollection

        public DBCollection getCollection​(String name)
        Find a collection that is prefixed with this collection's name. A typical use of this might be
        
            DBCollection users = mongo.getCollection( "wiki" ).getCollection( "users" );
         
        Which is equivalent to
        
           DBCollection users = mongo.getCollection( "wiki.users" );
         
        Parameters:
        name - the name of the collection to find
        Returns:
        the matching collection
      • createIndex

        public void createIndex​(String name)
        Forces creation of an ascending index on a field with the default options.
        Parameters:
        name - name of field to index on
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Index Creation Tutorials
      • createIndex

        public void createIndex​(DBObject keys,
                                String name)
        Forces creation of an index on a set of fields, if one does not already exist.
        Parameters:
        keys - a document that contains pairs with the name of the field or fields to index and order of the index
        name - an identifier for the index. If null or empty, the default name will be used.
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Index Creation Tutorials
      • createIndex

        public void createIndex​(DBObject keys,
                                @Nullable
                                String name,
                                boolean unique)
        Forces creation of an index on a set of fields, if one does not already exist.
        Parameters:
        keys - a document that contains pairs with the name of the field or fields to index and order of the index
        name - an identifier for the index. If null or empty, the default name will be used.
        unique - if the index should be unique
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Index Creation Tutorials
      • createIndex

        public void createIndex​(DBObject keys)
        Creates an index on the field specified, if that index does not already exist.
        Parameters:
        keys - a document that contains pairs with the name of the field or fields to index and order of the index
        MongoDB documentation
        Index Creation Tutorials
      • createIndex

        public void createIndex​(DBObject keys,
                                DBObject options)
        Creates an index on the field specified, if that index does not already exist.

        Prior to MongoDB 3.0 the dropDups option could be used with unique indexes allowing documents with duplicate values to be dropped when building the index. Later versions of MongoDB will silently ignore this setting.

        Parameters:
        keys - a document that contains pairs with the name of the field or fields to index and order of the index
        options - a document that controls the creation of the index.
        MongoDB documentation
        Index Creation Tutorials
      • findAndModify

        @Nullable
        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      @Nullable
                                      DBObject sort,
                                      DBObject update)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        sort - determines which document the operation will modify if the query selects multiple documents
        update - the modifications to apply
        Returns:
        pre-modification document
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Find and Modify
      • findAndModify

        @Nullable
        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      DBObject update)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        update - the modifications to apply
        Returns:
        the document as it was before the modifications
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Find and Modify
      • findAndRemove

        @Nullable
        public DBObject findAndRemove​(@Nullable
                                      DBObject query)
        Atomically remove and return a single document. The returned document is the original document before removal.
        Parameters:
        query - specifies the selection criteria for the modification
        Returns:
        the document as it was before the modifications
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Find and Modify
      • findAndModify

        @Nullable
        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      @Nullable
                                      DBObject fields,
                                      @Nullable
                                      DBObject sort,
                                      boolean remove,
                                      @Nullable
                                      DBObject update,
                                      boolean returnNew,
                                      boolean upsert)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        fields - a subset of fields to return
        sort - determines which document the operation will modify if the query selects multiple documents
        remove - when true, removes the selected document
        returnNew - when true, returns the modified document rather than the original
        update - the modifications to apply
        upsert - when true, operation creates a new document if the query returns no documents
        Returns:
        the document as it was before the modifications, unless returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        MongoDB documentation
        Find and Modify
      • findAndModify

        @Nullable
        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      @Nullable
                                      DBObject fields,
                                      @Nullable
                                      DBObject sort,
                                      boolean remove,
                                      DBObject update,
                                      boolean returnNew,
                                      boolean upsert,
                                      WriteConcern writeConcern)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        fields - a subset of fields to return
        sort - determines which document the operation will modify if the query selects multiple documents
        remove - when true, removes the selected document
        returnNew - when true, returns the modified document rather than the original
        update - the modifications to apply
        upsert - when true, operation creates a new document if the query returns no documents
        writeConcern - the write concern to apply to this operation
        Returns:
        the document as it was before the modifications, unless returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        2.14
        MongoDB documentation
        Find and Modify
      • findAndModify

        @Nullable
        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      @Nullable
                                      DBObject fields,
                                      @Nullable
                                      DBObject sort,
                                      boolean remove,
                                      @Nullable
                                      DBObject update,
                                      boolean returnNew,
                                      boolean upsert,
                                      long maxTime,
                                      TimeUnit maxTimeUnit)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        fields - a subset of fields to return
        sort - determines which document the operation will modify if the query selects multiple documents
        remove - when true, removes the selected document
        returnNew - when true, returns the modified document rather than the original
        update - the modifications to apply
        upsert - when true, operation creates a new document if the query returns no documents
        maxTime - the maximum time that the server will allow this operation to execute before killing it.
        maxTimeUnit - the unit that maxTime is specified in
        Returns:
        the document as it was before the modifications, unless returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        2.12.0
        MongoDB documentation
        Find and Modify
      • findAndModify

        @Nullable
        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      @Nullable
                                      DBObject fields,
                                      @Nullable
                                      DBObject sort,
                                      boolean remove,
                                      @Nullable
                                      DBObject update,
                                      boolean returnNew,
                                      boolean upsert,
                                      long maxTime,
                                      TimeUnit maxTimeUnit,
                                      WriteConcern writeConcern)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        fields - a subset of fields to return
        sort - determines which document the operation will modify if the query selects multiple documents
        remove - when true, removes the selected document
        returnNew - when true, returns the modified document rather than the original
        update - performs an update of the selected document
        upsert - when true, operation creates a new document if the query returns no documents
        maxTime - the maximum time that the server will allow this operation to execute before killing it
        maxTimeUnit - the unit that maxTime is specified in
        writeConcern - the write concern to apply to this operation
        Returns:
        the document as it was before the modifications, unless returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        2.14.0
        MongoDB documentation
        Find and Modify
      • findAndModify

        @Nullable
        public DBObject findAndModify​(DBObject query,
                                      DBObject fields,
                                      DBObject sort,
                                      boolean remove,
                                      @Nullable
                                      DBObject update,
                                      boolean returnNew,
                                      boolean upsert,
                                      boolean bypassDocumentValidation,
                                      long maxTime,
                                      TimeUnit maxTimeUnit)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        fields - a subset of fields to return
        sort - determines which document the operation will modify if the query selects multiple documents
        remove - when true, removes the selected document
        returnNew - when true, returns the modified document rather than the original
        update - performs an update of the selected document
        upsert - when true, operation creates a new document if the query returns no documents
        bypassDocumentValidation - whether to bypass document validation.
        maxTime - the maximum time that the server will allow this operation to execute before killing it
        maxTimeUnit - the unit that maxTime is specified in
        Returns:
        the document as it was before the modifications, unless returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        2.14.0
        MongoDB documentation
        Find and Modify
      • findAndModify

        public DBObject findAndModify​(@Nullable
                                      DBObject query,
                                      @Nullable
                                      DBObject fields,
                                      @Nullable
                                      DBObject sort,
                                      boolean remove,
                                      @Nullable
                                      DBObject update,
                                      boolean returnNew,
                                      boolean upsert,
                                      boolean bypassDocumentValidation,
                                      long maxTime,
                                      TimeUnit maxTimeUnit,
                                      WriteConcern writeConcern)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        fields - a subset of fields to return
        sort - determines which document the operation will modify if the query selects multiple documents
        remove - when true, removes the selected document
        returnNew - when true, returns the modified document rather than the original
        update - performs an update of the selected document
        upsert - when true, operation creates a new document if the query returns no documents
        bypassDocumentValidation - whether to bypass document validation.
        maxTime - the maximum time that the server will allow this operation to execute before killing it
        maxTimeUnit - the unit that maxTime is specified in
        writeConcern - the write concern to apply to this operation
        Returns:
        the document as it was before the modifications, unless returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        2.14.0
        MongoDB documentation
        Find and Modify
      • findAndModify

        public DBObject findAndModify​(DBObject query,
                                      DBCollectionFindAndModifyOptions options)
        Atomically modify and return a single document. By default, the returned document does not include the modifications made on the update.
        Parameters:
        query - specifies the selection criteria for the modification
        options - the options regarding the find and modify operation
        Returns:
        the document as it was before the modifications, unless oprtions.returnNew is true, in which case it returns the document after the changes were made
        Throws:
        WriteConcernException - if the write failed due some other failure specific to the update command
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed for some other reason
        Since:
        3.4
        MongoDB documentation
        Find and Modify
      • getDB

        public DB getDB()
        Returns the database this collection is a member of.
        Returns:
        this collection's database
        MongoDB documentation
        Database
      • getWriteConcern

        public WriteConcern getWriteConcern()
        Get the WriteConcern for this collection.
        Returns:
        the default write concern for this collection
        MongoDB documentation
        Write Concern
      • setWriteConcern

        public void setWriteConcern​(WriteConcern writeConcern)
        Set the WriteConcern for this collection. Will be used for writes to this collection. Overrides any setting of write concern at the DB level.
        Parameters:
        writeConcern - WriteConcern to use
        MongoDB documentation
        Write Concern
      • setReadPreference

        public void setReadPreference​(ReadPreference preference)
        Sets the ReadPreference for this collection. Will be used as default for reads from this collection; overrides DB and Connection level settings. See the documentation for ReadPreference for more information.
        Parameters:
        preference - ReadPreference to use
        MongoDB documentation
        Read Preference
      • setReadConcern

        public void setReadConcern​(ReadConcern readConcern)
        Sets the read concern for this collection.
        Parameters:
        readConcern - the read concern to use for this collection
        Since:
        3.3
        MongoDB documentation
        Read Concern
        Since server release
        3.2
      • getReadConcern

        public ReadConcern getReadConcern()
        Get the read concern for this collection.
        Returns:
        the ReadConcern
        Since:
        3.3
        MongoDB documentation
        Read Concern
        Since server release
        3.2
      • drop

        public void drop()
        Drops (deletes) this collection from the database. Use with care.
        Throws:
        MongoCommandException - if the write failed due to a specific command exception
        MongoException - if the operation failed
        MongoDB documentation
        Drop Command
      • getDBDecoderFactory

        public DBDecoderFactory getDBDecoderFactory()
        Get the decoder factory for this collection. A null return value means that the default from MongoClientOptions is being used.
        Returns:
        the factory
      • setDBDecoderFactory

        public void setDBDecoderFactory​(@Nullable
                                        DBDecoderFactory factory)
        Set a custom decoder factory for this collection. Set to null to use the default from MongoClientOptions.
        Parameters:
        factory - the factory to set.
      • getDBEncoderFactory

        public DBEncoderFactory getDBEncoderFactory()
        Get the encoder factory for this collection. A null return value means that the default from MongoClientOptions is being used.
        Returns:
        the factory
      • setDBEncoderFactory

        public void setDBEncoderFactory​(@Nullable
                                        DBEncoderFactory factory)
        Set a custom encoder factory for this collection. Set to null to use the default from MongoClientOptions.
        Parameters:
        factory - the factory to set.
      • getIndexInfo

        public List<DBObject> getIndexInfo()
        Return a list of the indexes for this collection. Each object in the list is the "info document" from MongoDB
        Returns:
        list of index documents
        Throws:
        MongoException - if the operation failed
        MongoDB documentation
        Indexes
      • dropIndex

        public void dropIndex​(DBObject index)
        Drops an index from this collection. The DBObject index parameter must match the specification of the index to drop, i.e. correct key name and type must be specified.
        Parameters:
        index - the specification of the index to drop
        Throws:
        MongoException - if the index does not exist
        MongoDB documentation
        Indexes
      • dropIndex

        public void dropIndex​(String indexName)
        Drops the index with the given name from this collection.
        Parameters:
        indexName - name of index to drop
        Throws:
        MongoException - if the index does not exist
        MongoDB documentation
        Indexes
      • dropIndexes

        public void dropIndexes()
        Drop all indexes on this collection. The default index on the _id field will not be deleted.
        MongoDB documentation
        Indexes
      • dropIndexes

        public void dropIndexes​(String indexName)
        Drops the index with the given name from this collection. This method is exactly the same as dropIndex(indexName).
        Parameters:
        indexName - name of index to drop
        Throws:
        MongoException - if the index does not exist
        MongoDB documentation
        Indexes
      • getStats

        public CommandResult getStats()
        The collStats command returns a variety of storage statistics for a given collection
        Returns:
        a CommandResult containing the statistics about this collection
        MongoDB documentation
        collStats Command
      • isCapped

        public boolean isCapped()
        Checks whether this collection is capped
        Returns:
        true if this is a capped collection
        MongoDB documentation
        Capped Collections
      • getObjectClass

        public Class getObjectClass()
        Gets the default class for objects in the collection
        Returns:
        the class
      • setObjectClass

        public void setObjectClass​(Class<? extends DBObject> aClass)
        Sets a default class for objects in this collection; null resets the class to nothing.
        Parameters:
        aClass - the class
      • setInternalClass

        public void setInternalClass​(String path,
                                     Class<? extends DBObject> aClass)
        Sets the internal class for the given path in the document hierarchy
        Parameters:
        path - the path to map the given Class to
        aClass - the Class to map the given path to
      • initializeOrderedBulkOperation

        public BulkWriteOperation initializeOrderedBulkOperation()

        Creates a builder for an ordered bulk write operation, consisting of an ordered collection of write requests, which can be any combination of inserts, updates, replaces, or removes. Write requests included in the bulk operations will be executed in order, and will halt on the first failure.

        Note: While this bulk write operation will execute on MongoDB 2.4 servers and below, the writes will be performed one at a time, as that is the only way to preserve the semantics of the value returned from execution or the exception thrown.

        Note: While a bulk write operation with a mix of inserts, updates, replaces, and removes is supported, the implementation will batch up consecutive requests of the same type and send them to the server one at a time. For example, if a bulk write operation consists of 10 inserts followed by 5 updates, followed by 10 more inserts, it will result in three round trips to the server.

        Returns:
        the builder
        Since:
        2.12
        MongoDB documentation
        initializeOrderedBulkOp()
      • initializeUnorderedBulkOperation

        public BulkWriteOperation initializeUnorderedBulkOperation()

        Creates a builder for an unordered bulk operation, consisting of an unordered collection of write requests, which can be any combination of inserts, updates, replaces, or removes. Write requests included in the bulk operation will be executed in an undefined order, and all requests will be executed even if some fail.

        Note: While this bulk write operation will execute on MongoDB 2.4 servers and below, the writes will be performed one at a time, as that is the only way to preserve the semantics of the value returned from execution or the exception thrown.

        Returns:
        the builder
        Since:
        2.12
        MongoDB documentation
        initializeUnorderedBulkOp()