Especifique quais campos retornar

Visão geral

Neste guia, você verá como controlar quais campos aparecem em documentos gerados de operações de leitura com o driver Java do MongoDB.

Muitas solicitações de leitura exigem apenas um subconjunto de campos em um documento. Por exemplo, ao fazer login de um usuário, você pode precisar apenas do nome de usuário e não de todas as informações do perfil. Por padrão, as queries no MongoDB retornam todos os campos em documentos correspondentes. Você pode usar uma projeção para retornar apenas os dados necessários.

Uma projeção é um documento que indica ao MongoDB quais campos de um documento devem ser gerados. Use a classeProjeções para construir um documento de projeção.

Comportamento

As projeções funcionam de duas formas:

• Incluir campos de forma explícita. Isso tem o efeito colateral de excluir implicitamente todos os campos não especificados.

• Excluindo campos de forma implícita. Isso tem o efeito colateral de implicitamente, incluindo 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.

Explicação

Considere a seguinte coleção contendo documentos que descrevem variedades de frutas:

{ "_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 },

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

// return all documents with *only* the name field
Bson filter = Filters.empty();
Bson projection = Projections.fields(Projections.include("name"));
collection.find(filter).projection(projection).forEach(doc -> System.out.println(doc));

O documento de projeção especifica que o resultado da operação de leitura deve incluir o campo name de cada documento gerado. Como resultado, esta projeção exclui implicitamente os campos qty e rating. Conectar esta projeção a um find() com um filtro de query vazio gera os seguintes resultados:

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

Apesar do fato de que essa projeção só incluía explicitamente o campo name, a query retornou o campo _id também.

O campo _id é um caso especial: ele é sempre incluído em todos os resultados da query, a menos que explicitamente excluído. Isso porque o campo _id é um identificador exclusivo para cada documento, uma propriedade que pode ser útil ao construir as queries.

Uma coleção movies é um bom exemplo da utilidade dessa propriedade: como as refilmagens e até mesmo os trabalhos separados às vezes reutilizam títulos de filmes, você precisa de um valor _id exclusivo para se referir a qualquer filme específico.

_id é a única exceção ao comportamento mutuamente exclusivo incluir-excluir comportamento em projeções: você pode excluir explicitamente o _id campo mesmo ao incluir explicitamente outros campos se não quiser _id que esteja presente nos documentos retornados.

// return all documents with only the name field
Bson filter = Filters.empty();
Bson projection = Projections.fields(Projections.include("name"), Projections.excludeId());
collection.find(filter).projection(projection).forEach(doc -> System.out.println(doc));

O documento de projeção especifica que o resultado da operação de leitura deve incluir o campo name de cada documento retornado e especifica a exclusão do campo _id. Como resultado, esta projeção exclui implicitamente os campos qty e rating. A cadeia desta projeção para find() com um filtro de query vazio gera os seguintes resultados:

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

Você também pode especificar vários campos para incluir em sua projeção.

Bson filter = Filters.empty();
Bson projection = Projections.fields(Projections.include("name", "rating"), Projections.excludeId());
collection.find(filter).projection(projection).forEach(doc -> System.out.println(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 exemplos adicionais de projeção, consulte a página do Manual do MongoDB em Campos do projeto para retornar da query.