Delete Documents

On this page

Overview

Sample Data
Delete Operations
Delete One Document
Delete Multiple Documents
Modify the Delete Operation
Example
Return Value
Example
API Documentation

Overview

In this guide, you can learn how to use the MongoDB PHP Library to remove documents from a MongoDB collection by performing delete operations.

A delete operation removes one or more documents from a MongoDB collection. You can perform a delete operation by using the MongoDB\Collection::deleteOne() or MongoDB\Collection::deleteMany() methods.

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.

Delete Operations

You can perform delete operations by using the following methods:

MongoDB\Collection::deleteOne(), which deletes the first document that matches the search criteria
MongoDB\Collection::deleteMany(), which deletes all documents that match the search criteria

Each delete method requires a query filter document, which specifies the search criteria to determine which documents to select for removal. For more information about query filters, see the Query Filter Documents section in the MongoDB Server manual.

Delete One Document

The following example uses the deleteOne() method to remove a document in the restaurants collection that has a name value of 'Ready Penny Inn':

$collection->deleteOne(['name' => 'Ready Penny Inn']);

Delete Multiple Documents

The following example uses the deleteMany() method to remove all documents in the restaurants collection that have a borough value of 'Brooklyn':

$collection->deleteMany(['borough' => 'Brooklyn']);

Modify the Delete Operation

You can modify the behavior of the MongoDB\Collection::deleteOne() and MongoDB\Collection::deleteMany() methods by passing an array that specifies option values as a parameter. The following table describes the options you can set in the array:

Option	Description
`collation`	Specifies the kind of language collation to use when comparing strings. For more information, see Collation in the MongoDB Server manual.
`writeConcern`	Sets the write concern for the operation. This option defaults to the collection's write concern. For more information, see Write Concern in the MongoDB Server manual.
`hint`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`session`	Specifies the client session to associate with the operation. For more information, see Session in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the delete command fields guide in the MongoDB Server manual.

Example

The following example calls the deleteMany() method to delete all documents in the restaurants collection that have a name value containing the string 'Mongo'. It also sets the comment option in an array parameter to add a comment to the operation:

$collection->deleteMany(
    ['name' => new MongoDB\BSON\Regex('Mongo')],
    ['comment' => 'Deleting Mongo restaurants'],
);

Note

If you replace the deleteMany() method with deleteOne() in the preceding example, the library deletes only the first document that has a name value containing 'Mongo'.

Return Value

The MongoDB\Collection::deleteOne() and MongoDB\Collection::deleteMany() methods return a MongoDB\DeleteResult object. This class contains the following member functions:

isAcknowledged(), which returns a boolean indicating whether the operation was acknowledged.
getDeletedCount(), which returns the number of documents deleted. If the write operation was not acknowledged, this method throws an error.

If the query filter does not match any documents, the driver doesn't delete any documents and getDeletedCount() returns 0.

Example

The following example calls the deleteMany() method to delete documents that have a cuisine value of 'Greek'. It then calls the getDeletedCount() member function to print the number of deleted documents:

$result = $collection->deleteMany(['cuisine' => 'Greek']);
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Deleted documents: 111

API Documentation

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

Back

Insert

Replace