- Reference >
- Database Commands >
- Query and Write Operation Commands >
- delete
delete¶
On this page
Definition¶
-
delete
¶ New in version 2.6.
The
delete
command removes documents from a collection. A singledelete
command can contain multiple delete specifications. The command cannot operate on capped collections. The remove methods provided by the MongoDB drivers use this command internally.The
delete
command has the following syntax:The command takes the following fields:
Field Type Description delete
string The name of the target collection. deletes
array An array of one or more delete statements to perform in the named collection. ordered
boolean Optional. If true
, then when a delete statement fails, return without performing the remaining delete statements. Iffalse
, then when a delete statement fails, continue with the remaining delete statements, if any. Defaults totrue
.writeConcern
document Optional. A document expressing the write concern of the
delete
command. Omit to use the default write concern.Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
Each element of the
deletes
array contains the following fields:Field Type Description q
document The query that matches documents to delete. limit
integer The number of matching documents to delete. Specify either a 0
to delete all matching documents or1
to delete a single document.collation
document Optional.
Specifies the collation to use for the operation.
Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.
The collation option has the following syntax:
When specifying collation, the
locale
field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.If the collation is unspecified but the collection has a default collation (see
db.createCollection()
), the operation uses the collation specified for the collection.If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.
You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.
New in version 3.4.
Returns: A document that contains the status of the operation. See Output for details.
Behavior¶
Limits¶
The total size of all the queries (i.e. the q
field values) in the
deletes
array must be less than or equal to the maximum
BSON document size
.
The total number of delete documents in the deletes
array must be
less than or equal to the maximum bulk size
.
Transactions¶
delete supports multi-document transactions.
Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
Important
In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transaction should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions. For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.
Examples¶
Limit the Number of Documents Deleted¶
The following example deletes from the orders
collection one
document that has the status
equal to D
by specifying the
limit
of 1
:
The returned document shows that the command deleted 1
document.
See Output for details.
Delete All Documents That Match a Condition¶
The following example deletes from the orders
collection all
documents that have the status
equal to D
by specifying the
limit
of 0
:
The returned document shows that the command found and deleted 13
documents. See Output for details.
Delete All Documents from a Collection¶
Delete all documents in the orders
collection by specifying an
empty query condition and a limit
of 0
:
The returned document shows that the command found and deleted 35
documents in total. See Output for details.
Output¶
The returned document contains a subset of the following fields:
-
delete.
ok
¶ The status of the command.
-
delete.
n
¶ The number of documents deleted.
-
delete.
writeErrors
¶ An array of documents that contains information regarding any error encountered during the delete operation. The
writeErrors
array contains an error document for each delete statement that errors.Each error document contains the following information:
-
delete.writeErrors.
index
¶ An integer that identifies the delete statement in the
deletes
array, which uses a zero-based index.
-
delete.writeErrors.
code
¶ An integer value identifying the error.
-
delete.writeErrors.
errmsg
¶ A description of the error.
-
-
delete.
writeConcernError
¶ Document that describe error related to write concern and contains the field:
-
delete.writeConcernError.
code
¶ An integer value identifying the cause of the write concern error.
-
delete.writeConcernError.
errmsg
¶ A description of the cause of the write concern error.
-
The following is an example document returned for a successful
delete
command:
The following is an example document returned for a delete
command that encountered an error: