Limitare i risultati di query MongoDB in Python con PyMongo

Il metodo limit() in PyMongo consente di limitare il numero di documenti restituiti da una query. Questa pagina spiega cosa fa limit(), quando usarlo, come combinarlo con skip() per la paginazione e come concatenarlo con sort() per ottenere set di risultati ordinati e delimitati.

Prerequisiti

È necessario avere PyMongo installato e un'istanza MongoDB in esecuzione. Installa il driver con:

pip install pymongo

Quindi connettiti al tuo database:

import pymongo

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

Se sei nuovo alla connessione e all'inserimento di documenti, consulta prima i capitoli MongoDB Get Started e MongoDB Insert.

Cosa fa limit()

Chiamare .limit(n) su un cursore indica a MongoDB di restituire al massimo n documenti. Senza di esso, find() restituisce tutti i documenti corrispondenti — il che può risultare costoso su collezioni di grandi dimensioni.

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

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

Passare 0 a limit() viene trattato come non averlo chiamato affatto: MongoDB restituisce tutti i documenti corrispondenti.

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

Esempio di base

Lo script seguente inserisce dieci documenti cliente di esempio e poi recupera solo i primi tre:

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)

Output atteso:

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

Il secondo argomento di find() è una proiezione — {"_id": 0} sopprime il campo _id per rendere l'output più leggibile.

Combinare limit() con sort()

limit() è più utile quando abbinato a sort(). Senza ordinamento, MongoDB restituisce i documenti in ordine naturale (ordine di inserimento su una collezione nuova, ma non garantito dopo aggiornamenti o cancellazioni). Ordinare prima assicura che i risultati "top N" siano significativi.

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)

Output atteso:

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}

Consulta il capitolo MongoDB Sort per una guida completa alle opzioni di ordinamento.

Paginazione con skip() e limit()

skip(n) indica a MongoDB di scartare i primi n documenti prima di applicare limit(). Insieme implementano la paginazione basata su pagine:

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)

Ecco un helper riutilizzabile che recupera una pagina alla volta:

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)

Output atteso:

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

Avvertenza sulle prestazioni di skip()

skip() funziona scansionando e scartando i primi n documenti prima di restituire i risultati. Su collezioni molto grandi (milioni di documenti), un valore elevato di skip() è lento perché MongoDB deve comunque leggere tutti i documenti saltati. Per la paginazione ad alto traffico su grandi set di dati, usa invece una query di intervallo su un campo indicizzato:

# 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)

Combinare limit() con una query di filtro

limit() funziona con qualsiasi query find(), non solo con find({}) semplice:

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)

Output atteso:

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

Per ulteriori informazioni sugli operatori di filtro ($gt, $lt, $in, ecc.), consulta il capitolo MongoDB Query.

Ordine di concatenazione dei metodi

PyMongo costruisce la query lato server, quindi l'ordine in cui si concatenano sort(), skip() e limit() in Python non cambia il risultato — MongoDB li applica sempre nella sequenza: filtro → ordinamento → skip → limit. Le due istruzioni seguenti sono equivalenti:

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

Scriverli nell'ordine logico (sort → skip → limit) è una convenzione che rende il codice più leggibile.

Riferimento rapido

Metodo	Scopo	Esempio
`.limit(n)`	Restituisce al massimo `n` documenti	`.find().limit(10)`
`.skip(n)`	Salta i primi `n` documenti	`.find().skip(20)`
`.sort(field, dir)`	Ordina prima di limitare	`.find().sort("rank", 1).limit(5)`
`.limit(0)`	Nessun limite (restituisce tutti)	`.find().limit(0)`

Capitoli correlati

MongoDB Find — interrogare documenti con find() e find_one()
MongoDB Query — filtrare con operatori di confronto e logici
MongoDB Sort — ordinare i risultati con sort()
MongoDB Insert — aggiungere documenti a una collezione
MongoDB Update — modificare documenti esistenti