Construtores de projeções
Nesta página
Visão geral
Neste guia, você pode aprender como especificar projeções utilizandoconstrutores do no driver MongoDB Kotlin .
O MongoDB oferece projeção de campo, especificando quais campos incluir e excluir ao gerar resultados de uma query. A projeção no MongoDB segue algumas regras básicas:
O campo
_id
está sempre incluído, a menos que esteja explicitamente excluídoA especificação de um campo para inclusão exclui implicitamente todos os outros campos exceto o campo
_id
Especificar um campo para exclusão remove apenas esse campo em um resultado de consulta
Encontre mais informações sobre mecânica de projeção no guia Campos de projeto para retornar da query na documentação do MongoDB Server .
A classe Projections
fornece métodos de fábrica estáticos para todos os operadores de projeção do MongoDB. Cada método retorna uma instância do tipo BSON que você pode passar para qualquer método que espera uma projeção.
Dica
Por questões de brevidade, você pode optar por importar os métodos das Projeções classe:
import com.mongodb.client.model.Projections.*
Amostras de documentos e exemplos
As seguintes seções apresentam exemplos que executam operações de query e projeção em uma collection de amostra denominada projection_builders
. Cada seção usa uma variável chamada collection
para fazer referência à instância MongoCollection
da coleção projection_builders
.
O acervo contém os seguintes documentos, representando as temperaturas médias mensais em Celsius para os anos de 2018 e 2019:
{ "year" : 2018, "type" : "even number but not a leap year", "temperatures" : [ { "month" : "January", "avg" : 9.765 }, { "month" : "February", "avg" : 9.675 }, { "month" : "March", "avg" : 10.004 }, { "month" : "April", "avg" : 9.983 }, { "month" : "May", "avg" : 9.747 }, { "month" : "June", "avg" : 9.65 }, { "month" : "July", "avg" : 9.786 }, { "month" : "August", "avg" : 9.617 }, { "month" : "September", "avg" : 9.51 }, { "month" : "October", "avg" : 10.042 }, { "month" : "November", "avg" : 9.452 }, { "month" : "December", "avg" : 9.86 } ] }, { "year" : 2019, "type" : "odd number, can't be a leap year", "temperatures" : [ { "month" : "January", "avg" : 10.023 }, { "month" : "February", "avg" : 9.808 }, { "month" : "March", "avg" : 10.43 }, { "month" : "April", "avg" : 10.175 }, { "month" : "May", "avg" : 9.648 }, { "month" : "June", "avg" : 9.686 }, { "month" : "July", "avg" : 9.794 }, { "month" : "August", "avg" : 9.741 }, { "month" : "September", "avg" : 9.84 }, { "month" : "October", "avg" : 10.15 }, { "month" : "November", "avg" : 9.84 }, { "month" : "December", "avg" : 10.366 } ] }
A seguinte classe de dados é usada para representar o documento na collection:
data class YearlyTemperature( val id: ObjectId, val year: Int, val type: String, val temperatures: List<MonthlyTemperature> ) { data class MonthlyTemperature( val month: String, val avg: Double ) }
Operações de Projeção
As seções seguintes contêm informações sobre as operações de projeção disponíveis e como construí-las utilizando a classe Projections
.
Inclusão
Utilize o método include()
para especificar a inclusão de um ou mais campos.
O exemplo seguinte inclui o campo year
e implicitamente o campo _id
:
data class Results( val id: ObjectId, val year: Int) val filter = Filters.empty() val projection = Projections.include(YearlyTemperature::year.name) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(id=6467808db5003e6354a1ee22, year=2018) Results(id=6467808db5003e6354a1ee23, year=2019)
O exemplo seguinte inclui os type
e year
o _id
:
data class Results( val id: ObjectId, val year: Int, val type: String) val filter = Filters.empty() val projection = Projections.include(YearlyTemperature::year.name, YearlyTemperature::type.name) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(id=646780e3311323724f69a907, year=2018, type=even number but not a leap year) Results(id=646780e3311323724f69a908, year=2019, type=odd number, can't be a leap year)
Exclusion
Utilize o método exclude()
para especificar a exclusão de um ou mais campos.
O exemplo seguinte exclui o campo temperatures
:
data class Results( val id: ObjectId, val year: Int, val type: String) val filter = Filters.empty() val projection = Projections.exclude(YearlyTemperature::temperatures.name) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(id=6462976102c85b29a7bfc9d5, year=2018, type=even number but not a leap year) Results(id=6462976102c85b29a7bfc9d6, year=2019, type=odd number, can't be a leap year)
O exemplo seguinte exclui os campos temperatures
e type
:
data class Results( val id: ObjectId, val year: Int) val filter = Filters.empty() val projection = Projections.exclude(YearlyTemperature::temperatures.name, YearlyTemperature::type.name) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(id=64629783d7760d2365215147, year=2018) Results(id=64629783d7760d2365215148, year=2019)
Combinando projeções
Utilize o método fields()
para combinar múltiplas projeções.
O exemplo seguinte inclui os campos year
e type
e exclui o campo _id
:
data class Results(val year: Int, val type: String) val filter = Filters.empty() val projection = Projections.fields( Projections.include(YearlyTemperature::year.name, YearlyTemperature::type.name), Projections.excludeId() ) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(year=2018, type=even number but not a leap year) Results(year=2019, type=odd number, can't be a leap year)
Exclusão de _id
Utilize o método de conveniência excludeId()
para especificar a exclusão do campo _id
:
data class Results(val year: Int, val type: String, val temperatures: List<YearlyTemperature.MonthlyTemperature>) val filter = Filters.empty() val projection = Projections.excludeId() val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(year=2018, type=even number but not a leap year, temperatures=[MonthlyTemperature(month=January, avg=9.765), MonthlyTemperature(month=February, avg=9.675), MonthlyTemperature(month=March, avg=10.004), MonthlyTemperature(month=April, avg=9.983), MonthlyTemperature(month=May, avg=9.747), MonthlyTemperature(month=June, avg=9.65), MonthlyTemperature(month=July, avg=9.786), MonthlyTemperature(month=August, avg=9.617), MonthlyTemperature(month=September, avg=9.51), MonthlyTemperature(month=October, avg=10.042), MonthlyTemperature(month=November, avg=9.452), MonthlyTemperature(month=December, avg=9.86)]) Results(year=2019, type=odd number, can't be a leap year, temperatures=[MonthlyTemperature(month=January, avg=10.023), MonthlyTemperature(month=February, avg=9.808), MonthlyTemperature(month=March, avg=10.43), MonthlyTemperature(month=April, avg=10.175), MonthlyTemperature(month=May, avg=9.648), MonthlyTemperature(month=June, avg=9.686), MonthlyTemperature(month=July, avg=9.794), MonthlyTemperature(month=August, avg=9.741), MonthlyTemperature(month=September, avg=9.84), MonthlyTemperature(month=October, avg=10.15), MonthlyTemperature(month=November, avg=9.84), MonthlyTemperature(month=December, avg=10.366)])
Projetar uma correspondência de elemento da array
Use a variante do método elemMatch(String, Bson)
para especificar uma projeção de array que incluirá o primeiro elemento de uma array que corresponda a um filtro de query fornecido. Essa filtragem ocorre depois que todos os documentos correspondentes ao filtro de query (se fornecidos) são recuperados.
Observação
Somente o primeiro elemento que corresponde ao filtro de consulta especificado será incluído, independentemente de quantas correspondências possam haver.
O exemplo seguinte projeta o primeiro elemento da array temperatures
onde o campo avg
é maior que 10.1
:
data class Results( val year: Int, val temperatures: List<YearlyTemperature.MonthlyTemperature>? ) val filter = Filters.empty() val projection = Projections.fields( Projections.include(YearlyTemperature::year.name), Projections.elemMatch( YearlyTemperature::temperatures.name, Filters.gt(YearlyTemperature.MonthlyTemperature::avg.name, 10.1) ) ) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(year=2018, temperatures=null) Results(year=2019, temperatures=[MonthlyTemperature(month=March, avg=10.43)])
Depois de especificar critérios de correspondência na parte de query da sua operação, use a variante do método elemMatch(String)
para especificar uma projeção posicional para incluir o primeiro elemento de uma array. Somente documentos que correspondam ao filtro de query serão recuperados.
Importante
Na versão 4.4 e anteriores do MongoDB, o campo de array especificado deve aparecer no filtro de query. Iniciando no MongoDB 4.4, você pode usar um projeto posicional em um campo de array que não aparece no filtro de query.
O exemplo abaixo projeta o primeiro elemento da array temperatures
:
data class Results( val year: Int, val temperatures: List<YearlyTemperature.MonthlyTemperature> ) val filter = Filters.gt( "${YearlyTemperature::temperatures.name}.${YearlyTemperature.MonthlyTemperature::avg.name}", 10.1 ) val projection = Projections.fields( Projections.include(YearlyTemperature::year.name), Projections.elemMatch(YearlyTemperature::temperatures.name) ) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(year=2019, temperatures=[MonthlyTemperature(month=March, avg=10.43)])
Projetar uma divisão da array
Use o método slice()
para projetar uma fatia de uma matriz.
O exemplo abaixo projeta os primeiros 6 elementos da array temperatures
:
data class Results(val temperatures: List<YearlyTemperature.MonthlyTemperature>) val filter = Filters.empty() // First half of the year val projection = Projections.fields( Projections.slice(YearlyTemperature::temperatures.name, 6), Projections.excludeId() ) val resultsFlow = collection.find<Results>(filter) .projection(projection) resultsFlow.collect { println(it) }
Results(temperatures=[MonthlyTemperature(month=January, avg=9.765), MonthlyTemperature(month=February, avg=9.675), MonthlyTemperature(month=March, avg=10.004), MonthlyTemperature(month=April, avg=9.983), MonthlyTemperature(month=May, avg=9.747), MonthlyTemperature(month=June, avg=9.65)]) Results(temperatures=[MonthlyTemperature(month=January, avg=10.023), MonthlyTemperature(month=February, avg=9.808), MonthlyTemperature(month=March, avg=10.43), MonthlyTemperature(month=April, avg=10.175), MonthlyTemperature(month=May, avg=9.648), MonthlyTemperature(month=June, avg=9.686)])
O exemplo a seguir pula os primeiros 6 elementos da array temperatures
e projeta os próximos 6:
data class Results(val temperatures: List<YearlyTemperature.MonthlyTemperature>) val filter = Filters.empty() // Second half of the year val projection = Projections.fields( Projections.slice(YearlyTemperature::temperatures.name, 6, 6), Projections.excludeId() ) val resultsFlow = collection.find<Results>(filter) .projection(projection) resultsFlow.collect { println(it) }
Results(temperatures=[MonthlyTemperature(month=July, avg=9.786), MonthlyTemperature(month=August, avg=9.617), MonthlyTemperature(month=September, avg=9.51), MonthlyTemperature(month=October, avg=10.042), MonthlyTemperature(month=November, avg=9.452), MonthlyTemperature(month=December, avg=9.86)]) Results(temperatures=[MonthlyTemperature(month=July, avg=9.794), MonthlyTemperature(month=August, avg=9.741), MonthlyTemperature(month=September, avg=9.84), MonthlyTemperature(month=October, avg=10.15), MonthlyTemperature(month=November, avg=9.84), MonthlyTemperature(month=December, avg=10.366)])
Projetar uma Pontuação de Texto
Utilize o método metaTextScore()
para especificar uma projeção da pontuação de uma query de texto.
O exemplo seguinte projeta a pontuação de texto como o valor do campo score
:
data class Results(val year: Int, val score: Double) val filter = Filters.text("even number") val projection = Projections.fields( Projections.include(YearlyTemperature::year.name), Projections.metaTextScore("score") ) val resultsFlow = collection.find<Results>(filter).projection(projection) resultsFlow.collect { println(it) }
Results(year=2018, score=1.25) Results(year=2019, score=0.625)