Especifique documentos a serem devolvidos

Visão geral

Neste guia, você pode aprender como especificar quais documentos retornar de uma operação de leitura usando os seguintes métodos:

• sort(): especifica a ordem de classificação para os documentos devolvidos.

• limit(): especifica o número máximo de documentos para retornar de uma query.

• skip(): especifica o número de documentos a ignorar antes de retornar os resultados da query.

const myDB = client.db("myDB");
const myColl = myDB.collection("books");
await myColl.insertMany([
  { "_id": 1, "name": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 },
  { "_id": 2, "name": "Les Misérables", "author": "Hugo", "length": 1462 },
  { "_id": 3, "name": "Atlas Shrugged", "author": "Rand", "length": 1088 },
  { "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 },
  { "_id": 5, "name": "Cryptonomicon", "author": "Stephenson", "length": 918 },
  { "_id": 6, "name": "A Dance With Dragons", "author": "Martin", "length": 1104 },
]);

Sort

Use o método sort() para alterar a ordem em que as operações de leitura retornam documentos. Este método diz ao MongoDB para ordenar os documentos retornados pelos valores de um ou mais campos em uma determinada direção. Para classificar documentos devolvidos por um campo em ordem crescente (primeira menor), use um valor de 1. Para classificar em ordem decrescente (o maior primeiro), use -1. Se você não especificar uma classificação, o MongoDB não garante a ordem dos resultados da query.

O exemplo a seguir passa o documento de classificação para uma operação de leitura para garantir que a operação retorne livros com comprimentos mais longos antes de livros com comprimentos mais curtos:

// define an empty query document
const query = {};
// sort in descending (-1) order by length
const sortFields = { length: -1 };
const cursor = myColl.find(query).sort(sortFields);
for await (const doc of cursor) {
  console.dir(doc);
}

Neste caso, o número -1 informa a operação de leitura para classificar os livros em ordem decrescente por comprimento. O find() retorna os seguintes documentos quando esta classificação é usada com uma query vazia:

{ "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 }
{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }
{ "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 }
{ "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 }
{ "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 }
{ "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }

Às vezes, a ordem de dois ou mais documentos é ambígua usando uma classificação especificada. No exemplo anterior , os documentos que têm title valores de "A Dance with Dragons" e "Infinite Jest" têm um length de 1104, portanto, a ordem em que são retornados não é garantida. Para resolver empates em seus resultados classificados de forma repetível, adicione mais campos ao documento de classificação:

// define an empty query document
const query = {};
// sort in ascending (1) order by length
const sortFields = { length: 1, author: 1 };
const cursor = myColl.find(query).sort(sortFields);
for await (const doc of cursor) {
  console.dir(doc);
}

Com a adição do campo author ao documento de classificação, a operação de leitura classifica os documentos correspondentes primeiro por length e depois, se houver empate, por author. Os campos de documento correspondentes são comparados na mesma ordem em que os campos são especificados no documento de classificação. find() retorna a seguinte ordem de documentos quando essa classificação é usada nos documentos correspondentes à query:

{ "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }
{ "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 }
{ "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 }
{ "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 }
{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }
{ "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 }

Limite

Use o método limit() para limitar o número de documentos que podem ser devolvidos de uma operação de leitura. Este método especifica o número máximo de documentos que a operação pode retornar, mas a operação pode retornar um número menor de documentos se não houver documentos suficientes presentes para atingir o limite. Se limit() for usado com o método skip(), o salto se aplica primeiro e o limite só se aplica aos documentos que sobraram após o salto.

Este exemplo executa as seguintes ações:

• Usa um filtro de query vazio para corresponder a todos os documentos na coleção

• Chama o método sort() para aplicar uma classificação decrescente no campo length aos resultados

• Chama o método limit() para retornar somente os primeiros 3 resultados

// define an empty query document
const query = {};
// sort in descending (-1) order by length
const sortFields = { length: -1 };
const limitNum = 3;
const cursor = myColl.find(query).sort(sortFields).limit(limitNum);
for await (const doc of cursor) {
  console.dir(doc);
}

O exemplo de código acima gera os três documentos a seguir, classificados por tamanho:

{ "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 }
{ "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 }
{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }

myColl.find(query).sort({ length: -1 }).limit(3);
myColl.find(query).limit(3).sort({ length: -1 });

Ignorar

Use o método skip() para omitir documentos do início dos resultados da operação de leitura. Você pode combinar o skip() com sort() para omitir os resultados superiores (para ordem decrescente) ou inferiores (para ordem crescente) para uma consulta fornecida. Uma vez que a ordem dos documentos devolvidos não é garantida na ausência de uma classificação, usar skip() sem usar sort() omite documentos arbitrários.

Se o valor de skip() exceder o número de documentos correspondentes para uma query, essa query não retornará nenhum documento.

Este exemplo faz query na collection em busca dos livros com o quinto e o sexto maiores comprimentos executando as seguintes ações:

• Usa um filtro de query vazio para corresponder a todos os documentos na coleção

• Chama o método sort() para aplicar uma classificação decrescente ao campo length , que retorna livros mais longos antes de livros mais curtos

• Chama o método skip() para omitir os primeiros quatro documentos correspondentes do resultado

// define an empty query document
const query = {};
const sortFields = { length: -1 };
const skipNum = 4;
const cursor = myColl.find(query).sort(sortFields).skip(skipNum);
for await (const doc of cursor) {
  console.dir(doc);
}

Como a query ignora os primeiros quatro documentos correspondentes, o trecho de código anterior imprime o quinto e o sexto documentos de maior comprimento:

{ "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 }
{ "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }

Combinar Limite, Classificar e Ignorar

Você pode combinar as opções limit, sort e skip em uma única operação. Isso permite que você defina um número máximo de documentos classificados para retornar, ignorando um número específico de documentos antes de retornar.

O exemplo a seguir retorna documentos com o valor length de "1104". Os resultados são classificados em ordem alfabética, ignorando o primeiro documento e incluindo apenas o primeiro resultado:

const query = {length: "1104"};
const cursor = myColl.find(query).sort({ title: 1 }).skip(1).limit(1);
for await (const doc of cursor) {
   console.dir(doc);
}

{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }

Informações adicionais

Para obter mais informações sobre como especificar uma query, consulte Operações de query.

Para obter mais informações sobre como recuperar documentos, consulte Localizar documentos.