> This page location: /docs.md > /docs/drivers.md > /docs/languages/ruby.md > /docs/ruby-driver/current.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Update Documents

## Overview

In this guide, you can learn how to use the Ruby driver to update documents in a MongoDB collection by using the `update_one` and `update_many` methods.

### Sample Data

The examples in this guide use the `restaurants` collection in the `sample_restaurants` database from the [Atlas sample datasets](https://www.mongodb.com/docs/atlas/sample-data/). 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:

```ruby
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 [MongoDB Get Started](https://www.mongodb.com/docs/get-started/?language=ruby) guide.

## Update Operations

You can update documents in MongoDB by using the following methods:

- `update_one`: Updates *the first document* that matches the search criteria

- `update_many`: Updates *all documents* that match the search criteria

Each update method requires the following parameters:

- **Query filter**, which matches the documents you want to update. To learn more about query filters, see the [Specify a Query](https://www.mongodb.com/docs/ruby-driver/current/crud/query/specify-a-query.md#std-label-ruby-specify-query) guide.

- **Update document**, which specifies the update operator and the fields and values to be updated. The update operator specifies the type of update to perform. To view a list of update operators and learn about their usages, see the [Field Update Operators guide page](https://www.mongodb.com/docs/manual/reference/operator/update-field/) in the MongoDB Server manual.

### Update One Document Example

The following example uses the `update_one` method to find the first document where the value of the `name` field is `"Happy Garden"`. It then uses the `$set` operator to update the `name` field value to `"Mountain House"`.

```ruby
filter = { name: 'Happy Garden' }

update = { '$set' => { name: 'Mountain House' } }

single_result = collection.update_one(filter, update)

puts "#{single_result.modified_count} document(s) updated."
```

**Output:**

```console
1 document(s) updated
```

### Update Many Documents Example

The following example uses the `update_many` method to update all documents where the value of the `name` field is `"Starbucks"`. The update document uses the `$rename` operator to change the name of the `address` field to `location`.

```ruby
filter = { name: 'Starbucks' }

update = { '$rename' => { address: 'location' } }

many_result = collection.update_many(filter, update)

puts "#{many_result.modified_count} document(s) updated."
```

**Output:**

```console
11 document(s) updated
```

### Upsert Option

The `upsert` parameter allows you to use the `update_one()` and `update_many()` operations to perform a conditional operation:

- If the specified document exists, the command updates it.

- If the specified document does not exist, the command creates a new document with the specified parameter.

For more information, see the [Modify Update Example](https://www.mongodb.com/docs/ruby-driver/current/crud/update.md#std-label-ruby-upsert-example) section or the [options table](https://www.mongodb.com/docs/ruby-driver/current/crud/update.md#std-label-ruby-update-options-table) on this page.

### Customize the Update Operation

The `update_one` and `update_many` methods accept options to configure the update operation. You can pass these options individually as parameters, or you can create a `Hash` object that contains the options and pass the object as a parameter. If you don't specify any options, the driver performs the update operation with default settings.

The following table describes the options that you can use to configure the update operation:

| Option | Description |
| --- | --- |
| `upsert` | Whether the update operation performs an upsert operation if no documents match the query filter. For more information, see the [upsert statement](https://www.mongodb.com/docs/manual/reference/command/update/#std-label-update-command-upsert) in the MongoDB Server manual.Default: `false` |
| `bypass_document_validation` | 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](https://www.mongodb.com/docs/manual/core/schema-validation/#schema-validation) in the MongoDB Server manual.Default: `false` |
| `collation` | Language collation to use when sorting results. For more information, see [Collation](https://www.mongodb.com/docs/manual/reference/collation/#std-label-collation) in the MongoDB Server manual. |
| `array_filters` | List of filters that you specify to select which array elements the update applies to. |
| `hint` | Index to use when matching documents. For more information, see the [hint statement](https://www.mongodb.com/docs/manual/reference/command/update/#std-label-update-command-hint) in the MongoDB Server manual. |
| `let` | 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. For more information, see the [let statement](https://www.mongodb.com/docs/manual/reference/command/update/#std-label-update-let-syntax) in the MongoDB Server manual. |

#### Modify Update Example

The example uses the `$equal` operator to match documents where the value of the `name` field is `"Sunrise Pizzeria"`. It then uses the `$set` operator to set the `borough` field value in the first matching document to `"Queens"` and the `cuisine` field value to `"Italian"`.

Because the `upsert` option is set to `true`, if the query filter doesn't match any existing documents, the driver inserts a new document that contains the fields and values in the filter and update documents.

```ruby
filter = { 'name' => 'Sunrise Pizzeria' }

update = { '$set' => { borough: 'Queens', cuisine: 'Italian' } }

upsert_result = collection.update_one(filter, update, upsert: true)

puts "#{upsert_result.modified_count} document(s) updated."
```

**Output:**

```console
1 document(s) updated
```

### Return Value

The `update_one` and `update_many` methods each return a `Result` object. You can access the following methods from a `Result` instance:

| Method | Description |
| --- | --- |
| `matched_count` | Number of documents that matched the query filter, regardless of how many updates were performed. |
| `modified_count` | Number of documents modified by the update operation. If an updated document is identical to the original, it is not included in this count. |
| `acknowledged?` | Returns `true` if the server acknowledged the result. |
| `upserted_count` | Returns the number of documents that were upserted in the database, if the driver performed an upsert. |
| `upserted_ids` | Returns the `_id` value of the document that was upserted in the database, if the driver performed an upsert. |

**Tip:**

Check the value of the `acknowledged?` method before you try to call any other `Result` methods. If the `acknowledged?` method returns `false`, the driver throws an `InvalidOperation` exception if you try to call any other method on the `Result` object. The driver cannot determine these values if the server does not acknowledge the write operation.

## Additional Information

To view runnable code examples that demonstrate how to update documents by using the Ruby driver, see [Insert Documents.](https://www.mongodb.com/docs/ruby-driver/current/crud/insert.md#std-label-ruby-write)

### API Documentation

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

- [update\_one](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection.html#update_one-instance_method)

- [update\_many](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection.html#update_many-instance_method)

- [Result](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Operation/Update/Result.html)
