Insert Documents
On this page
Overview
In this guide, you can learn how to use the MongoDB PHP Library 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:
MongoDB\Collection::insertOne()
method to insert a single documentMongoDB\Collection::insertMany()
method 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. To access this collection
from your PHP application, instantiate a MongoDB\Client
that connects to an Atlas cluster
and assign the following value to your $collection
variable:
$collection = $client->sample_restaurants->restaurants;
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas 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
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 a MongoDB\Driver\Exception\BulkWriteException
error.
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 MongoDB\Collection::insertOne()
method and pass the document you want to add.
The following example inserts a document into the restaurants
collection:
$result = $collection->insertOne(['name' => 'Mongo\'s Burgers']);
Insert Multiple Documents
To add multiple documents to a MongoDB collection, call the MongoDB\Collection::insertMany()
method and pass an array that contains the list of documents you want to add.
The following example inserts two documents into the restaurants
collection:
$restaurants = [ ['name' => 'Mongo\'s Burgers'], ['name' => 'Mongo\'s Pizza'] ]; $result = $collection->insertMany($restaurants);
Modify Insert Behavior
You can modify the behavior of the MongoDB\Collection::insertOne()
and
MongoDB\Collection::insertMany()
methods by passing an array that specifies
option values as a parameter. The following table describes some options
you can set in the array:
Field | Description |
---|---|
bypassDocumentValidation | If set to true , allows the write operation to opt out of
document-level validation.Defaults to false .Type: bool |
writeConcern | Sets the write concern for the operation. Defaults to the write concern of the namespace. Type: MongoDB\Driver\WriteConcern |
ordered | If set to true , the operation stops inserting documents when one insert
fails. If false , the operation continues to insert the remaining documents
when one insert fails. You cannot pass this option to the insertOne() method.Defaults to true .Type: bool |
comment | A comment to attach to the operation. For more information, see the insert command
fields guide in the
MongoDB Server manual. Type: any valid BSON type |
Example
The following code uses the insertMany()
method to insert three new
documents into a collection. Because the bypassDocumentValidation
field
is set to true
in an options array, this
insert operation bypasses document-level validation:
$docs = [ ['name' => 'Mongo\'s Burgers'], ['name' => 'Mongo\'s Pizza'], ['name' => 'Mongo\'s Tacos'] ]; $result = $collection->insertMany($docs, ['bypassDocumentValidation' => true]);
Additional Information
To view runnable code examples of inserting documents with the MongoDB PHP Library, 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: