$sort, $limit e $skip no pipeline

Três estágios do pipeline de agregação controlam a ordem e o volume dos resultados: $sort ordena os documentos por um ou mais campos, $limit mantém apenas os primeiros N documentos e $skip descarta os primeiros N documentos. Juntos, eles implementam ordenação e paginação. Entender onde colocá-los no pipeline tem um impacto significativo no desempenho.

O estágio $sort ordena os documentos pelos valores de um ou mais campos. Use 1 para ordem crescente e -1 para ordem decrescente. Quando vários campos são especificados, os documentos são ordenados primeiro pelo primeiro campo, depois pelo segundo campo entre os que estão empatados, e assim por diante — exatamente como na ordenação por várias chaves do SQL ou em find().sort() do MongoDB.

Quando $sort é o primeiro estágio do pipeline (ou vem depois de um $match que usa um índice), o MongoDB pode usar um índice para realizar a ordenação, evitando completamente uma ordenação em memória. Quando $sort aparece depois de estágios que produzem novos campos, como $group ou $project, nenhum índice está disponível e o MongoDB realiza uma ordenação em memória. Ordenações em memória grandes (>100 MB) exigem allowDiskUse: true.

$limit encaminha apenas os primeiros N documentos e descarta os demais. É simples: passe um número inteiro que especifique o número máximo de documentos permitidos. Colocar $limit antes de estágios dispendiosos, como $lookup, reduz significativamente o número de junções ou consultas realizadas. Pergunte sempre: “Posso limitar antecipadamente?”

$skip descarta os primeiros N documentos do fluxo. Ele é o equivalente, na agregação, à paginação por deslocamento: a página 2 começa com skip 10 (considerando um limite de 10 por página). $skip deve sempre vir depois de $sort para produzir resultados consistentes — ignorar documentos não ordenados gera páginas imprevisíveis. Assim como OFFSET no SQL, $skip é lento com deslocamentos grandes, pois o MongoDB ainda precisa processar todos os documentos ignorados.

O otimizador de agregação do MongoDB detecta quando um estágio $sort é seguido imediatamente por um estágio $limit e combina os dois em uma ordenação dos N primeiros. Em vez de ordenar todos os documentos e depois descartar a maioria, o MongoDB mantém apenas os N principais candidatos em uma fila de prioridade durante a ordenação, usando memória O(N) em vez de memória O(total). Essa otimização é automática: basta escrever $sort seguido de $limit.

O otimizador de agregação também move automaticamente um estágio $match para uma posição anterior no pipeline quando isso é seguro. Por exemplo, se $sort aparecer antes de $match em um campo que $sort não calculou, o otimizador move $match para antes de $sort, reduzindo o número de documentos que precisam ser ordenados. Você pode observar as alterações do otimizador na saída de explain().

Um endpoint de API realista que lista produtos com filtros, ordenação e paginação combina $match, $sort, $skip e $limit na ordem correta. O padrão é sempre: filtrar → ordenar → ignorar → limitar. Essa ordem garante que o MongoDB use índices tanto para a filtragem quanto, quando possível, para a ordenação antes de descartar documentos desnecessários.

O problema fundamental de $skip é que o MongoDB ainda precisa processar e descartar todos os documentos ignorados. Na página 1000, com 20 itens por página, o MongoDB descarta 19.980 documentos antes de retornar 20. Isso fica progressivamente mais lento em páginas mais profundas. Para APIs públicas de pesquisa ou feed, nas quais os usuários raramente vão além da página 5 ou 10, a paginação por deslocamento é adequada. Para paginação profunda de alta frequência, é necessário usar paginação por conjunto de chaves.

Um $sort em memória no pipeline de agregação é limitado, por padrão, a 100 MB. Se a ordenação exceder esse limite, o pipeline falhará com um erro QueryExceededMemoryLimitNoDiskUseAllowed. Passe { allowDiskUse: true } como segundo argumento de aggregate() para permitir a transferência de dados excedentes para o disco. Como alternativa, aplique um $match antecipado ou use um índice de suporte para reduzir o tamanho da entrada da ordenação.

Um padrão comum de API é retornar os resultados paginados e a contagem total em uma única ida e volta ao banco de dados. Use $facet para dividir o pipeline em dois ramos paralelos: um para os resultados de $skip/$limit e outro para $count. Isso evita duas chamadas de agregação separadas e é mais eficiente do que contar todos os documentos separadamente.

Nesta lição, você aprendeu que: $sort ordena os documentos e se beneficia do uso de índices quando colocado no início; $limit mantém os primeiros N documentos e se combina com $sort em uma ordenação eficiente dos N primeiros; e $skip implementa a paginação por deslocamento, mas perde desempenho em deslocamentos profundos. A seguir, exploraremos estágios avançados de agregação, incluindo $lookup para unir coleções.