Limitar Resultados de Consulta MongoDB em Python com PyMongo

O método limit() no PyMongo permite limitar o número de documentos retornados por uma consulta. Esta página explica o que o limit() faz, quando usá-lo, como combiná-lo com skip() para paginação e como encadeá-lo com sort() para conjuntos de resultados ordenados e limitados.

Pré-requisitos

Você precisa do PyMongo instalado e de uma instância do MongoDB em execução. Instale o driver com:

pip install pymongo

Em seguida, conecte-se ao seu banco de dados:

import pymongo

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

Se você é novo na conexão e inserção de documentos, consulte primeiro os capítulos MongoDB Get Started e MongoDB Insert.

O que o limit() Faz

Chamar .limit(n) em um cursor instrui o MongoDB a retornar no máximo n documentos. Sem ele, find() retorna todos os documentos correspondentes — o que pode ser custoso em coleções 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)

Passar 0 para limit() é tratado da mesma forma que não chamá-lo: o MongoDB retorna todos os documentos correspondentes.

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

Exemplo Básico

O script a seguir insere dez documentos de cliente de exemplo e depois recupera apenas os três primeiros:

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)

Saída esperada:

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

O segundo argumento para find() é uma projeção — {"_id": 0} suprime o campo _id para que a saída seja mais fácil de ler.

Combinando limit() com sort()

limit() é mais útil quando combinado com sort(). Sem ordenação, o MongoDB retorna documentos na ordem natural (ordem de inserção em uma coleção nova, mas não garantida após atualizações ou exclusões). Ordenar primeiro garante que os resultados dos "N melhores" sejam 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)

Saída 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}

Consulte o capítulo MongoDB Sort para um guia completo sobre opções de ordenação.

Paginação com skip() e limit()

skip(n) instrui o MongoDB a descartar os primeiros n documentos antes de aplicar limit(). Juntos, eles implementam paginação baseada em 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)

Aqui está um helper reutilizável que busca uma página por 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)

Saída 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}]

Ressalva de desempenho do skip()

skip() funciona varrendo e descartando os primeiros n documentos antes de retornar os resultados. Em coleções muito grandes (milhões de documentos), um valor grande de skip() é lento porque o MongoDB ainda precisa ler todos os documentos ignorados. Para paginação de alto tráfego em grandes conjuntos de dados, use uma consulta de intervalo em um campo indexado:

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

Combinando limit() com uma Consulta de Filtro

limit() funciona com qualquer consulta find(), não apenas com find({}) simples:

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)

Saída esperada:

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

Para mais informações sobre operadores de filtro ($gt, $lt, $in, etc.), consulte o capítulo MongoDB Query.

Ordem de Encadeamento de Métodos

O PyMongo constrói a consulta no lado do servidor, portanto a ordem em que você encadeia sort(), skip() e limit() em Python não altera o resultado — o MongoDB sempre os aplica na sequência: filtro → ordenação → skip → limit. As duas instruções a seguir são equivalentes:

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

Escrevê-los na ordem lógica (sort → skip → limit) é uma convenção que torna o código mais fácil de ler.

Referência Rápida

Método	Propósito	Exemplo
`.limit(n)`	Retornar no máximo `n` documentos	`.find().limit(10)`
`.skip(n)`	Ignorar os primeiros `n` documentos	`.find().skip(20)`
`.sort(field, dir)`	Ordenar antes de limitar	`.find().sort("rank", 1).limit(5)`
`.limit(0)`	Sem limite (retorna todos)	`.find().limit(0)`

Capítulos Relacionados

MongoDB Find — consulta de documentos com find() e find_one()
MongoDB Query — filtragem com operadores de comparação e lógicos
MongoDB Sort — ordenação de resultados com sort()
MongoDB Insert — adição de documentos a uma coleção
MongoDB Update — modificação de documentos existentes