Criando Collections do MongoDB com Python

Uma collection é o equivalente MongoDB de uma tabela em um banco de dados relacional. Ela agrupa documentos (objetos semelhantes a JSON) e pertence a um único banco de dados. Este capítulo mostra duas formas de criar uma collection com o driver pymongo do Python — explicitamente com create_collection() e implicitamente ao inserir o primeiro documento — além de opções de collection como capped collections e validadores de esquema.

Pré-requisitos

Antes de continuar, certifique-se de ter:

• Python 3.7 ou posterior instalado
• pymongo instalado (pip install pymongo)
• Uma instância MongoDB em execução — seja o MongoDB Atlas (nuvem) ou um servidor local iniciado com mongod

Consulte MongoDB Get Started para o guia completo de configuração e MongoDB Create Database para entender como os bancos de dados funcionam no MongoDB.

Conectando ao MongoDB

Toda collection existe dentro de um banco de dados, portanto o primeiro passo é sempre obter um handle de banco de dados.

Conectar a um servidor MongoDB local e selecionar um banco de dados

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
db = client["mystore"]  # selects (or lazily creates) the database

Para conectar ao MongoDB Atlas, substitua a string de conexão pela do seu painel do Atlas:

client = pymongo.MongoClient(
    "mongodb+srv://<username>:<password>@cluster0.example.mongodb.net/"
)
db = client["mystore"]

Substitua <username>, <password> e o host pelas suas credenciais reais.

Criação Explícita de Collection

Use create_collection() quando precisar controlar as opções da collection no momento da criação (tamanho limitado, validação de esquema, collation etc.).

Criar uma collection explicitamente

import pymongo

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

collection = db.create_collection("customers")
print("Collection created:", collection.name)
# Collection created: customers

create_collection() lança pymongo.errors.CollectionInvalid se uma collection com esse nome já existir. Proteja-se disso com um try/except:

Tratar o caso em que a collection já existe

from pymongo.errors import CollectionInvalid

try:
    collection = db.create_collection("customers")
    print("Created:", collection.name)
except CollectionInvalid:
    print("Collection already exists — using existing one")
    collection = db["customers"]

Regras de Nomenclatura de Collections

Os nomes de collections do MongoDB devem:

• Não ser uma string vazia
• Não conter $ nem o caractere nulo (\0)
• Não começar com system. (esse prefixo é reservado)
• Não ultrapassar 120 bytes quando combinados com o nome do banco de dados e um separador de ponto

Nomes válidos: customers, order_items, 2024_logs. Nomes inválidos: $orders, system.users.

Criação Implícita de Collection

A abordagem mais comum no desenvolvimento cotidiano é deixar o MongoDB criar a collection automaticamente ao inserir o primeiro documento. Se a collection não existir, o MongoDB a cria dinamicamente.

Criar uma collection implicitamente ao inserir um documento

import pymongo

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

products = db["products"]  # no round-trip to the server yet
result = products.insert_one({"name": "Widget", "price": 9.99, "stock": 100})

print("Inserted ID:", result.inserted_id)
# Inserted ID: 6650a1b2c3d4e5f678901234  (an ObjectId — yours will differ)

A atribuição db["products"] é puramente local; o MongoDB só cria a collection quando a chamada insert_one() chega ao servidor.

Capped Collections

Uma capped collection é um buffer circular de tamanho fixo. Quando atinge seu limite de tamanho, o MongoDB substitui automaticamente os documentos mais antigos. Isso torna as capped collections ideais para logs, trilhas de auditoria e fluxos de eventos.

Criar uma capped collection (máximo de 1 MB, máximo de 1000 documentos)

import pymongo

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

logs = db.create_collection(
    "access_logs",
    capped=True,
    size=1_048_576,   # maximum size in bytes (1 MB) — required for capped collections
    max=1000,         # optional: maximum number of documents
)
print("Capped collection created:", logs.name)
# Capped collection created: access_logs

Regras principais das capped collections:

• size é obrigatório quando capped=True; max é opcional.
• Não é possível fragmentar (shard) uma capped collection.
• Os documentos em uma capped collection não podem crescer além do tamanho original na atualização (o preenchimento é adicionado automaticamente, mas o tamanho do slot é fixo).

Adicionando um Validador de Esquema

A validação de esquema do MongoDB permite impor a estrutura de documentos no nível do banco de dados. As regras de validação são expressas como JSON Schema.

Criar uma collection com um validador JSON Schema

import pymongo

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

validator = {
    "$jsonSchema": {
        "bsonType": "object",
        "required": ["name", "price"],
        "properties": {
            "name":  {"bsonType": "string",  "description": "must be a string"},
            "price": {"bsonType": "double",  "description": "must be a number"},
            "stock": {"bsonType": "int",     "description": "must be an integer"},
        },
    }
}

orders = db.create_collection("orders", validator=validator)
print("Collection with validator created:", orders.name)
# Collection with validator created: orders

Quando validationAction é o padrão ("error"), o MongoDB rejeita qualquer inserção ou atualização que viole o esquema. Defina-o como "warn" para registrar violações sem rejeitar escritas.

Listando Collections

Para ver quais collections existem em um banco de dados, use list_collection_names(). Essa também é uma forma prática de verificar se uma collection já existe antes de chamar create_collection().

Listar todas as collections de um banco de dados

import pymongo

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

names = db.list_collection_names()
print(names)
# ['customers', 'products', 'orders', 'access_logs']

Verificar se uma collection existe antes de criá-la

if "customers" not in db.list_collection_names():
    db.create_collection("customers")
    print("Created customers collection")
else:
    print("customers already exists")

list_collection_names() retorna uma lista Python simples, portanto qualquer operação de lista funciona no resultado.

Escolhendo entre Criação Explícita e Implícita

Próximos Passos

Agora que você tem uma collection, pode começar a trabalhar com documentos:

• MongoDB Insert — adicione documentos simples e múltiplos com insert_one() e insert_many()
• MongoDB Find — consulte documentos de uma collection
• MongoDB Drop Collection — exclua uma collection quando não precisar mais dela