In this guide, you can learn how to use the Ruby 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 operation 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.
The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your Ruby application, create a Mongo::Client object that connects to an Atlas cluster and assign the following values to your database and collection variables:
database = client.use('sample_restaurants')collection = database[:restaurants]To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.
You can perform a replace operation in MongoDB by using the replace_one method. This method removes all fields except the _id field from the first document that matches the specified query filter. It then adds the fields and values you specify to the empty document.
You must pass the following parameters to the replace_one method:
Query filter: Specifies which documents to update. To learn more about query filters, see the Specify a Query guide.
Replacement document: Specifies the fields and values that you want to replace the existing fields and values with.
The following example uses the replace_one method to replace the fields and values of a document in which the value of the name field is "Primola Restaurant":
filter = { name: 'Primola Restaurant' }new_document = { name: 'Frutti Di Mare', cuisine: 'Seafood', borough: 'Queens' }result = collection.replace_one(filter, new_document)puts "Replaced #{result.modified_count} document(s)"The value of the _id field is 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.
You can pass a Hash object as a parameter to the replace_one method to set 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 options that you can use to configure the replace operation:
Option
Description
upsert
Specifies whether the replace operation performs an upsert operation if no documents match the query filter. For more information, see
upsert behaviorin the MongoDB Server manual.
Defaults to false.
bypass_document_validation
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 Validationin the MongoDB Server manual.
Defaults to false.
collation
Specifies the kind of language collation to use when sorting results. For more information, see
Collationin the MongoDB Server manual.
session
Specifies the session to use for the operation. To learn more about sessions, see
Client Sessions and Causal Consistency Guaranteesin the MongoDB Server manual.
hint
Sets the index to use when matching documents. For more information, see the
hint statementin 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.
The following code performs the same replace operation as the preceding example, but sets the upsert option to true. This 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:
options = { upsert: true }result = collection.replace_one(filter, new_document, options)puts "Replaced #{result.upserted_count} document(s)"The replace_one method returns a Mongo::Operation::Update::Result object. You can use the following methods to access information from a Result instance:
Method
Description
matched_count
Returns the number of documents that matched the query filter.
modified_count
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.
upserted_count
Returns the number of documents upserted.
upserted_id
Returns the _id value of the document that the driver upserted into the database, if any.
To view a runnable code example that demonstrates how to replace a document, see Write Data to MongoDB.
To learn more about any of the methods or types discussed in this guide, see the following API documentation:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4