Insert Documents

On this page

Overview

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

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 document
MongoDB\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:

Back

Update

Delete