Delete Documents

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. To learn more, see the Collation section of this page.
`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.

Collation

To specify a collation for your operation, pass an $options array parameter that sets the collation option to the operation method. Assign the collation option to an array that configures the collation rules.

The following table describes the fields you can set to configure the collation:

Field	Description
`locale`	(Required) Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server manual. Data Type: `string`
`caseLevel`	(Optional) Specifies whether to include case comparison. When set to `true`, the comparison behavior depends on the value of the `strength` field: - If `strength` is `1`, the PHP library compares base characters and case. - If `strength` is `2`, the PHP library compares base characters, diacritics, other secondary differences, and case. - If `strength` is any other value, this field is ignored. When set to `false`, the PHP library doesn't include case comparison at strength level `1` or `2`. Data Type: `bool` Default: `false`
`caseFirst`	(Optional) Specifies the sort order of case differences during tertiary level comparisons. Data Type: `string` Default: `"off"`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: `int` Default: `3`
`numericOrdering`	(Optional) Specifies whether the driver compares numeric strings as numbers. If set to `true`, the PHP library compares numeric strings as numbers. For example, when comparing the strings "10" and "2", the library uses the strings' numeric values and treats "10" as greater than "2". If set to `false`, the PHP library compares numeric strings as strings. For example, when comparing the strings "10" and "2", the library compares one character at a time and treats "10" as less than "2". For more information, see Collation Restrictions in the MongoDB Server manual. Data Type: `bool` Default: `false`
`alternate`	(Optional) Specifies whether the library considers whitespace and punctuation as base characters for comparison purposes. Data Type: `string` Default: `"non-ignorable"`
`maxVariable`	(Optional) Specifies which characters the library considers ignorable when the `alternate` field is set to `"shifted"`. Data Type: `string` Default: `"punct"`
`backwards`	(Optional) Specifies whether strings containing diacritics sort from the back of the string to the front. Data Type: `bool` Default: `false`

To learn more about collation and the possible values for each field, see the Collation entry 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

Replace Documents

Bulk Write Operations