> 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

# Insert Documents

## Overview

In this guide, you can learn how to use the Ruby driver to add documents to a MongoDB collection by performing **insert operations**.

An insert operation inserts one or more documents into a MongoDB collection. You can perform an insert operation by using the following methods:

- `insert_one` to insert a single document

- `insert_many` to insert one or more documents

### 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.

## The \_id Field

In a MongoDB collection, each document *must* contain an `_id` field with a unique field value.

MongoDB allows you to manage this field in two ways:

- Set the `_id` field for each document yourself, ensuring each value is unique.

- Let the driver automatically generate unique `BSON::ObjectId` values for each document `_id` field.

Unless you can guarantee uniqueness, we recommend letting the driver automatically generate `_id` values.

**Note:**

Duplicate `_id` values violate unique index constraints, which causes the driver to return an error.

To learn more about the `_id` field, see the [Unique Indexes](https://www.mongodb.com/docs/manual/core/index-unique/) guide in the MongoDB Server manual.

To learn more about document structure and rules, see the [Documents](https://www.mongodb.com/docs/manual/core/document/) guide in the MongoDB Server manual.

## Insert One Document

To add a single document to a MongoDB collection, call the `insert_one` method and pass the document you want to insert.

The following example inserts a document into the `restaurants` collection:

```ruby
document = { name: 'Neighborhood Bar & Grill', borough: 'Queens' }
collection.insert_one(document)
```

## Insert Multiple Documents

To add multiple documents to a MongoDB collection, call the `insert_many` method and pass a list of documents you want to insert.

The following example inserts two documents into the `restaurants` collection:

```ruby
documents = [
  { name: 'Metropolitan Cafe', borough: 'Queens' },
  { name: 'Yankee Bistro', borough: 'Bronx' }
]
collection.insert_many(documents)
```

## Modify Insert Behavior

You can pass a `Hash` object as a parameter to the `insert_one` method to set options to configure the insert operation. If you don't specify any options, the driver performs the insert operation with default settings.

The following table describes the options you can set to configure the `insert_one` operation:

| Option | Description |
| --- | --- |
| `bypass_document_validation` | Instructs the driver whether to ignore document-level validation. For more information, see [Schema Validation](https://www.mongodb.com/docs/manual/core/schema-validation/) in the MongoDB Server manual.Defaults to `false`. |
| `comment` | Sets a comment to attach to the operation. For more information, see the [insert command fields](https://www.mongodb.com/docs/manual/reference/command/insert/#command-fields) guide in the MongoDB Server manual. |
| `session` | Sets the session to use for the operation. To learn more about sessions, see [Client Sessions and Causal Consistency Guarantees](https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency/#std-label-sessions) in the MongoDB Server manual. |
| `write_concern` | Sets the write concern for the operation. For more information, see the [Write Concern](https://www.mongodb.com/docs/manual/core/write-concern/) guide in the MongoDB Server manual. |

You can set the preceding settings on the `insert_many` method by passing a `Hash` as a parameter to the method call. You can also use the `ordered` option to specify the order in which the driver inserts documents into MongoDB.

### Example

The following code uses the `insert_many` method to insert three new documents into a collection. Because the `bypass_document_validation` option is enabled, this insert operation bypasses document-level validation.

```ruby
documents = [
  { name: 'Cloudy Day', borough: 'Brooklyn' },
  { name: 'Squall or Shine', borough: 'Staten Island' }
  { name: 'Rose Field', borough: 'Queens' }
]
options = { bypass_document_validation: true }
collection.insert_many(documents, options)
```

## API Documentation

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

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

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