Créer des collections MongoDB avec Python

Une collection est l'équivalent MongoDB d'une table dans une base de données relationnelle. Elle regroupe des documents (des objets similaires à JSON) et appartient à une seule base de données. Ce chapitre vous montre deux façons de créer une collection avec le pilote Python pymongo — explicitement avec create_collection() et implicitement en insérant le premier document — ainsi que les options de collection telles que les collections plafonnées et les validateurs de schéma.

Prérequis

Avant de continuer, assurez-vous d'avoir :

• Python 3.7 ou une version ultérieure installée
• pymongo installé (pip install pymongo)
• Une instance MongoDB en cours d'exécution — soit MongoDB Atlas (cloud) soit un serveur local démarré avec mongod

Consultez MongoDB Get Started pour le guide de configuration complet et MongoDB Create Database pour comprendre le fonctionnement des bases de données dans MongoDB.

Connexion à MongoDB

Chaque collection réside dans une base de données, donc la première étape consiste toujours à obtenir un handle de base de données.

Se connecter à un serveur MongoDB local et sélectionner une base de données

import pymongo

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

Pour vous connecter à MongoDB Atlas, remplacez la chaîne de connexion par celle de votre tableau de bord Atlas :

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

Remplacez <username>, <password> et l'hôte par vos identifiants réels.

Création explicite de collection

Utilisez create_collection() lorsque vous devez contrôler les options de collection au moment de la création (taille plafonnée, validation de schéma, collation, etc.).

Créer une collection explicitement

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() lève pymongo.errors.CollectionInvalid si une collection portant ce nom existe déjà. Gérez ce cas avec un try/except :

Gérer le cas où la collection existe déjà

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

Règles de nommage des collections

Les noms de collection MongoDB doivent :

• Ne pas être une chaîne vide
• Ne pas contenir $ ni le caractère nul (\0)
• Ne pas commencer par system. (ce préfixe est réservé)
• Ne pas dépasser 120 octets une fois combinés avec le nom de la base de données et un séparateur point

Noms valides : customers, order_items, 2024_logs. Noms invalides : $orders, system.users.

Création implicite de collection

L'approche la plus courante au quotidien consiste à laisser MongoDB créer la collection automatiquement lors de l'insertion du premier document. Si la collection n'existe pas, MongoDB la crée à la volée.

Créer une collection implicitement en insérant un document

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'affectation db["products"] est purement locale ; MongoDB ne crée la collection que lorsque l'appel à insert_one() atteint le serveur.

Collections plafonnées

Une collection plafonnée est un tampon circulaire de taille fixe. Lorsqu'elle atteint sa limite de taille, MongoDB écrase automatiquement les documents les plus anciens. Cela rend les collections plafonnées idéales pour les journaux, les pistes d'audit et les flux d'événements.

Créer une collection plafonnée (max 1 Mo, max 1000 documents)

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

Règles clés pour les collections plafonnées :

• size est obligatoire lorsque capped=True ; max est facultatif.
• Vous ne pouvez pas partitionner une collection plafonnée.
• Les documents d'une collection plafonnée ne peuvent pas dépasser leur taille d'origine lors d'une mise à jour (le rembourrage est ajouté automatiquement, mais la taille de l'emplacement est fixe).

Ajout d'un validateur de schéma

La validation de schéma de MongoDB vous permet d'imposer la structure des documents au niveau de la base de données. Les règles de validation sont exprimées en JSON Schema.

Créer une collection avec un validateur 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

Lorsque validationAction est la valeur par défaut ("error"), MongoDB rejette toute insertion ou mise à jour qui viole le schéma. Définissez-la sur "warn" pour journaliser les violations sans rejeter les écritures.

Liste des collections

Pour voir quelles collections existent dans une base de données, utilisez list_collection_names(). C'est également un moyen pratique de vérifier si une collection existe déjà avant d'appeler create_collection().

Lister toutes les collections d'une base de données

import pymongo

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

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

Vérifier si une collection existe avant de la créer

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

list_collection_names() retourne une liste Python ordinaire, donc toute opération de liste fonctionne sur le résultat.

Choisir entre création explicite et implicite

Étapes suivantes

Maintenant que vous avez une collection, vous pouvez commencer à travailler avec des documents :

• MongoDB Insert — ajoutez des documents uniques ou multiples avec insert_one() et insert_many()
• MongoDB Find — interrogez des documents d'une collection
• MongoDB Drop Collection — supprimez une collection lorsque vous n'en avez plus besoin