Bulk Write Operations

Sample Data

The examples in this section use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your Scala application, create a MongoClient that connects to an Atlas cluster and assign the following values to your database and collection variables:

val database: MongoDatabase = mongoClient.getDatabase("sample_restaurants")
val collection: MongoCollection[Document] = database.getCollection("restaurants")

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Insert Operations

To perform an insert operation, create an InsertOneModel instance and specify the document you want to insert.

The following example creates an instance of InsertOneModel:

val insertOneModel = InsertOneModel(
    Document("name" -> "Blue Moon Grill",
             "borough" -> "Brooklyn",
             "cuisine" -> "American")
)

To insert multiple documents, create an instance of InsertOneModel for each document.

Update Operations

To update a document, create an instance of UpdateOneModel and pass the following arguments:

• Query filter that specifies the criteria used to match documents in your collection.

• Update operation that you want to perform. To learn more about update operations, see the Field Update Operators guide in the MongoDB Server manual.

The following example creates an instance of UpdateOneModel:

val updateOneFilter = equal("name", "White Horse Tavern")
val updateOneDoc = set("borough", "Queens")
val updateOneModel = UpdateOneModel(updateOneFilter, updateOneDoc)

If multiple documents match the query filter specified in the UpdateOneModel instance, the operation updates the first result. You can specify a sort in an UpdateOptions instance to apply an order to matched documents before the driver performs the update operation, as shown in the following code:

val options = UpdateOptions.sort(ascending("name"))

To update multiple documents, create an instance of UpdateManyModel and pass the same arguments as for UpdateOneModel. The UpdateManyModel class specifies updates for all documents that match your query filter.

The following example creates an instance of UpdateManyModel:

val updateManyFilter = equal("name", "Wendy's")
val updateManyDoc = set("cuisine", "Fast food")
val updateManyModel = UpdateManyModel(updateManyFilter, updateManyDoc)

Replace Operations

A replace operation removes all fields and values of a specified document and replaces them with new fields and values that you specify. To perform a replace operation, create an instance of ReplaceOneModel and pass the following arguments:

• Query filter that specifies the criteria used to match documents in your collection

• Replacement document that specifies the new fields and values to insert

The following example creates an instance of ReplaceOneModel:

val replaceFilter = equal("name", "Cooper Town Diner")
val replaceDoc = Document("name" -> "Smith Town Diner",
                          "borough" -> "Brooklyn",
                          "cuisine" -> "American")
val replaceOneModel = ReplaceOneModel(replaceFilter, replaceDoc)

If multiple documents match the query filter specified in the ReplaceOneModel instance, the operation replaces the first result. You can specify a sort in a ReplaceOptions instance to apply an order to matched documents before the driver performs the replace operation, as shown in the following code:

val options = ReplaceOptions.sort(ascending("name"))

Delete Operations

To delete a document, create an instance of DeleteOneModel and pass a query filter specifying the document you want to delete. A DeleteOneModel instance provides instructions to delete only the first document that matches your query filter.

The following example creates an instance of DeleteOneModel:

val deleteOneModel = DeleteOneModel(equal("name", "Morris Park Bake Shop"))

To delete multiple documents, create an instance of DeleteManyModel and pass a query filter specifying the document you want to delete. An instance of DeleteManyModel provides instructions to remove all documents that match your query filter.

The following example creates an instance of DeleteManyModel:

val deleteManyModel = DeleteManyModel(equal("cuisine", "Experimental"))

Perform the Bulk Operation

After you define a model instance for each operation that you want to perform, pass a Seq instance containing the models to the MongoCollection.bulkWrite() method. By default, the method runs the operations in the order specified by the list of models.

The following example performs multiple write operations by using the bulkWrite() method:

val insertOneModel = InsertOneModel(
    Document("name" -> "Red's Pizza",
             "borough" -> "Brooklyn",
             "cuisine" -> "Pizzeria")
)
val updateOneModel = UpdateOneModel(equal("name", "Moonlit Tavern"), set("borough", "Queens"))
val deleteManyModel = DeleteManyModel(equal("name", "Crepe"))
val writes = Seq(insertOneModel, updateOneModel, deleteManyModel)
val observable = collection.bulkWrite(writes)
observable.subscribe(
  (result: BulkWriteResult) => println(s"Success: $result"),
  (error: Throwable) => println(s"Error: ${error.getMessage}"),
  () => println("Completed")
)

Success: AcknowledgedBulkWriteResult{insertedCount=1, matchedCount=1, removedCount=1,
modifiedCount=1, upserts=[], inserts=[BulkWriteInsert{index=0, id=BsonObjectId{value=...}}]}
Completed

If any of the write operations fail, the Scala driver raises a BulkWriteError and does not perform any further operations. BulkWriteError provides a details item that includes the operation that failed and details about the exception.

Customize Bulk Write

The MongoCollection.bulkWrite() method optionally accepts a BulkWriteOptions parameter, which specifies options that you can use to configure the bulk write operation. If you don't specify any options, the driver performs the bulk operation with default settings. To modify the behavior of the write operation, pass the class instance as the last argument to the bulkWrite() method.

The following table describes the setter methods that you can use to configure a BulkWriteOptions instance:

The following code creates options and sets the ordered option to false to specify an unordered bulk write. Then, the example uses the bulkWrite() method to perform a bulk operation:

val options = BulkWriteOptions().ordered(false)
val observable = collection.bulkWrite(writes, options)

