Limiter les résultats de requêtes MongoDB en Python avec PyMongo

La méthode limit() de PyMongo vous permet de limiter le nombre de documents renvoyés par une requête. Cette page explique ce que fait limit(), quand l'utiliser, comment la combiner avec skip() pour la pagination et comment la chaîner avec sort() pour des ensembles de résultats ordonnés et bornés.

Prérequis

Vous devez avoir PyMongo installé et une instance MongoDB en cours d'exécution. Installez le pilote avec :

pip install pymongo

Connectez-vous ensuite à votre base de données :

import pymongo

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

Si vous débutez avec la connexion et l'insertion de documents, consultez d'abord les chapitres MongoDB Get Started et MongoDB Insert.

Ce que fait limit()

Appeler .limit(n) sur un curseur indique à MongoDB de renvoyer au plus n documents. Sans cette méthode, find() renvoie tous les documents correspondants — ce qui peut être coûteux sur des collections volumineuses.

# Returns ALL documents — can be slow on large collections
all_docs = col.find()

# Returns at most 5 documents
five_docs = col.find().limit(5)

Passer 0 à limit() est traité de la même façon que de ne pas l'appeler du tout : MongoDB renvoie tous les documents correspondants.

# These two are equivalent — both return all documents
col.find().limit(0)
col.find()

Exemple de base

Le script suivant insère dix documents clients exemples, puis récupère uniquement les trois premiers :

import pymongo

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

# Insert sample data (skip if your collection already has data)
col.drop()
names = ["Alice", "Bob", "Charlie", "Diana", "Eve",
         "Frank", "Grace", "Hank", "Iris", "Jack"]
col.insert_many([{"name": n, "rank": i + 1} for i, n in enumerate(names)])

# Retrieve only the first 3 documents
results = col.find({}, {"_id": 0}).limit(3)

for doc in results:
    print(doc)

Résultat attendu :

{'name': 'Alice', 'rank': 1}
{'name': 'Bob', 'rank': 2}
{'name': 'Charlie', 'rank': 3}

Le deuxième argument de find() est une projection — {"_id": 0} supprime le champ _id pour rendre le résultat plus lisible.

Combiner limit() avec sort()

