Replace Documents
On this page
Overview
In this guide, you can learn how to use the Kotlin Sync driver to perform a replace
operation on a document in a MongoDB collection. A replace operation
removes all fields and values from a specified document except the
_id
field, and adds new fields and values that you specify. This
operations differs from an update operation, which changes only
specified fields in one or more documents.
To learn more about update operations, see the Update Documents guide.
Sample Data
The examples in this guide use the sample_restaurants.restaurants
collection
from the Atlas sample datasets. To learn how to create a
free MongoDB Atlas cluster and load the sample datasets, see the
Get Started with Atlas guide.
The documents in this collection are modeled by the following Kotlin data class:
data class Restaurant( val name: String, val borough: String, val cuisine: String, val owner: String?, )
Replace Operation
You can perform a replace operation in MongoDB by using the
replaceOne()
method. This method removes all fields except the
_id
field from the first document that matches the query filter. It
then adds the fields and values you specify to the empty document.
Required Parameters
You must pass the following parameters to the replaceOne()
method:
Query filter, which matches which documents to update. To learn more about query filters, see the Specify a Query guide.
Replacement document, which specifies the fields and values that you want to replace the existing fields and values with.
Replace One Document
The following example uses the replaceOne()
method to replace the
fields and values of a document in which the value of the name
field
value is "Primola Restaurant"
:
val filter = Filters.eq(Restaurant::name.name, "Primola Restaurant") val replacement = Restaurant( "Frutti Di Mare", "Queens", "Seafood", owner = "Sal Thomas" ) val result = collection.replaceOne(filter, replacement)
Important
The values of _id
fields are immutable. If your replacement
document specifies a value for the _id
field, it must be the same
as the _id
value of the existing document or the driver raises a
WriteError
.
Customize the Replace Operation
The replaceOne()
method optionally accepts
a parameter that sets options to configure the replace operation.
If you don't specify any options, the driver performs the replace
operation with default settings.
The following table describes the setter methods that you can use to
configure an ReplaceOptions
instance:
Property | Description |
---|---|
upsert() | Specifies whether the replace operation performs an upsert operation if no
documents match the query filter. For more information, see upsert
behavior
in the MongoDB Server manual. Defaults to false |
bypassDocumentValidation() | Specifies whether the update operation bypasses document validation. This lets you
update documents that don't meet the schema validation requirements, if any
exist. For more information about schema validation, see Schema
Validation in the MongoDB
Server manual. Defaults to false . |
collation() | Specifies the kind of language collation to use when sorting
results. For more information, see Collation
in the MongoDB Server manual. |
hint() | Sets the index to use when matching documents.
For more information, see the hint statement
in the MongoDB Server manual. |
let() | Provides a map of parameter names and values to set top-level
variables for the operation. Values must be constant or closed
expressions that don't reference document fields. |
comment() | Sets a comment to attach to the operation. |
The following code sets the upsert
option to true
, which instructs the
driver to insert a new document that has the fields and values specified
in the replacement document if the query filter doesn't match any
existing documents:
val opts = ReplaceOptions().upsert(true) val result = collection.replaceOne(filter, replacement, opts)
Return Value
The replaceOne()
method returns an UpdateResult
object. You can use the following methods to access information from
an UpdateResult
instance:
Property | Description |
---|---|
getMatchedCount() | Returns the number of documents that matched the query filter, regardless of
how many updates were performed. |
getModifiedCount() | Returns the number of documents modified by the update operation. If an updated
document is identical to the original, it is not included in this
count. |
wasAcknowledged() | Returns true if the server acknowledged the result. |
getUpsertedId() | Returns the _id value of the document that was upserted
in the database, if the driver performed an upsert. |
Additional Information
To view a runnable code example that demonstrates how to replace a document, see Write Data to MongoDB.
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API documentation: