Databases and Collections

Prerequisites

You must include the following import statements in your program to run the code examples in this guide:

import com.mongodb.reactivestreams.client.MongoClients;
import com.mongodb.reactivestreams.client.MongoClient;
import com.mongodb.reactivestreams.client.MongoCollection;
import com.mongodb.reactivestreams.client.MongoDatabase;
import static com.mongodb.client.model.Filters.*;
import com.mongodb.client.model.CreateCollectionOptions;
import com.mongodb.client.model.ValidationOptions;

Connect to a MongoDB Deployment

First, connect to a running MongoDB deployment.

The following code connects to a standalone MongoDB deployment running on localhost on port 27017:

MongoClient mongoClient = MongoClients.create();

To learn more about connecting to MongoDB deployments, see the Connect to MongoDB tutorial.

Access a Database

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

Pass the name of the database as a parameter to the getDatabase() method. If a database does not exist, MongoDB creates it when you insert any data into the database.

The following example accesses the test database:

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

Access a Collection

After you create a MongoDatabase instance, use the getCollection() method to access a collection from within that database.

Pass the name of the collection as a parameter to the getCollection() method.

Using the database instance created in the preceding section, the following code accesses the collection named myTestCollection:

MongoCollection<Document> coll = database.getCollection("myTestCollection");

If a collection with that name does not exist, MongoDB creates it when you first insert data into that collection.

You can also directly create a collection with various options, such as setting the maximum size or creating documentation validation rules.

Create a Collection

The driver provides the createCollection() method to directly create a collection. When you create a collection, you can specify various collection options, such as a maximum size or documentation validation rules, with the CreateCollectionOptions class.

If you are not specifying any options, you do not need to directly create the collection since MongoDB automatically creates new collections when you first insert data.

database.createCollection(
    "cappedCollection",
    new CreateCollectionOptions().capped(true).sizeInBytes(0x100000)
).subscribe(new OperationSubscriber<Void>());

ValidationOptions collOptions = new ValidationOptions().validator(
         Filters.or(Filters.exists("email"), Filters.exists("phone")));
database.createCollection(
    "contacts",
    new CreateCollectionOptions().validationOptions(collOptions)
).subscribe(new OperationSubscriber<Void>());

Get A List of Collections

You can get a list of the collections in a database by using the MongoDatabase.listCollectionNames() method:

database.listCollectionNames().subscribe(new PrintToStringSubscriber<String>());

Drop a Collection

You can drop a collection and delete all of the data in the collection by using the MongoCollection.drop() method:

MongoCollection<Document> collection = database.getCollection("contacts");
collection.drop().subscribe(new OperationSubscriber<Void>());

Immutability

MongoDatabase and MongoCollection instances are immutable. To create new instances from existing instances that have different properties, such as different read concerns, read preferences, and write concerns, the MongoDatabase and MongoCollection class provides the following methods:

• MongoDatabase.withReadConcern()

• MongoDatabase.withReadPreference()

• MongoDatabase.withWriteConcern()

• MongoCollection.withReadConcern()

• MongoCollection.withReadPreference()

• MongoCollection.withWriteConcern()

To learn more, see the Read Operations and Write Operations tutorials.

CodecRegistry

An overload of the getCollection() method allows you to specify a different class for representing BSON documents. For example, you might want to use the strict and type-safe BsonDocument class to model your documents when performing CRUD operations:

// pass BsonDocument.class as the second argument
MongoCollection<BsonDocument> collection = database
    .getCollection("mycoll", BsonDocument.class);
// insert a document
BsonDocument document = BsonDocument.parse("{x: 1}");
collection.insertOne(document).subscribe(new OperationSubscriber<Void>());
document.append("x", new BsonInt32(2)).append("y", new BsonInt32(3));
// replace a document
collection.replaceOne(Filters.eq("_id", document.get("_id")), document)
    .subscribe(new PrintSubscriber<UpdateResult>("Update Result: %s"));
// find documents
collection.find().subscribe(new PrintDocumentSubscriber());

There are two requirements that any class must meet to be used in this way:

• Codec instance for the class must be registered in the CodecRegistry for the MongoCollection.

• Codec instance must be one that encodes and decodes a full BSON document, and not just, for example, a single BSON value like an Int32.

By default, a MongoCollection is configured with Codec instances for three classes:

• Document

• BsonDocument

• BasicDBObject

Applications are free to register Codec implementations for other classes by customizing the CodecRegistry. New CodecRegistry instances are configurable at the following levels:

• In a MongoClient within MongoClientSettings

• In a MongoDatabase within its withCodecRegistry method

• In a MongoCollection within its withCodecRegistry method

Consider the case of encoding and decoding instances of the UUID class. The driver by default encodes instances of UUID by using a byte ordering that is not compatible with other MongoDB drivers, and changing the default would be dangerous.

It is possible for new applications that require interoperability across multiple drivers to be able to change that default, and they can do that by specifying a CodecRegistry

// replaces the default UuidCodec to use the standard UUID representation
CodecRegistry codecRegistry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(new UuidCodec(UuidRepresentation.STANDARD)
), MongoClientSettings.getDefaultCodecRegistry());
// globally
MongoClientSettings settings = MongoClientSettings.builder()
    .codecRegistry(codecRegistry).build();
MongoClient client = MongoClients.create(settings);
// or per database
MongoDatabase database = client.getDatabase("mydb")
    .withCodecRegistry(codecRegistry);
// or per collection
MongoCollection<Document> collection = database.getCollection("mycoll")
    .withCodecRegistry(codecRegistry);