Docs Menu

Docs Home → Develop Applications → Python Drivers → PyMongo

Delete Documents

On this page

  • Overview
  • Sample Data
  • Delete Operations
  • Delete One Document
  • Delete Multiple Documents
  • Customize the Delete Operation
  • Return Value
  • API Documentation

Overview

In this guide, you can learn how to use PyMongo 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 delete_one() or delete_many() methods.

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with PyMongo tutorial.

Delete Operations

You can perform delete operations in MongoDB by using the following methods:

  • delete_one(), which deletes the first document that matches the search criteria

  • delete_many(), which deletes all documents that match the search criteria

Each delete method requires a query filter document, which specifies the search criteria that 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 delete_one() method to remove a document in the restaurants collection with a name value of "Ready Penny Inn":

query_filter = { "name": "Ready Penny Inn" }
result = restaurants.delete_one(query_filter)

Delete Multiple Documents

The following example uses the delete_many() method to remove all documents in the restaurants collection with a borough value of "Brooklyn":

query_filter = { "borough": "Brooklyn" }
result = restaurants.delete_many(query_filter)

Customize the Delete Operation

The delete_one() and delete_many() methods optionally accept additional parameters, which represent options you can use to configure the delete operation. If you don't specify any additional options, the driver does not customize the delete operation.

Property
Description
collation
Specifies the kind of language collation to use when sorting results. For more information, see Collation 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.
session
An instance of ClientSession.
let
A map of parameter names and values. 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.
comment
A comment to attach to the operation. For more information, see the delete command fields guide in the MongoDB Server manual for more information.

The following code uses the delete_many() method to delete all documents in the restaurants collection with a name value that includes the string "Mongo". It also uses the comment option to add a comment to the operation:

query_filter = { 'name': {'$regex': 'Mongo' }}
result = restaurants.delete_many(query_filter, comment="Deleting Mongo restaurants")

Tip

If the preceding example used the delete_one() method instead of delete_many(), the driver would delete only the first document with a name value that includes "Mongo".

Return Value

The delete_one() and delete_many() methods return a DeleteResult type. This type contains the following properties:

  • deleted_count, which indicates the number of documents deleted

  • acknowledged, which indicates if the server acknowledges the result

  • raw_result, which is the raw result returned by the server

Note

If the acknowledged attribute is False, all other attributes of DeleteResult raise an InvalidOperation exception when accessed. The driver cannot determine these values if the server does not acknowledge the write operation.

If the query filter does not match any documents, the driver doesn't delete any documents and deleted_count is 0.

API Documentation

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

← Replace Documents
Bulk Write Operations →

On this page