Docs Menu

Compound Operations

On this page

  • Overview
  • Find and Delete
  • Find and Update
  • Find and Replace
  • Additional Information

In this guide, you can learn how to perform compound operations.

Compound operations combine a read and write operation into a single operation. If you perform a read and write operation separately, there's a chance someone else may alter the document between both operations. MongoDB prevents this by placing a write lock on the document you are modifying for the duration of your compound operation.

MongoDB supports the following compound operations:

Tip

If you need to read and write to more than one document, use transactions.

Run the following snippet to load the documents into the ratings collection of the tea database:

coll := client.Database("tea").Collection("ratings")
docs := []interface{}{
bson.D{{"type", "Masala"}, {"rating", 10}},
bson.D{{"type", "Assam"}, {"rating", 5}},
bson.D{{"type", "Oolong"}, {"rating", 7}},
bson.D{{"type", "Earl Grey"}, {"rating", 8}},
bson.D{{"type", "English Breakfast"}, {"rating", 5}},
}
result, err := coll.InsertMany(context.TODO(), docs)
if err != nil {
panic(err)
}
fmt.Printf("Number of documents inserted: %d\n", len(result.InsertedIDs))
Tip
Non-existent Databases and Collections

The server implicitly creates the necessary database and collection when you perform a write operation against them if they don't already exist.

Each document contains a rating for a type of tea that corresponds to the type and rating fields.

Note

Each example truncates the ObjectID value because the driver generates them uniquely.

The FindOneAndDelete() function finds the first document that matches the specified query filter and deletes it. The function returns a SingleResult containing the deleted document.

Note

This function differs from the DeleteOne() function. FindOneAndDelete() performs a find and delete as a single operation, and eliminates the possibility of someone altering a document between both operations.

You can modify the behavior of the FindOneAndDelete() function by passing in a FineOneAndDeleteOptions. If you don't specify a FineOneAndDeleteOptions, the driver uses the default values for each option.

The FineOneAndDeleteOptions type allows you to configure options with the following functions:

Function
Description
SetCollation()
The type of language collation to use when sorting results.
Default: nil
SetMaxTime()
The maximum amount of time that the query can run on the server.
Default: nil
SetProjection()
The fields to include in the document returned.
Default: nil
SetSort()
The sort fields and directions to order the documents matched.
Default: nil
SetHint()
The index to use to scan for documents.
Default: nil

The following example matches and deletes a document where the type is "Assam" with the FindOneAndDelete() function:

filter := bson.D{{"type", "Assam"}}
var deletedDoc bson.D
err := coll.FindOneAndDelete(context.TODO(), filter).Decode(&deletedDoc)
if err != nil {
panic(err)
}
fmt.Println(deletedDoc)

After running this example, the output resembles the following:

[{_id ObjectID("...")} {type Assam} {rating 5}]

The FindOneAndUpdate() function finds the first document that matches the specified query filter and updates it according to the update document. The function returns a SingleResult containing the matched document.

Note

This function differs from the UpdateOne() function. FindOneAndUpdate() performs a find and update as a single operation, and eliminates the possibility of someone altering a document between both operations.

You can modify the behavior of the FindOneAndUpdate() function by passing in a FineOneAndUpdateOptions. If you don't specify a FineOneAndUpdateOptions, the driver uses the default values for each option.

The FineOneAndUpdateOptions type allows you to configure options with the following functions:

Function
Description
SetArrayFilters()
The array elements the update applies to.
Default: nil
SetBypassDocumentValidation()
Whether to allow the write operation to opt-out of document level validation.
Default: false
SetCollation()
The type of language collation to use when sorting results.
Default: nil
SetMaxTime()
The maximum amount of time that the query can run on the server.
Default: nil
SetProjection()
The fields to include in the document returned.
Default: nil
SetReturnDocument()
Whether to return the original or updated document in the SingleResult.
Default: options.Before
SetSort()
The sort fields and directions to order the documents matched.
Default: nil
SetUpsert()
Whether to insert a new document if the query filter doesn't match any documents.
Default: false
SetHint()
The index to use to scan for documents.
Default: nil

The following example performs the following actions in order with the FindOneAndUpdate() function:

  • Matches a document where the type is "Oolong"
  • Updates the matched document's rating to 9
  • Returns the updated document
filter := bson.D{{"type", "Oolong"}}
update := bson.D{{"$set", bson.D{{"rating", 9}}}}
opts := options.FindOneAndUpdate().SetReturnDocument(options.After)
var updatedDoc bson.D
err := coll.FindOneAndUpdate(context.TODO(), filter, update, opts).Decode(&updatedDoc)
if err != nil {
panic(err)
}
fmt.Println(updatedDoc)

After running this example, the output resembles the following:

[{_id ObjectID("...")} {type Oolong} {rating 9}]

The FindOneAndReplace() function finds the first document that matches the specified query filter and replaces it with the replacement document. The function returns a SingleResult containing the matched document.

Note

This function differs from the ReplaceOne() function. FindOneAndReplace() performs a find and replace as a single operation, and eliminates the possibility of someone altering a document between both operations.

You can modify the behavior of the FindOneAndReplace() function by passing in a FineOneAndReplaceOptions. If you don't specify a FineOneAndReplaceOptions, the driver uses the default values for each option.

The FineOneAndReplaceOptions type allows you to configure options with the following functions:

Function
Description
SetBypassDocumentValidation()
Whether to allow the write operation to opt-out of document level validation.
Default: false
SetCollation()
The type of language collation to use when sorting results.
Default: nil
SetMaxTime()
The maximum amount of time that the query can run on the server.
Default: nil
SetProjection()
The fields to include in the document returned.
Default: nil
SetReturnDocument()
Whether to return the original or replaced document in the SingleResult.
Default: nil
SetSort()
The sort fields and directions to order the documents matched.
Default: nil
SetUpsert()
Whether to insert a new document if the query filter doesn't match any documents.
Default: false
SetHint()
The index to use to scan for documents.
Default: nil

The following example performs the following actions in order with the FindOneAndReplace() function:

  • Matches a document where the type is "English Breakfast"
  • Replaces the matched document with a new document where the type is "Ceylon" and rating is 6
filter := bson.D{{"type", "English Breakfast"}}
replacement := bson.D{{"type", "Ceylon"}, {"rating", 6}}
var previousDoc bson.D
err := coll.FindOneAndReplace(context.TODO(), filter, replacement).Decode(&previousDoc)
if err != nil {
panic(err)
}
fmt.Println(previousDoc)

After running this example, the output resembles the following:

[{_id ObjectID("...")} {type English Breakfast} {rating 5}]

For more information on performing the operations mentioned, see the following guides:

For more information on any of the functions or types discussed in this guide, see the following API Documentation:

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.