If any of the write operations in an unordered bulk write fail, the Scala driver reports the errors only after attempting all operations.

Return Value

The bulkWrite() method returns a SingleObservable object that contains a BulkWriteResult. You can access information from the BulkWriteResult instance by subscribing to the observable and using the following methods:

Insert Operations

This example shows how to create models that contain instructions to insert two documents. One document is inserted into the db.people collection, and the other document is inserted into the db.things collection. The MongoNamespace instance defines the target database and collection that each write operation applies to.

val personToInsert = ClientNamespacedWriteModel.insertOne(
  MongoNamespace("db", "people"),
  Document("name" -> "Julia Smith")
)
val thingToInsert = ClientNamespacedWriteModel.insertOne(
  MongoNamespace("db", "things"),
  Document("object" -> "washing machine")
);

Update Operations

The following example shows how to use the bulkWrite() method to update existing documents in the db.people and db.things collections:

val personUpdate = ClientNamespacedWriteModel.updateOne(
  MongoNamespace("db", "people"),
  equal("name", "Freya Polk"),
  inc("age", 1)
)
val thingUpdate = ClientNamespacedWriteModel.updateMany(
  MongoNamespace("db", "things"),
  equal("category", "electronic"),
  set("manufacturer", "Premium Technologies")
)

This example increments the value of the age field by 1 in the document that has a name value of "Freya Polk" in the people collection. It also sets the value of the manufacturer field to "Premium Technologies" in all documents that have a category value of "electronic" in the things collection.

If multiple documents match the query filter specified in a ClientNamespacedUpdateOneModel instance, the operation updates the first result. You can specify a sort order in a ClientUpdateOneOptions instance to apply an order to matched documents before the driver performs the update operation, as shown in the following code:

val options = ClientUpdateOneOptions
  .clientUpdateOneOptions()
  .sort(ascending("_id"))

Replace Operations

The following example shows how to create models to replace existing documents in the db.people and db.things collections:

val personReplacement = ClientNamespacedWriteModel.replaceOne(
  MongoNamespace("db", "people"),
  equal("_id", 1),
  Document("name" -> "Frederic Hilbert")
)
val thingReplacement = ClientNamespacedWriteModel.replaceOne(
  MongoNamespace("db", "things"),
  equal("_id", 1),
  Document("object" -> "potato")
)

The preceding code example replaces the following documents with new documents:

• Document in the people collection that has an _id value of 1

• Document in the things collection that has an _id value of 1

If multiple documents match the query filter specified in a ClientNamespacedReplaceOneModel instance, the operation replaces the first result. You can specify a sort order in a ClientReplaceOneOptions instance to apply an order to matched documents before the driver performs the replace operation, as shown in the following code:

val options = ClientReplaceOneOptions
  .clientReplaceOneOptions()
  .sort(ascending("_id"))

Perform the Bulk Operation

After you define a ClientNamespacedWriteModel instance for each operation that you want to perform, pass a list of these instances to the client bulkWrite() method. By default, the method runs the operations in the order that you specify them.

The following example performs multiple write operations by using the bulkWrite() method:

val peopleNamespace = MongoNamespace("db", "people")
val thingsNamespace = MongoNamespace("db", "things")
val writeModels = List(
  ClientNamespacedWriteModel.insertOne(
    peopleNamespace,
    Document("name" -> "Corey Kopper")
  ),
  ClientNamespacedWriteModel.replaceOne(
    thingsNamespace,
    equal("_id", 1),
    Document("object" -> "potato")
  )
)
val observable = mongoClient.bulkWrite(writeModels)
observable.subscribe(
  (result: ClientBulkWriteResult) => println(result.toString),
  (error: Throwable) => println(s"Error: ${error.getMessage}"),
  () => println("Completed")
)

AcknowledgedSummaryClientBulkWriteResult{insertedCount=1, matchedCount=1, ...}

If any of the write operations fail, the driver raises a ClientBulkWriteException and does not perform any further individual operations. ClientBulkWriteException includes a BulkWriteError that can be accessed by using the ClientBulkWriteException.getWriteErrors() method, which provides information about the failure.

Customize Bulk Write

You can pass an instance of ClientBulkWriteOptions to the bulkWrite() method to customize how the driver performs the bulk write operation.

val namespace = MongoNamespace("db", "people")
val options = ClientBulkWriteOptions.clientBulkWriteOptions().ordered(false)
val writeModels = List(
  ClientNamespacedWriteModel.insertOne(namespace, Document("_id" -> 1, "name" -> "Rudra Suraj")),
  // Causes a duplicate key error
  ClientNamespacedWriteModel.insertOne(namespace, Document("_id" -> 1, "name" -> "Mario Bianchi")),
  ClientNamespacedWriteModel.insertOne(namespace, Document("name" -> "Wendy Zhang"))
)
val observable = mongoClient.bulkWrite(writeModels, options)

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

• Collection Bulk Write

  • bulkWrite()

  • InsertOneModel

  • UpdateOneModel

  • UpdateManyModel

  • ReplaceOneModel

  • DeleteOneModel

  • DeleteManyModel

  • BulkWriteOptions

  • BulkWriteResult

• Client Bulk Write

  • bulkWrite()

  • ClientNamespacedWriteModel

  • MongoNamespace

  • ClientBulkWriteOptions

  • ClientBulkWriteResult