For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
- MongoDB Driver
- Tutorials
- Write Operations
Write Operations (Insert, Update, Replace, Delete)
Perform write operations to insert new documents into a collection, update existing document or documents in a collection, replace an existing document in a collection, or delete existing document or documents from a collection.
Prerequisites
The example below requires a
restaurants
collection in thetest
database. To create and populate the collection, follow the directions in github.Include the following import statements:
import com.mongodb.*; import com.mongodb.client.MongoClients; import com.mongodb.clientMongoClient; import com.mongodb.client.MongoCollection; import com.mongodb.client.MongoDatabase; import com.mongodb.client.model.Filters; import static com.mongodb.client.model.Filters.*; import static com.mongodb.client.model.Updates.*; import com.mongodb.client.model.UpdateOptions; import com.mongodb.client.result.*; import org.bson.Document; import org.bson.types.ObjectId; import java.util.List; import java.util.Arrays; import java.util.ArrayList;
Connect to a MongoDB Deployment
Connect to a MongoDB deployment and declare and define a MongoDatabase
instance.
For example, include the following code to connect to a standalone MongoDB deployment running on localhost on port 27017
and define database
to refer to the test
database and collection
to refer to the restaurants
collection:
MongoClient mongoClient = MongoClients.create();
MongoDatabase database = mongoClient.getDatabase("test");
MongoCollection<Document> collection = database.getCollection("restaurants");
For additional information on connecting to MongoDB, see Connect to MongoDB.
Insert New Document
To insert a single document into the collection, you can use the collection’s insertOne()
method.
Document document = new Document("name", "Café Con Leche")
.append("contact", new Document("phone", "228-555-0149")
.append("email", "cafeconleche@example.com")
.append("location",Arrays.asList(-73.92502, 40.8279556)))
.append("stars", 3)
.append("categories", Arrays.asList("Bakery", "Coffee", "Pastries"));
collection.insertOne(document);
Note
If no top-level _id
field is specified in the document, the Java driver automatically adds the _id
field to the inserted document.
Insert Multiple Documents
To add multiple documents, you can use the collection’s insertMany()
method, which takes a list of documents to insert.
The following example inserts two documents to the collection:
Document doc1 = new Document("name", "Amarcord Pizzeria")
.append("contact", new Document("phone", "264-555-0193")
.append("email", "amarcord.pizzeria@example.net")
.append("location",Arrays.asList(-73.88502, 40.749556)))
.append("stars", 2)
.append("categories", Arrays.asList("Pizzeria", "Italian", "Pasta"));
Document doc2 = new Document("name", "Blue Coffee Bar")
.append("contact", new Document("phone", "604-555-0102")
.append("email", "bluecoffeebar@example.com")
.append("location",Arrays.asList(-73.97902, 40.8479556)))
.append("stars", 5)
.append("categories", Arrays.asList("Coffee", "Pastries"));
List<Document> documents = new ArrayList<Document>();
documents.add(doc1);
documents.add(doc2);
collection.insertMany(documents);
Note
If no top-level _id
field is specified in the documents, the Java driver automatically adds the _id
field to the inserted documents.
Update Existing Documents
To update existing documents in a collection, you can use the collection’s updateOne()
or updateMany
methods.
Filters
You can pass in a filter document to the methods to specify which documents to update. The filter document specification is the same as for read operations. To facilitate creating filter objects, Java driver provides the Filters
helper.
To specify an empty filter (i.e. match all documents in a collection), use an empty Document
object.
Update Operators
To change a field in a document, MongoDB provides update operators. To specify the modification to perform using the update operators, use an updates document.
To facilitate the creation of updates documents, the Java driver provides the Updates
class.
important
The _id
field is immutable; i.e. you cannot change the value of the _id
field.
Update a Single Document
The updateOne()
method updates at most a single document, even if the filter condition matches multiple documents in the collection.
The following operation on the restaurants
collection updates a document whose _id
field equals ObjectId("57506d62f57802807471dd41")
.
collection.updateOne(
eq("_id", new ObjectId("57506d62f57802807471dd41")),
combine(set("stars", 1), set("contact.phone", "228-555-9999"), currentDate("lastModified")));
Specifically, the operation uses:
Updates.set
to set the value of thestars
field to1
and thecontact.phone
field to"228-555-9999"
, andUpdates.currentDate
to modify thelastModified
field to the current date. If thelastModified
field does not exist, the operator adds the field to the document.
tip
In some cases where you may need to update many fields in a document, it may be more efficient to replace the document. See Replace a Document.
Update Multiple Documents
The updateMany
method updates all documents that match the filter condition.
The following operation on the restaurants
collection updates all documents whose stars
field equals 2
.
collection.updateMany(
eq("stars", 2),
combine(set("stars", 0), currentDate("lastModified")));
Specifically, the operation uses:
Updates.set
to set the value of thestars
field to0
, andUpdates.currentDate
to modify thelastModified
field to the current date. If thelastModified
field does not exist, the operator adds the field to the document.
Update Options
With the updateOne()
and updateMany
methods, you can include an UpdateOptions
document to specify the upsert
option or the bypassDocumentationValidation
option.
collection.updateOne(
eq("_id", 1),
combine(set("name", "Fresh Breads and Tulips"), currentDate("lastModified")),
new UpdateOptions().upsert(true).bypassDocumentValidation(true));
Replace an Existing Document
To replace an existing document in a collection, you can use the collection’s replaceOne
method.
important
The _id
field is immutable; i.e. you cannot replace the _id
field value.
Filters
You can pass in a filter document to the method to specify which document to replace. The filter document specification is the same as for read operations. To facilitate creating filter objects, Java driver provides the Filters
helper.
To specify an empty filter (i.e. match all documents in a collection), use an empty Document
object.
The replaceOne
method replaces at most a single document, even if the filter condition matches multiple documents in the collection.
Replace a Document
To replace a document, pass a new document to the replaceOne
method.
important
The replacement document can have different fields from the original document. In the replacement document, you can omit the _id
field since the _id
field is immutable; however, if you do include the _id
field, you cannot specify a different value for the _id
field.
The following operation on the restaurants
collection replaces the document whose _id
field equals ObjectId("57506d62f57802807471dd41")
.
collection.replaceOne(
eq("_id", new ObjectId("57506d62f57802807471dd41")),
new Document("name", "Green Salads Buffet")
.append("contact", "TBD")
.append("categories", Arrays.asList("Salads", "Health Foods", "Buffet")));
See also Update a Document.
Update Options
With the replaceOne
, you can include an UpdateOptions
document to specify the upsert
option or the bypassDocumentationValidation
option.
collection.replaceOne(
eq("name", "Orange Patisserie and Gelateria"),
new Document("stars", 5)
.append("contact", "TBD")
.append("categories", Arrays.asList("Cafe", "Pastries", "Ice Cream")),
new UpdateOptions().upsert(true).bypassDocumentValidation(true));
Delete Documents
To delete documents in a collection, you can use the
deleteOne
and deleteMany
methods.
Filters
You can pass in a filter document to the methods to specify which documents to delete. The filter document specification is the same as for read operations. To facilitate creating filter objects, Java driver provides the Filters
helper.
To specify an empty filter (i.e. match all documents in a collection), use an empty Document
object.
Delete a Single Document
The deleteOne
method deletes at most a single document, even if the filter condition matches multiple documents in the collection.
The following operation on the restaurants
collection deletes a document whose _id
field equals ObjectId("57506d62f57802807471dd41")
.
collection.deleteOne(eq("_id", new ObjectId("57506d62f57802807471dd41")));
Delete Multiple Documents
The deleteMany
method deletes all documents that match the filter condition.
The following operation on the restaurants
collection deletes all documents whose stars
field equals 4
.
collection.deleteMany(eq("stars", 4));
See also Drop a Collection.
Write Concern
Write concern describes the level of acknowledgement requested from MongoDB for write operations.
Applications can configure write concern at three levels:
In a
MongoClient()
- Via
MongoClientOptions
, as in the following example:
MongoClientOptions options = MongoClientOptions.builder().writeConcern(WriteConcern.MAJORITY).build(); MongoClient mongoClient = new MongoClient(Arrays.asList( new ServerAddress("host1", 27017), new ServerAddress("host1", 27018)), options);
- Via
MongoClientURI
, as in the following example:
MongoClient mongoClient = new MongoClient( new MongoClientURI("mongodb://host1:27017,host2:27017/?w=majority"));
- Via
In a
MongoDatabase
via itswithWriteConcern
method, as in the following example:MongoDatabase database = mongoClient.getDatabase("test").withWriteConcern(WriteConcern.MAJORITY);
In a
MongoCollection
via itswithWriteConcern
method, as in the following example:MongoCollection<Document> collection = database.getCollection("restaurants").withWriteConcern(WriteConcern.MAJORITY);
MongoDatabase
and MongoCollection
instances are immutable. Calling .withWriteConcern()
on an existing MongoDatabase
or MongoCollection
instance returns a new instance and does not affect the instance on which the method is called.
For example, in the following, the collWithWriteConcern
instance has the write concern of majority whereas the write concern of the collection
is unaffected.
MongoCollection<Document> collWithWriteConcern = collection
.withWriteConcern(WriteConcern.MAJORITY);
You can build MongoClientOptions
, MongoDatabase
, or MongoCollection
to include a combination of write concern, read concern, and read preference.
For example, the following sets all three at the collection level:
collection = database.getCollection("restaurants")
.withReadPreference(ReadPreference.primary())
.withReadConcern(ReadConcern.MAJORITY)
.withWriteConcern(WriteConcern.MAJORITY);