Docs Home → Develop Applications → Python Drivers → PyMongo
Insert Documents
On this page
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.
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.
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:
You can set this field for each document yourself, ensuring each
_id
field value is unique.You can let the driver automatically generate unique
ObjectId
values for each document_id
. If you do not manually set an_id
value for a document, the driver populates the field with anObjectId
.
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 a WriteError
from
insert_one()
or a BulkWriteError
from insert_many()
.
To learn more about the _id
field, see the
Unique Indexes guide in the MongoDB Server manual.
To learn more about document structure and rules, see the Documents 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 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 InsertMany()
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: