Crear colecciones en MongoDB con Python

Una colección es el equivalente en MongoDB de una tabla en una base de datos relacional. Contiene un grupo de documentos (objetos similares a JSON) y pertenece a una sola base de datos. Este capítulo muestra dos formas de crear una colección con el driver pymongo de Python: de forma explícita con create_collection() y de forma implícita insertando el primer documento, junto con opciones de colección como colecciones limitadas y validadores de esquema.

Prerrequisitos

Antes de continuar, asegúrate de tener:

• Python 3.7 o posterior instalado
• pymongo instalado (pip install pymongo)
• Una instancia de MongoDB en ejecución: ya sea MongoDB Atlas (en la nube) o un servidor local iniciado con mongod

Consulta MongoDB Get Started para el recorrido completo de configuración y MongoDB Create Database para entender cómo funcionan las bases de datos en MongoDB.

Conexión a MongoDB

Cada colección vive dentro de una base de datos, por lo que el primer paso siempre es obtener un identificador de base de datos.

Conectar a un servidor MongoDB local y seleccionar una base de datos

import pymongo

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

Para conectarte a MongoDB Atlas, reemplaza la cadena de conexión con la de tu panel de control de Atlas:

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

Reemplaza <username>, <password> y el host con tus credenciales reales.

Creación Explícita de Colecciones

Usa create_collection() cuando necesites controlar las opciones de la colección en el momento de su creación (tamaño limitado, validación de esquema, intercalación, etc.).

Crear una colección de forma explícita

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() lanza pymongo.errors.CollectionInvalid si ya existe una colección con ese nombre. Protégete de esto con un bloque try/except:

Manejar el caso en que la colección ya 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"]

Reglas de Nomenclatura de Colecciones

Los nombres de colecciones en MongoDB deben:

• No ser una cadena vacía
• No contener $ ni el carácter nulo (\0)
• No comenzar con system. (ese prefijo está reservado)
• No superar 120 bytes al combinarse con el nombre de la base de datos y un separador de punto

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

Creación Implícita de Colecciones

El enfoque más común en el desarrollo cotidiano es dejar que MongoDB cree la colección automáticamente al insertar el primer documento. Si la colección no existe, MongoDB la crea al vuelo.

Crear una colección de forma implícita insertando un 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)

La asignación db["products"] es puramente local; MongoDB solo crea la colección cuando la llamada a insert_one() llega al servidor.

Colecciones Limitadas (Capped Collections)

Una colección limitada es un búfer circular de tamaño fijo. Una vez que alcanza su límite de tamaño, MongoDB sobrescribe automáticamente los documentos más antiguos. Esto hace que las colecciones limitadas sean ideales para registros, trazas de auditoría y flujos de eventos.

Crear una colección limitada (máx. 1 MB, máx. 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

Reglas clave de las colecciones limitadas:

• size es obligatorio cuando capped=True; max es opcional.
• No puedes fragmentar (sharding) una colección limitada.
• Los documentos en una colección limitada no pueden crecer más allá de su tamaño original en una actualización (el relleno se agrega automáticamente, pero el tamaño del espacio es fijo).

Agregar un Validador de Esquema

La validación de esquema de MongoDB permite aplicar la estructura del documento a nivel de base de datos. Las reglas de validación se expresan como JSON Schema.

Crear una colección con un 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

Cuando validationAction tiene el valor predeterminado ("error"), MongoDB rechaza cualquier inserción o actualización que viole el esquema. Establécelo en "warn" para registrar las infracciones sin rechazar las escrituras.

Listar Colecciones

Para ver qué colecciones existen en una base de datos, usa list_collection_names(). También es una forma práctica de comprobar si una colección ya existe antes de llamar a create_collection().

Listar todas las colecciones de una base de datos

import pymongo

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

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

Comprobar si una colección existe antes de crearla

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

list_collection_names() devuelve una lista Python normal, por lo que cualquier operación de lista funciona sobre el resultado.

Elegir entre Creación Explícita e Implícita

Próximos Pasos

Ahora que tienes una colección, puedes empezar a trabajar con documentos:

• MongoDB Insert — agrega documentos individuales y múltiples con insert_one() e insert_many()
• MongoDB Find — consulta documentos de una colección
• MongoDB Drop Collection — elimina una colección cuando ya no la necesites