投影构建器

本页内容

概述

示例文档和示例
投影操作
包含
排除
组合投影
排除_id
投影数组元素匹配
投影数组切片
投影文本评分

概述

在本指南中，您可以学习如何使用构建器在MongoDB Kotlin驱动程序中指定投影。

MongoDB支持字段投影，在查询结果返回时指定包含和排除哪些字段。MongoDB中的投影遵循一些基本规则

的_id字段总是包含，除非明确排除
指定一个字段以包含会隐式排除所有其他字段，除了 _id字段
指定一个字段以排除会移除查询结果中的该字段

有关投影机制更多信息的详细信息，请参阅MongoDB服务器文档中的从查询结果中投影字段指南。

Projections类提供了所有MongoDB投影运算符的静态工厂方法。每个方法都返回一个BSON类型的实例，您可以将其传递给任何期望投影的方法。

提示

为了简洁，您可以选择导入Projections类的

import com.mongodb.client.model.Projections.*

示例文档和示例

以下部分展示了在名为 projection_builders 的示例集合上运行的查询和投影操作的示例。每个部分使用名为 collection 的变量来引用 projection_builders 集合的 MongoCollection 实例。

该集合包含以下文档，代表2018年和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 }
  ]
}

以下数据类用于表示集合中的文档

data class YearlyTemperature(
    @BsonId val id: ObjectId,
    val year: Int,
    val type: String,
    val temperatures: List<MonthlyTemperature>
) {
    data class MonthlyTemperature(
        val month: String,
        val avg: Double
    )
}

投影操作

以下部分包含有关可用投影操作以及如何使用 Projections 类构建它们的详细信息。

包含

使用 include() 方法来指定包含一个或多个字段。

以下示例包含 year 字段和隐式包含的 _id 字段

data class Results(@BsonId 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)

以下示例包括year和type字段，以及隐式包含的_id字段。

data class Results(@BsonId 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)

排除

使用exclude()方法指定排除一个或多个字段。

以下示例排除了temperatures字段

data class Results(@BsonId 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)

以下示例排除了temperatures和type字段

data class Results(@BsonId 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)

组合投影

使用fields()方法组合多个投影。

以下示例包括year和type字段，并排除了_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)

`_id`的排除

使用便利方法excludeId()指定排除_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)])

投影数组元素匹配

使用 elemMatch(String, Bson) 方法变体来指定一个数组投影，该投影将包含匹配提供的查询过滤器的数组的第一元素。此过滤在检索到所有匹配查询过滤器（如果提供）的文档之后发生。

注意

仅包含与指定查询过滤器匹配的第一个元素，不管可能有多少匹配项。

以下示例投影了 temperatures 数组中平均数字段大于 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)])

当你在操作的部分指定匹配条件时，使用 elemMatch(String) 方法变体来指定一个位置投影，以包含数组的第一元素。只有匹配查询过滤器的文档将被检索。

重要

在 MongoDB 4.4 及更早版本中，指定的数组字段必须出现在查询过滤器中。从 MongoDB 4.4 开始，你可以对未出现在查询过滤器中的数组字段使用位置投影。

以下示例投影了 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)])

投影数组切片

使用 slice() 方法来投影数组的切片。

以下示例展示了如何投影 temperatures 数组的第一个 6 个元素

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)])

以下示例跳过 temperatures 数组的第一个 6 个元素，并投影接下来的 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)])

投影文本分数

使用 metaTextScore() 方法来指定文本查询的分数投影

以下示例将文本分数投影为 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)

索引

排序

概述

提示