Limitar resultados de consultas MongoDB en Python con PyMongo

El método limit() en PyMongo te permite acotar el número de documentos devueltos por una consulta. Esta página explica qué hace limit(), cuándo usarlo, cómo combinarlo con skip() para paginación y cómo encadenarlo con sort() para conjuntos de resultados ordenados y acotados.

Requisitos previos

Necesitas tener PyMongo instalado y una instancia de MongoDB en ejecución. Instala el driver con:

pip install pymongo

Luego conéctate a tu base de datos:

import pymongo

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

Si eres nuevo en la conexión e inserción de documentos, consulta primero los capítulos MongoDB Get Started y MongoDB Insert.

Qué hace limit()

Llamar a .limit(n) sobre un cursor le indica a MongoDB que devuelva como máximo n documentos. Sin él, find() devuelve todos los documentos que coincidan, lo que puede ser costoso en colecciones grandes.

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

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

Pasar 0 a limit() se trata igual que no llamarlo en absoluto: MongoDB devuelve todos los documentos que coincidan.

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

Ejemplo básico

El siguiente script inserta diez documentos de clientes de muestra y luego recupera solo los tres primeros:

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)

Salida esperada:

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

El segundo argumento de find() es una proyección — {"_id": 0} suprime el campo _id para que la salida sea más fácil de leer.

Combinar limit() con sort()

limit() es más útil cuando se combina con sort(). Sin ordenamiento, MongoDB devuelve los documentos en orden natural (orden de inserción en una colección nueva, pero no garantizado tras actualizaciones o eliminaciones). Ordenar primero garantiza que los resultados del "top N" sean significativos.

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)

Salida esperada:

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 el capítulo MongoDB Sort para una guía completa de las opciones de ordenamiento.

Paginación con skip() y limit()

skip(n) le indica a MongoDB que descarte los primeros n documentos antes de aplicar limit(). Juntos implementan paginación basada en páginas:

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)

Aquí hay un helper reutilizable que obtiene una página a la vez:

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)

Salida esperada:

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

Advertencia de rendimiento con skip()

skip() funciona escaneando y descartando los primeros n documentos antes de devolver resultados. En colecciones muy grandes (millones de documentos), un valor grande de skip() es lento porque MongoDB aún debe leer todos los documentos omitidos. Para paginación de alto tráfico sobre grandes conjuntos de datos, usa una consulta de rango sobre un campo indexado en su lugar:

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

Combinar limit() con una consulta de filtro

limit() funciona con cualquier consulta find(), no solo con find({}) simple:

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)

Salida esperada:

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

Para más información sobre los operadores de filtro ($gt, $lt, $in, etc.), consulta el capítulo MongoDB Query.

Orden de encadenamiento de métodos

PyMongo construye la consulta en el lado del servidor, por lo que el orden en que encadenas sort(), skip() y limit() en Python no cambia el resultado — MongoDB siempre los aplica en la secuencia: filtro → ordenamiento → skip → limit. Las dos siguientes declaraciones son equivalentes:

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

Escribirlos en el orden lógico (sort → skip → limit) es una convención que facilita la lectura del código.

Referencia rápida

Método	Propósito	Ejemplo
`.limit(n)`	Devolver como máximo `n` documentos	`.find().limit(10)`
`.skip(n)`	Saltar los primeros `n` documentos	`.find().skip(20)`
`.sort(field, dir)`	Ordenar antes de limitar	`.find().sort("rank", 1).limit(5)`
`.limit(0)`	Sin límite (devuelve todos)	`.find().limit(0)`

Capítulos relacionados

MongoDB Find — consulta de documentos con find() y find_one()
MongoDB Query — filtrado con operadores de comparación y lógicos
MongoDB Sort — ordenamiento de resultados con sort()
MongoDB Insert — agregar documentos a una colección
MongoDB Update — modificar documentos existentes