- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.remove()
db.collection.remove()¶
On this page
Definition¶
-
db.collection.
remove
()¶ Removes documents from a collection.
The
db.collection.remove()
method can have one of two syntaxes. Theremove()
method can take a query document and an optionaljustOne
boolean:Or the method can take a query document and an optional remove options document:
New in version 2.6.
Parameter Type Description query
document Specifies deletion criteria using query operators. To delete all documents in a collection, pass an empty document (
{}
).Changed in version 2.6: In previous versions, the method invoked with no query parameter deleted all documents in a collection.
justOne
boolean Optional. To limit the deletion to just one document, set to true
. Omit to use the default value offalse
and delete all documents matching the deletion criteria.writeConcern
document Optional. A document expressing the write concern. Omit to use the default write concern. See Write Concern.
New in version 2.6.
Changed in version 2.6: The
remove()
returns an object that contains the status of the operation.Returns: A WriteResult object that contains the status of the operation.
Behavior¶
Write Concern¶
Changed in version 2.6.
The remove()
method uses the
delete
command, which uses the default write concern. To specify a different write concern,
include the write concern in the options parameter.
Query Considerations¶
By default, remove()
removes all documents
that match the query
expression. Specify the justOne
option to
limit the operation to removing a single document. To delete a single
document sorted by a specified order, use the findAndModify() method.
When removing multiple documents, the remove operation may interleave
with other read and/or write operations to the collection. For
unsharded collections, you can override this behavior with the
$isolated
operator, which “isolates” the remove operation and
disallows yielding during the operation. This ensures that no client
can see the affected documents until they are all processed or an error
stops the remove operation.
See Isolate Remove Operations for an example.
Capped Collections¶
You cannot use the remove()
method
with a capped collection.
Sharded Collections¶
All remove()
operations for a sharded
collection that specify the justOne
option must include the
shard key or the _id
field in the query specification.
remove()
operations specifying justOne
in a sharded collection which do not contain either the
shard key or the _id
field return an error.
Examples¶
The following are examples of the remove()
method.
Remove All Documents from a Collection¶
To remove all documents in a collection, call the remove
method with an empty query document {}
.
The following operation deletes all documents from the bios
collection:
This operation is not equivalent to the
drop()
method.
To remove all documents from a collection, it may be more efficient
to use the drop()
method to drop the entire
collection, including the indexes, and then recreate the collection
and rebuild the indexes.
Remove All Documents that Match a Condition¶
To remove the documents that match a deletion criteria, call the
remove()
method with the <query>
parameter:
The following operation removes all the documents from the collection
products
where qty
is greater than 20
:
Override Default Write Concern¶
The following operation to a replica set removes all the documents from
the collection products
where qty
is greater than 20
and
specifies a write concern of "w:
majority"
with a wtimeout
of 5000 milliseconds such that the
method returns after the write propagates to a majority of the voting
replica set members or the method times out after 5 seconds.
Changed in version 3.0: In previous versions, majority
referred to the majority of all
members of the replica set instead of the majority of the voting
members.
Remove a Single Document that Matches a Condition¶
To remove the first document that match a deletion criteria, call the
remove
method with the query
criteria and the justOne
parameter set to true
or 1
.
The following operation removes the first document from the collection
products
where qty
is greater than 20
:
Isolate Remove Operations¶
To isolate the query, include $isolated: 1
in the
<query>
parameter as in the following examples:
WriteResult¶
Changed in version 2.6.
Successful Results¶
The remove()
returns a WriteResult
object that contains the status of the operation. Upon success, the
WriteResult
object contains information on the number of
documents removed:
See also
Write Concern Errors¶
If the remove()
method encounters write
concern errors, the results include the
WriteResult.writeConcernError
field:
See also