Quick Start

The code examples in this guide come from the QuickTour.java file in the driver source code GitHub repository.

Note

For instructions about how to install the Java Reactive Streams driver, see the installation guide.

Important

This guide uses the Subscriber implementations, which are described in the Quick Start Primer.

Prerequisites

You must set up the following components to run the code examples in this guide:

MongoDB server running on the default port for MongoDB (27017)
Driver dependency installed in your project

The following import statements:

import com.mongodb.bulk.BulkWriteResult;
import com.mongodb.client.model.BulkWriteOptions;
import com.mongodb.client.model.DeleteOneModel;
import com.mongodb.client.model.InsertOneModel;
import com.mongodb.client.model.ReplaceOneModel;
import com.mongodb.client.model.UpdateOneModel;
import com.mongodb.client.model.WriteModel;
import com.mongodb.client.result.InsertOneResult;
import com.mongodb.client.result.InsertManyResult;
import com.mongodb.client.result.DeleteResult;
import com.mongodb.client.result.UpdateResult;
import com.mongodb.reactivestreams.client.MongoClient;
import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoCollection;
import com.mongodb.reactivestreams.client.MongoDatabase;
import org.bson.Document;
import java.util.ArrayList;
import java.util.List;
import static com.mongodb.client.model.Accumulators.*;
import static com.mongodb.client.model.Aggregates.*;
import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Projections.*;
import static com.mongodb.client.model.Sorts.*;
import static com.mongodb.client.model.Updates.*;
import static java.util.Arrays.asList;
import static java.util.Collections.singletonList;

Make a Connection

Use the MongoClients.create() method to make a connection to a running MongoDB deployment.

The MongoClient instance represents a pool of connections to the database. You need only one instance of MongoClient even when using concurrent operation threads.

Important

Typically, you create only one MongoClient instance for a given MongoDB deployment, such as a standalone deployment, replica set, or a sharded cluster, and use the client across your application. However, if you do create multiple instances, keep the following in mind:

All resource-usage limits (for example, max connections) apply to each MongoClient instance.
To dispose of an instance, call the MongoClient.close() method to clean up resources.

Connect to a Single MongoDB Deployment

The following example shows several ways to connect to a single MongoDB deployment.

You can connect to a single MongoDB deployment in the following ways:

Instantiate a MongoClient object without any parameters to connect to a MongoDB server running on localhost on port 27017:
```
MongoClient mongoClient = MongoClients.create();
```

Explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port 27017:

MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder()
       .applyToClusterSettings(builder ->
           builder.hosts(Arrays.asList(new ServerAddress("hostOne"))))
       .build());

Explicitly specify the hostname and the port:

MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder()
       .applyToClusterSettings(builder ->
           builder.hosts(Arrays.asList(new ServerAddress("hostOne", 27018))))
       .build());

Specify the ConnectionString:

MongoClient mongoClient = MongoClients.create("mongodb://hostOne:27017");

Access a Database

Once you have a MongoClient instance connected to a MongoDB deployment, use the MongoClient.getDatabase() method to access a database.

Specify the name of the database to the getDatabase() method. If a database does not exist, MongoDB creates the database when you first store data for that database.

The following example accesses the mydb database:

MongoDatabase database = mongoClient.getDatabase("mydb");

MongoDatabase instances are immutable.

Access a Collection

