Delete Documents

Learn how to remove specific documents from a MongoDB collection using PyMongo, ensuring data integrity and efficient storage management.

What it is

In MongoDB, documents are the basic unit of data. Deleting them involves removing records that match specific criteria. PyMongo provides methods like delete_one() and delete_many() to handle these operations. The mental model is similar to SQL's DELETE FROM table WHERE condition, but with more flexible query structures using JSON-like objects.

Related terms include filter (the criteria for selection), acknowledged write (confirmation of deletion), and collection (the group of documents).

Why it matters

• Data Hygiene: Removes obsolete or incorrect records to keep databases clean.
• Storage Efficiency: Frees up disk space by eliminating unnecessary data.
• Compliance: Helps meet regulations like GDPR by deleting user data upon request.
• Application Logic: Supports features like "undo" actions or clearing temporary sessions.

Syntax or steps

To delete documents, you need a database connection, a collection reference, and a filter dictionary. The most common method is delete_one(filter), which removes the first document matching the filter. If no document matches, nothing happens. For multiple deletions, use delete_many(filter).

1. Connect to the MongoDB client.
2. Select the database and collection.
3. Define the filter as a Python dictionary.
4. Call the delete method on the collection object.

Example

from pymongo import MongoClient

# Connect to local MongoDB instance
client = MongoClient("mongodb://localhost:27017/")
db = client["my_database"]
col = db["users"]

# Delete a single document where name is 'Ada'
result = col.delete_one({"name": "Ada"})

# Check if a document was deleted
if result.deleted_count == 1:
    print("Document deleted successfully.")
else:
    print("No document found to delete.")

# Close connection
client.close()

Part-by-part explanation:

• MongoClient(...): Establishes a connection to the MongoDB server.
• db = client["my_database"]: Accesses the specific database.
• col = db["users"]: References the collection within that database.
• col.delete_one({"name": "Ada"}): Sends a command to remove the first document where the field name equals "Ada".
• result.deleted_count: An attribute in the response object indicating how many documents were actually removed.

Common mistakes

• Empty Filter: Calling delete_many({}) deletes all documents in the collection. Always verify filters before bulk deletions.
• Ignoring Return Values: Not checking deleted_count can lead to silent failures if the document doesn't exist.
• Wrong Data Types: Querying {"age": "30"} when the stored value is an integer 30 will fail to match. Ensure types align.
• No Connection Handling: Failing to close the client or use context managers can leak connections in long-running applications.

When to use it

Compare delete_one() with delete_many() based on your intent:

Use delete_one() for precise, targeted removals. Use delete_many() for batch operations, always testing filters first.

Practice

Guided Exercise: Write a script that deletes all users older than 65 from a collection named employees. Print the number of deleted records.

Challenge: Modify the script to first count how many employees are over 65, then delete them, and finally verify the count is zero.

Hint: Use {"age": {"$gt": 65}} as the filter.

Quick check

Question: What happens if you call col.delete_one({"id": 999}) and no document has id: 999?

Answer: Nothing is deleted, and result.deleted_count will be 0. No error is raised.

Summary

Deleting documents in PyMongo requires clear filters and careful handling of return values to ensure accuracy. Always distinguish between single and bulk deletions to prevent accidental data loss.