Primeiros Passos com MongoDB

Este capítulo apresenta o MongoDB e mostra como usá-lo a partir do Python com o driver PyMongo. Ao final, você terá o MongoDB instalado, uma conexão funcionando e uma visão clara de como inserir, consultar, atualizar e excluir documentos.

O que é MongoDB?

MongoDB é um banco de dados de documentos — um tipo de banco de dados NoSQL que armazena registros como documentos no formato JSON, em vez de linhas e colunas. Cada documento é um objeto independente que pode ter campos aninhados e arrays, o que o torna uma escolha natural para dados que não se encaixam bem em um esquema fixo.

Características principais:

• Esquema flexível. Dois documentos na mesma coleção podem ter campos completamente diferentes.
• Linguagem de consulta rica. Filtre, projete, ordene, limite e agregue com uma única chamada ao driver.
• Escalabilidade horizontal. Sharding integrado e replica sets lidam com grandes volumes de dados e alta disponibilidade.
• Nativo em JSON. Os documentos são armazenados como BSON (Binary JSON), portanto dicionários Python mapeiam diretamente para documentos MongoDB.

Quando escolher MongoDB em vez de um banco de dados relacional

Instalando o MongoDB

Opção 1 — Instalação local

Baixe o MongoDB Community Server em mongodb.com/try/download/community, escolha seu sistema operacional e siga o instalador. Em seguida, inicie o servidor:

# macOS / Linux
mongod --dbpath /data/db

# Windows (PowerShell, run as Administrator)
mongod --dbpath "C:\data\db"

Verifique se o MongoDB está em execução abrindo um segundo terminal e executando:

mongosh --eval "db.adminCommand('ping')"

Saída esperada:

{ ok: 1 }

Opção 2 — Docker (mais rápido para desenvolvimento)

Se você tiver o Docker instalado, pode ignorar a instalação local completamente:

docker run -d --name mongo -p 27017:27017 mongo:7

Isso baixa a imagem oficial do MongoDB 7 e expõe a porta 27017 na sua máquina. Pare com docker stop mongo.

Opção 3 — MongoDB Atlas (nuvem)

Atlas é o serviço de nuvem totalmente gerenciado do MongoDB, com uma camada gratuita. Após se cadastrar, copie a string de conexão do painel — ela se parece com:

mongodb+srv://username:[email protected]/

Você pode usar esse URI em qualquer lugar onde vir mongodb://localhost:27017/ neste capítulo.

Instalando o Driver PyMongo

PyMongo é o driver Python oficial para MongoDB. Instale com pip:

pip install pymongo

Para usar o MongoDB Atlas, instale também os extras que incluem o resolvedor DNS:

pip install "pymongo[srv]"

Verifique a instalação:

import pymongo
print(pymongo.version)
# e.g. 4.7.3

Conectando ao MongoDB

MongoClient é o ponto de entrada para todas as operações do driver. Crie um cliente por aplicação e reutilize-o — o cliente gerencia um pool de conexões interno.

from pymongo import MongoClient

# Local server with default host and port
client = MongoClient("mongodb://localhost:27017/")

# Verify connectivity (raises ConnectionFailure if the server is unreachable)
client.admin.command("ping")
print("Connected successfully")

Para código em produção, sempre trate erros de conexão explicitamente:

from pymongo import MongoClient
from pymongo.errors import ConnectionFailure

client = MongoClient("mongodb://localhost:27017/", serverSelectionTimeoutMS=3000)

try:
    client.admin.command("ping")
    print("Connected to MongoDB")
except ConnectionFailure as e:
    print("Connection failed:", e)

Formato da string de conexão

mongodb://[username:password@]host[:port][/database][?options]

Opções comuns:

Bancos de Dados e Coleções

O MongoDB organiza os dados em uma hierarquia de dois níveis:

• Um banco de dados agrupa coleções relacionadas (semelhante a um schema ou banco de dados SQL).
• Uma coleção contém documentos (semelhante a uma tabela SQL, mas sem esquema fixo).

Ambos são criados de forma lazy — eles passam a existir na primeira vez que você insere um documento. Nunca é necessário executar CREATE DATABASE ou CREATE TABLE.

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")

# Reference a database (not yet created on disk)
db = client["mystore"]

# Reference a collection inside it (also not yet on disk)
products = db["products"]

# The database and collection are created when the first document is inserted

Operações CRUD Básicas

Os exemplos a seguir se complementam. Execute-os em ordem se estiver acompanhando de forma interativa.

Create — inserir documentos

Use insert_one() para um único documento e insert_many() para um lote:

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")
db = client["mystore"]
products = db["products"]

# Insert a single document
result = products.insert_one({
    "name": "Laptop",
    "brand": "Acme",
    "price": 999.99,
    "in_stock": True
})
print("Inserted id:", result.inserted_id)

