MongoDB Delete

O PyMongo fornece dois métodos para remover documentos de uma coleção: delete_one() remove o primeiro documento correspondente, e delete_many() remove todos os documentos correspondentes. Ambas são operações precisas e orientadas por filtros — você especifica exatamente quais documentos deseja remover usando a mesma sintaxe de consulta do find().

Este capítulo aborda:

• delete_one() — remover um único documento
• delete_many() — remover múltiplos documentos (incluindo todos os documentos)
• Leitura do objeto DeleteResult
• Operadores de filtro que tornam as exclusões precisas
• Tratamento de erros e práticas seguras
• Quando excluir documentos versus descartar a coleção inteira

Pré-requisitos: Python 3.8+, PyMongo instalado (pip install pymongo) e um servidor MongoDB em execução. Consulte MongoDB Get Started para configuração, e MongoDB Insert para entender como os documentos entram em uma coleção.

Conectando e Selecionando uma Coleção

Toda operação de exclusão precisa de um MongoClient, um banco de dados e uma coleção:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mydatabase"]
col = db["customers"]

Todos os exemplos abaixo pressupõem que col está definido dessa forma.

Excluindo Um Documento com delete_one()

delete_one(filter) encontra o primeiro documento que corresponde ao filtro e o exclui. Se vários documentos corresponderem, apenas um é removido (a ordem natural do MongoDB determina qual deles).

result = col.delete_one({"name": "Alice"})
print(result.deleted_count)  # 1 if a match was found, 0 if not

delete_one() nunca lança um erro quando nenhum documento corresponde — ele retorna um DeleteResult com deleted_count = 0.

Correspondência por valor de campo específico

# Delete the customer whose name is "Bob"
result = col.delete_one({"name": "Bob"})

if result.deleted_count == 1:
    print("Document deleted.")
else:
    print("No matching document found.")

Correspondência em campo aninhado

Use a notação de ponto para acessar campos dentro de documentos incorporados:

# Delete the first customer whose city is "London"
result = col.delete_one({"address.city": "London"})
print(result.deleted_count)  # 1 or 0

Excluindo Múltiplos Documentos com delete_many()

delete_many(filter) remove todos os documentos que correspondem ao filtro. Use-o quando precisar limpar um conjunto de registros em uma única chamada.

# Delete all customers whose address starts with "S"
result = col.delete_many({"address": {"$regex": "^S"}})
print(result.deleted_count, "documents deleted")

Excluindo todos os documentos de uma coleção

Passe um filtro vazio {} para remover todos os documentos. A coleção em si e seus índices permanecem — apenas os documentos são removidos:

result = col.delete_many({})
print(result.deleted_count, "documents deleted")

Aviso: delete_many({}) em uma coleção de produção é irreversível. Sempre verifique seu filtro e faça um backup antes de executar exclusões em massa. Se quiser remover a coleção inteiramente (documentos e índices), use col.drop() — consulte MongoDB Drop Collection.

O Objeto DeleteResult

Ambos os métodos retornam um DeleteResult. As duas propriedades que você usará com mais frequência são:

result = col.delete_many({"status": "inactive"})
print(f"Deleted: {result.deleted_count}")
print(f"Acknowledged: {result.acknowledged}")

Operadores de Filtro para Exclusões Precisas

Os mesmos operadores de consulta usados em find() funcionam dentro dos filtros de exclusão.

Excluir por comparação

# Delete all orders with a quantity less than 10
col.delete_many({"qty": {"$lt": 10}})

# Delete all orders with a quantity greater than or equal to 100
col.delete_many({"qty": {"$gte": 100}})

Excluir por expressão regular

# Delete all customers whose name starts with "A" (case-sensitive)
col.delete_many({"name": {"$regex": "^A"}})

Excluir pela existência de um campo

# Delete all documents that have no "email" field
col.delete_many({"email": {"$exists": False}})

Excluir por valor em uma lista

# Delete all documents whose status is either "cancelled" or "expired"
col.delete_many({"status": {"$in": ["cancelled", "expired"]}})

Tratamento de Erros

Envolva as operações de exclusão em um bloco try/except para lidar com os dois modos de falha mais comuns:

• pymongo.errors.OperationFailure — o servidor rejeitou a operação (por exemplo, o usuário conectado não tem privilégios de remove na coleção).
• pymongo.errors.ConnectionFailure — a conexão de rede com o MongoDB foi perdida.

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
col = client["mydatabase"]["customers"]

try:
    result = col.delete_many({"status": "inactive"})
    print(f"{result.deleted_count} documents deleted.")
except pymongo.errors.OperationFailure as e:
    print(f"Server error: {e}")
except pymongo.errors.ConnectionFailure as e:
    print(f"Connection error: {e}")

Exemplo Prático: Fluxo Completo

Este exemplo popula uma coleção, executa exclusões direcionadas e verifica o resultado:

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
col = client["mydatabase"]["customers"]

# 1. Start clean
col.drop()

# 2. Insert sample documents
col.insert_many([
    {"name": "Alice", "city": "Oslo",   "active": True},
    {"name": "Bob",   "city": "Sydney", "active": False},
    {"name": "Carol", "city": "Seattle","active": False},
    {"name": "Dave",  "city": "Sofia",  "active": True},
])
print("Inserted:", col.count_documents({}))  # 4

# 3. Delete the one inactive customer named "Bob"
r1 = col.delete_one({"name": "Bob", "active": False})
print("delete_one:", r1.deleted_count)  # 1

# 4. Delete all customers in cities that start with "S"
r2 = col.delete_many({"city": {"$regex": "^S"}})
print("delete_many (city ^S):", r2.deleted_count)  # 2 (Carol/Seattle, Dave/Sofia)

# 5. Check what remains
remaining = list(col.find({}, {"_id": 0}))
print("Remaining:", remaining)  # [{'name': 'Alice', 'city': 'Oslo', 'active': True}]

Saída esperada:

Inserted: 4
delete_one: 1
delete_many (city ^S): 2
Remaining: [{'name': 'Alice', 'city': 'Oslo', 'active': True}]

Excluir Documentos vs. Descartar uma Coleção

Essas duas operações são frequentemente confundidas:

Escolha delete_many({}) quando precisar esvaziar uma coleção, mas mantendo seus índices e validadores de esquema intactos. Escolha col.drop() quando quiser um começo completamente limpo — por exemplo, entre execuções de testes ou durante uma migração de esquema. Consulte MongoDB Drop Collection para mais detalhes sobre drop().

Resumo

• delete_one(filter) remove o primeiro documento correspondente; delete_many(filter) remove todos os documentos correspondentes.
• Ambos retornam um DeleteResult — verifique deleted_count para confirmar o que foi removido.
• Um filtro vazio {} em delete_many() remove todos os documentos da coleção.
• Use operadores de consulta do MongoDB ($regex, $lt, $in, $exists, …) para construir filtros precisos.
• Envolva as operações em try/except para tratar OperationFailure e ConnectionFailure.
• Para remover a própria coleção, use col.drop() em vez disso.

Capítulos relacionados:

• MongoDB Insert — inserindo documentos com insert_one() e insert_many()
• MongoDB Update — modificando documentos existentes com update_one() e update_many()
• MongoDB Drop Collection — removendo uma coleção inteira incluindo seus índices
• MongoDB Query — construindo filtros com operadores de consulta
• MongoDB Get Started — instalando o PyMongo e conectando ao MongoDB