4.3.4 Collection.remove()

The Collection.remove() function is for removing documents in a collection, similar to the DELETE statement for an SQL database. It takes a search condition string (SearchConditionStr) as a parameter to specify the documents that should be removed from the collection (a detailed explanation of the SearchConditionStr can be found in Section 4.3.2, “Collection.find()”). remove() returns an error if no search condition string is provided, or if an empty string is provided. All documents in the collection are removed if any expression that evaluates to true without matching any document (for example, “true” or “_id IS NOT NULL”) is passed as the search condition string.

The following methods can be chained to the remove() method to configure the deletion:

limit(int): Limits the number of documents to be deleted to int.
sort(sortCriteriaList): Sort the order in which documents are to be deleted according to sortCriteriaList, which is either a comma-separated list or an array of sortCriteria. Each sortCriteria consists of a component name and a search order (asc for ascending, or desc for descending). For example:
- sort('name asc', 'age desc')
- sort(['name asc', 'age desc'])
The method is usually used in combination with the limit() method to determine which of the documents matched by the search condition string are to be deleted.

Parameter binding using bind() is also supported, and the execute() function triggers the actual execution of the remove operation. The following example shows how to use the Collection.remove() function. It assumes some documents have been added to the collection as illustrated by the code example in Section 4.3.1, “Collection.add()”:

# Use the collection 'my_collection'
myColl = db.get_collection('my_collection')

# Remove documents by criteria
myColl.remove('name like :name AND age < :age') \
  .limit(1).bind('name','N%').bind('age', 60).execute()

See also CollectionRemoveFunction for the syntax of add() in EBNF.