Menu Docs
Página inicial do Docs
/ / /
Kotlin Coroutine
/ / /

Especifique quais campos retornar

Nesta página

  • Visão geral
  • Comportamento
  • Explicação

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

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 .

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.

Importante

O campo _id não está sujeito a estes mecanismos. Você deve excluir explicitamente o campo _id se não desejar que ele seja gerado. Você pode excluir o campo _id mesmo se tiver especificado determinados campos para inclusã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 },

Esses dados são modelados usando a seguinte classe de dados Kotlin:

data class Fruit(
@BsonId val id: Int,
val name: String,
val qty: Int,
val rating: Int
)

Na query a seguir, passe a projeção para retornar o campo name de cada documento. Os resultados são modelados usando a classe de dados Kotlin FruitName :

data class FruitName(
@BsonId val id: Int? = null,
val name: String
)
// Return all documents with only the name field
val filter = Filters.empty()
val projection = Projections.fields(
Projections.include(FruitName::name.name)
)
val flowResults = collection.find<FruitName>(filter).projection(projection)
flowResults.collect { println(it)}
FruitName(id=1, name=apples),
FruitName(id=2, name=bananas),
FruitName(id=3, name=oranges),
FruitName(id=4, name=avocados)

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 . A cadeia desta projeção para find() com um filtro de query vazio gera os resultados acima.

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

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.

_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.

data class FruitName(
@BsonId val id: Int? = null,
val name: String
)
// Return all documents with *only* the name field
// excludes the id
val filter = Filters.empty()
val projection = Projections.fields(
Projections.include(FruitName::name.name),
Projections.excludeId()
)
val flowResults = collection.find<FruitName>(filter).projection(projection)
flowResults.collect { println(it)}
FruitName(name=apples),
FruitName(name=bananas),
FruitName(name=oranges),
FruitName(name=avocados)

The projection document specifies that the read operation result should include the name field of each returned document, and specifies to exclude the _id field. 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 resultados acima.

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

Dica

A ordem na qual você especifica os campos na projeção não altera a ordem na qual eles são retornados.

Este exemplo que identifica dois campos a serem incluídos na projeção gera os seguintes resultados usando a classe de dados Kotlin FruitRating :

data class FruitRating(
val name: String,
val rating: Int
)
val filter = Filters.empty()
val projection = Projections.fields(
Projections.include(FruitRating::name.name, FruitRating::rating.name),
Projections.excludeId()
)
val flowResults = collection.find<FruitRating>(filter).projection(projection)
flowResults.collect { println(it)}
FruitRating(name=apples, rating=3),
FruitRating(name=bananas, rating=1),
FruitRating(name=oranges, rating=2),
FruitRating(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.

Voltar

Limite o número de resultados retornados