Once you have a MongoDatabase instance, use the getCollection()` method to access a collection.

Specify the name of the collection to the getCollection() method. If a collection does not exist, MongoDB creates the collection when you first store data for that collection.

For example, using the database instance, the following statement accesses the collection named test in the mydb database:

MongoCollection<Document> collection = database.getCollection("test");

MongoCollection instances are immutable.

Create a Document

To create the document by using the driver, use the Document class.

For example, consider the following JSON document:

{
   "name" : "MongoDB",
   "type" : "database",
   "count" : 1,
   "versions": [ "v3.2", "v3.0", "v2.6" ],
   "info" : { x : 203, y : 102 }
}

To create the document by using the driver, instantiate a Document object with a field and value, and use its append() method to include additional fields and values to the document object. The value can be another Document object to specify an embedded document:

Document doc = new Document("name", "MongoDB")
    .append("type", "database")
    .append("count", 1)
    .append("versions", Arrays.asList("v3.2", "v3.0", "v2.6"))
    .append("info", new Document("x", 203).append("y", 102));

Note

The BSON type of an array corresponds to the Java type java.util.List. For a list of the BSON types and the corresponding types in Java, see the Document mapping.

Insert a Document

Once you have the MongoCollection object, you can insert documents into the collection.

Insert One Document

To insert a single document into a collection, you can use the insertOne() method.

var subscriber = new OperationSubscriber<InsertOneResult>();
collection.insertOne(doc).subscribe(subscriber);
// Wait for the insertOne operation to complete
subscriber.await();

Note

If no top-level _id field is specified in the document, MongoDB automatically generates a value and adds this field to the inserted document.

Important

In the API, all methods returning a Publisher instance are cold streams, meaning that nothing happens until they are subscribed to.

For example, the example below does nothing:

Publisher<InsertOneResult> publisher = collection.insertOne(doc);

The operation happens only when a Publisher is subscribed to and data is requested.

publisher.subscribe(new Subscriber<InsertOneResult>() {
    @Override
    public void onSubscribe(final Subscription s) {
        s.request(1);  // <--- Data requested and the insertion will now occur
    }
    @Override
    public void onNext(final InsertOneResult result) {
        System.out.println("Inserted: " + result);
    }
    @Override
    public void onError(final Throwable t) {
        System.out.println("Failed");
    }
    @Override
    public void onComplete() {
        System.out.println("Completed");
    }
});

Once the document has been inserted, the onNext() method is called and prints Inserted: followed by the result. Finally, the onComplete() method prints Completed. If there was an error for any reason, the onError() method would print Failed.

Insert Multiple Documents

To insert multiple documents, you can use the collection's insertMany() method, which takes a list of documents to insert.

The following example adds multiple documents in the following form:

{ "i" : value }

Create the documents in a loop and add them to the documents list:

List<Document> documents = new ArrayList<Document>();
for (int i = 0; i < 100; i++) {
    documents.add(new Document("i", i));
}

To insert these documents into the collection, pass the list of documents to the insertMany() method:

var subscriber = new OperationSubscriber<InsertManyResult>();
collection.insertMany(documents).subscribe(subscriber);
// Wait for the insertMany operation to complete
subscriber.await();

The previous example blocks on the Publisher to finish. This ensures that the data is in the database before the next operation runs.

Count Documents in A Collection

To count the number of documents in a collection, you can use the collection's countDocuments() method. The following code should print 101, describing the 100 inserted documents by using insertMany() and the 1 inserted by using insertOne().

collection.count()
    .subscribe(new PrintSubscriber<Long>("total # of documents: %s"));

Query the Collection

To query the collection, you can use the collection's find() method. You can call the method without any arguments to query all documents in a collection or pass a filter to query for documents that match the filter criteria.

Find the First Document in a Collection

To return the first document in the collection, use the find() method without any parameters and chain the first() method.

Tip

The find().first() construct is useful for queries that should only match a single document or if you are interested only in the first matching document.

The following example prints the first document found in the collection:

collection.find().first().subscribe(new PrintDocumentSubscriber());

The example should print the following document:

{
  "_id" : { "$oid" : "551582c558c7b4fbacf16735" },
  "name" : "MongoDB",
  "type" : "database",
  "count" : 1,
  "info" : { "x" : 203, "y" : 102 }
}

Note

The _id element has been added automatically by MongoDB to your document and your value will differ from the one shown. MongoDB reserves field names that start with _ and $ for internal use.

Find All Documents in a Collection

To retrieve all of the documents in the collection, use the find() method. The find() method returns a FindPublisher instance that provides a fluent interface for chaining or controlling find operations. The following code retrieves and prints all documents in the collection:

collection.find().subscribe(new PrintDocumentSubscriber());

Specify a Query Filter

To query for documents that match certain conditions, pass a filter object to the find() method. To facilitate creating filter objects, the driver provides Filters helper methods.

Get A Single Document That Matches a Filter

To find the first document in which the field i has the value 71, pass an eq() filter definition to specify the equality condition:

collection.find(eq("i", 71)).first().subscribe(new PrintDocumentSubscriber());

The example prints one document:

{ "_id" : { "$oid" : "5515836e58c7b4fbc756320b" }, "i" : 71 }

Get All Documents That Match a Filter

The following example returns and prints all documents in which the value of i is greater than 50:

collection.find(gt("i", 50)).subscribe(new PrintDocumentSubscriber());

To specify a filter for a range, such as 50 < i <= 100, you can use the and() helper:

collection.find(and(gt("i", 50), lte("i", 100)))
    .subscribe(new PrintDocumentSubscriber());

Update Documents

To update documents in a collection, you can use the collection's updateOne() and updateMany() methods.

Pass the following parameters to the methods:

Filter object to determine the document or documents to update. To facilitate creating filter objects, the driver provides Filters helper methods. To specify an empty filter and match all documents in the collection, use an empty Document object.
Update document that specifies the modifications. To view a list of the available operators, see Update Operators in the Server manual.

The update methods return an UpdateResult type that provides information about the operation, including the number of documents modified by the update.

Update a Single Document

To update a single document, use the updateOne() method.

The following example updates the first document in which i is 10 and sets the value of i to 110:

collection.updateOne(eq("i", 10), set("i", 110))
    .subscribe(new PrintSubscriber<UpdateResult>("Update Result: %s"));

Update Multiple Documents

To update all documents matching a query filter, use the updateMany() method.

The following example increments the value of i by 100 in all documents in which the value of i is less than 100:

UpdateResult updateResult = collection.updateMany(lt("i", 100), inc("i", 100))
    .subscribe(new PrintSubscriber<UpdateResult>("Update Result: %s"));

Delete Documents

To delete documents from a collection, you can use the collection's deleteOne() and deleteMany() methods.

Pass a filter object to determine the document or documents to delete. To facilitate creating filter objects, the driver provides Filters helper methods. To specify an empty filter and match all documents in the collection, use an empty Document object.

The delete methods return a DeleteResult that provides information about the operation, including the number of documents deleted.

Delete a Single Document That Matches a Filter

To delete a single document that matches the filter, use the deleteOne() method.

The following example deletes the first document in which the value of i equals 110:

collection.deleteOne(eq("i", 110))
    .subscribe(new PrintSubscriber<DeleteResult>("Delete Result: %s"));

Delete All Documents That Match a Filter

To delete all documents that match the filter, use the deleteMany() method.

The following example deletes all documents in which the value of i is greater or equal to 100:

DeleteResult deleteResult = collection.deleteMany(gte("i", 100))
    .subscribe(new PrintSubscriber<DeleteResult>("Delete Result: %s"));

Create Indexes

To create an index on a field or fields, pass an index specification document to the createIndex() method. An index key specification document contains the fields to index and the index type for each field, as modeled by the following document:

new Document(<field1>, <type1>).append(<field2>, <type2>) ...

To create an ascending index type, specify 1 for <type>. To create a descending index type, specify -1 for <type>.

The following example creates an ascending index on the i field:

collection.createIndex(new Document("i", 1))
    .subscribe(new PrintSubscriber<String>("Create Index Result: %s"));

To view a list of other index types, see the Create Indexes guide.

Additional Information

For additional tutorials that demonstrate how to use MongoDB with POJOs, see the Quick Start (POJO Examples) guide.

To find additional tutorials, see the Tutorials section.

Back

Primer

Quick Start (POJO Examples)

Quick Start.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Note

Important

Prerequisites

Make a Connection

Important

Connect to a Single MongoDB Deployment

Access a Database

Access a Collection

Create a Document

Note

Insert a Document

Insert One Document

Note

Important

Insert Multiple Documents

Count Documents in A Collection

Query the Collection

Find the First Document in a Collection

Tip

Note

Find All Documents in a Collection

Specify a Query Filter

Get A Single Document That Matches a Filter

Get All Documents That Match a Filter

Update Documents

Update a Single Document

Update Multiple Documents

Delete Documents

Delete a Single Document That Matches a Filter

Delete All Documents That Match a Filter

Create Indexes

Additional Information

Quick Start