Creare Collezioni MongoDB con Python

Una collezione è l'equivalente MongoDB di una tabella in un database relazionale. Contiene un gruppo di documenti (object simili a JSON) e appartiene a un singolo database. Questo capitolo mostra due modi per creare una collezione con il driver pymongo di Python — esplicitamente con create_collection() e implicitamente inserendo il primo documento — insieme alle opzioni di collezione come le collezioni con limite e i validatori di schema.

Prerequisiti

Prima di continuare, assicurati di avere:

• Python 3.7 o versioni successive installato
• pymongo installato (pip install pymongo)
• Un'istanza MongoDB in esecuzione — MongoDB Atlas (cloud) o un server locale avviato con mongod

Consulta MongoDB Inizia per la procedura di configurazione completa e MongoDB Crea Database per capire come funzionano i database in MongoDB.

Connessione a MongoDB

Ogni collezione vive all'interno di un database, quindi il primo passo è sempre ottenere un handle al database.

Connetti a un server MongoDB locale e seleziona un database

import pymongo

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

Per connetterti a MongoDB Atlas, sostituisci la stringa di connessione con quella del tuo dashboard Atlas:

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

Sostituisci <username>, <password> e l'host con le tue credenziali effettive.

Creazione Esplicita di una Collezione

Usa create_collection() quando hai bisogno di controllare le opzioni della collezione al momento della creazione (dimensione con limite, validazione dello schema, collation, ecc.).

Crea una collezione esplicitamente

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() genera pymongo.errors.CollectionInvalid se esiste già una collezione con quel nome. Gestisci questo caso con un try/except:

Gestisci il caso in cui la collezione esiste già

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"]

Regole di Denominazione delle Collezioni

I nomi delle collezioni MongoDB devono:

• Non essere una stringa vuota
• Non contenere $ o il carattere null (\0)
• Non iniziare con system. (quel prefisso è riservato)
• Non superare i 120 byte quando combinati con il nome del database e un separatore punto

Nomi validi: customers, order_items, 2024_logs. Nomi non validi: $orders, system.users.

Creazione Implicita di una Collezione

L'approccio più comune nello sviluppo quotidiano è lasciare che MongoDB crei automaticamente la collezione quando si inserisce il primo documento. Se la collezione non esiste, MongoDB la crea al volo.

Crea una collezione implicitamente inserendo 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)

L'assegnazione db["products"] è puramente locale; MongoDB crea la collezione solo quando la chiamata insert_one() raggiunge il server.

Collezioni con Limite

Una collezione con limite è un buffer circolare di dimensione fissa. Una volta raggiunto il limite di dimensione, MongoDB sovrascrive automaticamente i documenti più vecchi. Questo rende le collezioni con limite ideali per log, audit trail e flussi di eventi.

Crea una collezione con limite (max 1 MB, max 1000 documenti)

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

Regole principali per le collezioni con limite:

• size è obbligatorio quando capped=True; max è opzionale.
• Non è possibile partizionare (shard) una collezione con limite.
• I documenti in una collezione con limite non possono crescere oltre la loro dimensione originale in fase di aggiornamento (il padding viene aggiunto automaticamente, ma la dimensione dello slot è fissa).

Aggiungere un Validatore di Schema

La validazione dello schema di MongoDB consente di imporre la struttura del documento a livello di database. Le regole di validazione sono espresse come JSON Schema.

Crea una collezione con un validatore 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 è il valore predefinito ("error"), MongoDB rifiuta qualsiasi inserimento o aggiornamento che viola lo schema. Impostalo su "warn" per registrare le violazioni senza rifiutare le scritture.

Elencare le Collezioni

Per vedere quali collezioni esistono in un database, usa list_collection_names(). Questo è anche un modo comodo per verificare se una collezione esiste già prima di chiamare create_collection().

Elenca tutte le collezioni in un database

import pymongo

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

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

Verifica se una collezione esiste prima di 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() restituisce una lista Python normale, quindi qualsiasi operazione sulle liste funziona sul risultato.

Scegliere tra Creazione Esplicita e Implicita

Passi Successivi

Ora che hai una collezione, puoi iniziare a lavorare con i documenti:

• MongoDB Insert — aggiungi documenti singoli e multipli con insert_one() e insert_many()
• MongoDB Find — interroga documenti da una collezione
• MongoDB Drop Collection — elimina una collezione quando non ne hai più bisogno