limit() est plus utile lorsqu'elle est associée à sort(). Sans tri, MongoDB renvoie les documents dans l'ordre naturel (ordre d'insertion sur une collection neuve, mais non garanti après des mises à jour ou des suppressions). Trier en premier garantit que les « N premiers » résultats ont un sens.

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
col = client["mydatabase"]["customers"]

# Top 3 customers by rank (ascending)
top3 = col.find({}, {"_id": 0}).sort("rank", pymongo.ASCENDING).limit(3)

print("Top 3 by rank:")
for doc in top3:
    print(doc)

# Bottom 3 customers by rank (descending = highest rank number first)
bottom3 = col.find({}, {"_id": 0}).sort("rank", pymongo.DESCENDING).limit(3)

print("\nBottom 3 by rank:")
for doc in bottom3:
    print(doc)

Résultat attendu :

Top 3 by rank:
{'name': 'Alice', 'rank': 1}
{'name': 'Bob', 'rank': 2}
{'name': 'Charlie', 'rank': 3}

Bottom 3 by rank:
{'name': 'Jack', 'rank': 10}
{'name': 'Iris', 'rank': 9}
{'name': 'Hank', 'rank': 8}

Consultez le chapitre MongoDB Sort pour un guide complet des options de tri.

Pagination avec skip() et limit()

skip(n) indique à MongoDB d'ignorer les n premiers documents avant d'appliquer limit(). Ensemble, elles permettent d'implémenter une pagination par page :

page_1 = skip(0).limit(page_size)
page_2 = skip(page_size).limit(page_size)
page_N = skip((N-1) * page_size).limit(page_size)

Voici un helper réutilisable qui récupère une page à la fois :

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
col = client["mydatabase"]["customers"]

def get_page(collection, page_number, page_size, sort_field="rank"):
    """Return one page of documents (1-indexed page numbers)."""
    offset = (page_number - 1) * page_size
    cursor = (
        collection.find({}, {"_id": 0})
        .sort(sort_field, pymongo.ASCENDING)
        .skip(offset)
        .limit(page_size)
    )
    return list(cursor)

# Fetch pages of 3 documents each
page1 = get_page(col, page_number=1, page_size=3)
page2 = get_page(col, page_number=2, page_size=3)
page3 = get_page(col, page_number=3, page_size=3)

print("Page 1:", page1)
print("Page 2:", page2)
print("Page 3:", page3)

Résultat attendu :

Page 1: [{'name': 'Alice', 'rank': 1}, {'name': 'Bob', 'rank': 2}, {'name': 'Charlie', 'rank': 3}]
Page 2: [{'name': 'Diana', 'rank': 4}, {'name': 'Eve', 'rank': 5}, {'name': 'Frank', 'rank': 6}]
Page 3: [{'name': 'Grace', 'rank': 7}, {'name': 'Hank', 'rank': 8}, {'name': 'Iris', 'rank': 9}]

Mise en garde sur les performances de skip()

skip() fonctionne en parcourant et en écartant les n premiers documents avant de renvoyer les résultats. Sur des collections très volumineuses (des millions de documents), une grande valeur skip() est lente car MongoDB doit quand même lire tous les documents ignorés. Pour une pagination à fort trafic sur de grands jeux de données, utilisez plutôt une requête par plage sur un champ indexé :

# Instead of skip(1000).limit(10), remember the last _id from the previous page
# and filter: {"_id": {"$gt": last_seen_id}}
# This is O(log n) with an index rather than O(n)

Combiner limit() avec une requête de filtre

limit() fonctionne avec n'importe quelle requête find(), pas seulement avec find({}) sans paramètre :

import pymongo

client = pymongo.MongoClient("mongodb://localhost:27017/")
col = client["mydatabase"]["customers"]

# Find customers with rank greater than 5, return only the first 3
query = {"rank": {"$gt": 5}}
results = col.find(query, {"_id": 0}).sort("rank", pymongo.ASCENDING).limit(3)

for doc in results:
    print(doc)

Résultat attendu :

{'name': 'Frank', 'rank': 6}
{'name': 'Grace', 'rank': 7}
{'name': 'Hank', 'rank': 8}

Pour en savoir plus sur les opérateurs de filtre ($gt, $lt, $in, etc.), consultez le chapitre MongoDB Query.

Ordre de chaînage des méthodes

PyMongo construit la requête côté serveur, donc l'ordre dans lequel vous chaînez sort(), skip() et limit() en Python ne change pas le résultat — MongoDB les applique toujours dans la séquence : filtre → tri → skip → limit. Les deux instructions suivantes sont équivalentes :

col.find().sort("rank", 1).skip(2).limit(3)
col.find().limit(3).skip(2).sort("rank", 1)  # same result

Les écrire dans l'ordre logique (sort → skip → limit) est une convention qui rend le code plus facile à lire.

Référence rapide

Méthode	Objectif	Exemple
`.limit(n)`	Renvoyer au plus `n` documents	`.find().limit(10)`
`.skip(n)`	Ignorer les `n` premiers documents	`.find().skip(20)`
`.sort(field, dir)`	Trier avant de limiter	`.find().sort("rank", 1).limit(5)`
`.limit(0)`	Pas de limite (renvoie tout)	`.find().limit(0)`

Chapitres associés

MongoDB Find — interroger des documents avec find() et find_one()
MongoDB Query — filtrer avec des opérateurs de comparaison et logiques
MongoDB Sort — ordonner les résultats avec sort()
MongoDB Insert — ajouter des documents à une collection
MongoDB Update — modifier des documents existants