# Insert multiple documents at once
new_products = [
    {"name": "Mouse",    "brand": "Acme", "price": 29.99,  "in_stock": True},
    {"name": "Keyboard", "brand": "Acme", "price": 79.99,  "in_stock": False},
    {"name": "Monitor",  "brand": "Zeta", "price": 349.99, "in_stock": True},
]
batch_result = products.insert_many(new_products)
print("Inserted ids:", batch_result.inserted_ids)

O MongoDB adiciona automaticamente um campo _id (do tipo ObjectId) a cada documento, caso você não forneça um. Este campo é a chave primária e é sempre único dentro de uma coleção.

Read — consultar documentos

find_one() retorna o primeiro documento correspondente (ou None). find() retorna um cursor que você pode iterar.

# Retrieve one document (no filter = the first document in natural order)
doc = products.find_one()
print(doc)

# Retrieve all documents in the collection
for p in products.find():
    print(p["name"], "-", p["price"])

# Filter: products that are in stock
for p in products.find({"in_stock": True}):
    print(p["name"])

# Projection: return only name and price (exclude _id)
for p in products.find({}, {"_id": 0, "name": 1, "price": 1}):
    print(p)

Operadores de consulta

A linguagem de consulta do MongoDB usa operadores prefixados com $:

# Products cheaper than £100
cheap = products.find({"price": {"$lt": 100}})

# In-stock products from brand "Acme" or "Zeta"
multi = products.find({
    "in_stock": True,
    "brand": {"$in": ["Acme", "Zeta"]}
})

# Price between 50 and 500 (inclusive)
range_q = products.find({"price": {"$gte": 50, "$lte": 500}})

Operadores de comparação comuns:

Update — modificar documentos

update_one() modifica o primeiro documento correspondente. update_many() modifica todas as correspondências. Sempre use o operador $set para alterar campos específicos — sem ele, você substitui o documento inteiro.

# Update a single document: change the price of "Mouse"
update_result = products.update_one(
    {"name": "Mouse"},          # filter
    {"$set": {"price": 24.99}}  # update
)
print("Matched:", update_result.matched_count,
      "Modified:", update_result.modified_count)

# Mark all Acme products as in stock
products.update_many(
    {"brand": "Acme"},
    {"$set": {"in_stock": True}}
)

# Increment a field value
products.update_one(
    {"name": "Laptop"},
    {"$inc": {"price": -50}}  # reduce price by 50
)

Operadores de atualização comuns:

Delete — remover documentos

delete_one() remove o primeiro documento correspondente. delete_many() remove todas as correspondências.

# Remove a single document
del_result = products.delete_one({"name": "Keyboard"})
print("Deleted count:", del_result.deleted_count)

# Remove all out-of-stock items
products.delete_many({"in_stock": False})

# Confirm what is left
print("Remaining products:")
for p in products.find({}, {"_id": 0, "name": 1}):
    print(" -", p["name"])

Armadilhas Comuns

A criação lazy pode esconder erros de digitação

Como o MongoDB cria bancos de dados e coleções sob demanda, um erro de digitação cria silenciosamente um segundo banco de dados vazio em vez de gerar um erro:

# Intended: client["mystore"]   Actual: client["mystoree"]
db = client["mystoree"]  # no error, but your data goes to the wrong database

Solução: defina nomes de banco de dados e coleções como constantes no nível do módulo:

DB_NAME  = "mystore"
COL_NAME = "products"

db = client[DB_NAME]
products = db[COL_NAME]

Erros de conexão aparecem apenas na primeira operação

MongoClient() é bem-sucedido mesmo quando o MongoDB não está em execução. O erro aparece apenas quando você faz uma requisição real. Use serverSelectionTimeoutMS e uma verificação com ping na inicialização (conforme mostrado na seção de conexão acima) para falhar rapidamente.

A ausência de $set substitui o documento inteiro

# WRONG — replaces the whole document with just {"price": 24.99}
products.update_one({"name": "Mouse"}, {"price": 24.99})

# CORRECT — only changes the price field
products.update_one({"name": "Mouse"}, {"$set": {"price": 24.99}})

find() retorna um cursor, não uma lista

Um cursor é lazy — os documentos são buscados do servidor apenas à medida que você itera. Se precisar de uma lista simples, converta explicitamente:

all_products = list(products.find())

Tenha cuidado com coleções grandes: buscar tudo na memória de uma vez pode esgotar a RAM.

O que Vem a Seguir

Este capítulo cobriu os conceitos essenciais. O restante da série Python MongoDB aprofunda cada tópico:

• MongoDB Create Database — como a criação lazy funciona e como verificar se um banco de dados existe.
• MongoDB Create Collection — opções de criação de coleções e schemas de validação.
• MongoDB Insert — insert_one(), insert_many() e tratamento de erros de chave duplicada.
• MongoDB Find — projeções, cursores e ordenação.
• MongoDB Query — referência completa de operadores de consulta.
• MongoDB Update — update_one(), update_many(), upsert e operadores de array.
• MongoDB Delete — padrões de exclusão segura e drop().
• MongoDB Sort — ordenação por campo único e por múltiplos campos.
• MongoDB Limit — paginação com limit() e skip().
• MongoDB Drop Collection — remoção completa de uma coleção.