Especifique quais campos retornar

Visão geral

Use uma projeção para controlar quais campos aparecem nos documentos retornados pelas operações de leitura. Muitas solicitações exigem apenas determinados campos, portanto, as projeções podem ajudar a limitar o uso desnecessário da largura de banda da rede. As projeções funcionam de duas formas:

• Inclua campos explicitamente com um valor de 1. Isso tem o efeito colateral de excluir implicitamente todos os campos não especificados.

• Exclua implicitamente campos com valor 0. Isso tem o efeito colateral de incluir implicitamente todos os campos não especificados.

Esses dois métodos de projeção são mutuamente exclusivos: se você incluir campos explicitamente, não poderá excluir campos explicitamente e vice-versa.

const myDB = client.db("myDB");
const myColl = myDB.collection("fruits");
await myColl.insertMany([
  { "_id": 1, "name": "apples", "qty": 5, "rating": 3 },
  { "_id": 2, "name": "bananas", "qty": 7, "rating": 1 },
  { "_id": 3, "name": "oranges", "qty": 6, "rating": 2 },
  { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
]);

Campo Único

Na query a seguir, passe a projeção para retornar somente o campo name de cada documento:

// return only* the name field
const projection = { name: 1 };
const cursor = myColl.find().project(projection);
for await (const doc of cursor) {
  console.dir(doc);
}

O documento de projeção especifica um valor de 1 para name. Isso instrui a operação a incluir o campo name de cada documento retornado nos resultados e excluir os campos qty e rating. Passar essa projeção para find() com um query vazio e nenhum documento de classificação produz os seguintes resultados:

{ "_id": 1, "name": "apples" }
{ "_id": 2, "name": "bananas" }
{ "_id": 3, "name": "oranges" }
{ "_id": 4, "name": "avocados" }

Embora essa projeção incluísse explicitamente apenas o campo name, a query também retornou o campo _id.

O campo _id é um caso especial porque é sempre incluído em cada consulta, a menos que explicitamente especificado de outra forma. Isso ocorre porque _id é um identificador exclusivo para cada documento, uma propriedade que geralmente é usada ao criar consultas. Os dados de coleta movies demonstram por que essa propriedade é necessária: dois ou mais filmes podem ter o mesmo título, como remakes de filmes. Por isso, você precisa de um valor de _id exclusivo para fazer referência confiável a um filme específico. _id é a única exceção ao comportamento mutuamente exclusivo de incluir-excluir em projeções: você pode excluir explicitamente _id mesmo ao incluir explicitamente outros campos se não quiser que _id esteja presente nos documentos retornados.

// return only the name field
const projection = { _id: 0, name: 1 };
const cursor = myColl.find().project(projection);
for await (const doc of cursor) {
  console.dir(doc);
}

O documento de projeção especifica um valor de 1 para name e 0 para _id. Isto instrui a operação a incluir o campo name de cada documento retornado nos resultados e exclui os campos _id, qty e rating. Passar essa projeção para find() com um documento de query vazio e nenhum documento de classificação produz os seguintes resultados:

{ "name": "apples" }
{ "name": "bananas" }
{ "name": "oranges" }
{ "name": "avocados" }

Vários campos

Você também pode especificar vários campos para incluir em sua projeção. Observação: a ordem em que você especifica os campos na projeção não altera a ordem em que eles são retornados.

const projection = { _id: 0, rating: 1, name: 1 };
const cursor = myColl.find().project(projection);
for await (const doc of cursor) {
  console.dir(doc);
}

Este exemplo que identifica dois campos a serem incluídos na projeção gera os seguintes resultados:

  { "name": "apples", "rating": 3 }
  { "name": "bananas", "rating": 1 }
  { "name": "oranges", "rating": 2 }
  { "name": "avocados", "rating": 5 }

Para obter mais exemplos de projeção, consulte a página Manual do MongoDB em Campos de projeto para retorno da query.