Insert Documents

On this page

Overview

Sample Data
Insert One Document
Insert Multiple Documents
Modify Insert Behavior
Example
Additional Information
API Documentation

Overview

In this guide, you can learn how to use PyMongo 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 insert_one() or insert_many() method.

Note

_id Field Must Be Unique

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

If you specify a value for the _id field, you must ensure that the value is unique across the collection. If you don't specify a value, the driver automatically generates a unique ObjectId value for the field.

We recommend letting the driver automatically generate _id values to ensure uniqueness. Duplicate _id values violate unique index constraints, which causes the driver to return an error.

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 PyMongo tutorial.

Insert One Document

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

The following example inserts a document into the restaurants collection:

sample_restaurants.restaurants.insert_one({"name" : "Mongo's Burgers"})

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

The following example inserts a list of documents into the restaurants collection:

document_list = [
   { "name" : "Mongo's Burgers" },
   { "name" : "Mongo's Pizza" }
]
sample_restaurants.restaurants.insert_many(document_list)

Modify Insert Behavior

The insert_one() method optionally accepts additional parameters which represent options you can use to configure the insert operation. If you don't specify any additional parameters, the driver does not customize the insert.

Property	Description
`bypass_document_validation`	If set to `True`, allows the write to opt out of document-level validation. Defaults to `False`.
`session`	An instance of `ClientSession`.
`comment`	A comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual for more information.

The insert_many() method accepts the preceding optional parameters, as well as the optional ordered property:

Property	Description
`ordered`	If set to `True`, the driver sends documents to the server in the order provided. If an error occurs, the driver and server cancel all remaining insert operations. Defaults to `True`.

Example

The following code uses the insert_many() method to insert three new documents into a collection. Because the second method argument is bypass_document_validation = True, this insert operation bypasses document-level validation.

document_list = [
    { "name" : "Mongo's Burgers" },
    { "name" : "Mongo's Pizza" },
    { "name" : "Mongo's Tacos" }
 ]
 sample_restaurants.restaurants.insert_many(document_list, bypass_document_validation = True)

Additional Information

For runnable code examples of inserting documents with PyMongo, 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:

Back

Write Data

Update