聚合表达式操作
Overview
在本指南中，您可了解如何使用 MongoDB Kotlin 驱动程序来构建可在聚合管道中使用的表达式。您可以使用可发现且类型安全的 Java 方法而不是 BSON 文档来执行表达式操作。由于这些方法遵循连贯接口模式，因此可将聚合操作链接在一起来创建更紧凑且可更自然阅读的代码。
本指南中的操作使用 com.mongodb 中的方法。 客户端.model.mql 包。这些方法提供了使用 Query API的一致方式，而 Query API 正是驾驶员与MongoDB 部署交互的机制。要学习；了解有关 Query API的更多信息，请参阅服务器手册文档。
如何使用运算
本指南中的示例假定您的代码中包含以下导入语句：
import com.mongodb.client.model.Aggregates import com.mongodb.client.model.Accumulators import com.mongodb.client.model.Projections import com.mongodb.client.model.Filters import com.mongodb.client.model.mql.MqlValues
要访问表达式中的文档字段，您需要引用聚合管道正在处理的当前文档。使用 current() 方法引用本文档。要访问字段值，您必须使用适当类型的方法，如 getString() 或 getDate()。为字段指定类型时，您要确保驱动程序只提供与该类型兼容的方法。以下代码显示了如何引用名为 name 的字符串字段：
current().getString("name")
要在某一操作中指定值，请将其传递给 of() 构造函数方法以将其转换为有效类型。以下代码展示了如何引用 1.0 值：
of(1.0)
要创建操作，请将方法链接到您的字段或值引用。您可通过链接其他方法来构建更复杂的操作。
以下示例创建一个操作，用于查找新墨西哥州至少看过一次医生的患者。该操作执行以下任务：
使用
gt()方法检查visitDates数组的大小是否大于0使用
eq()方法检查state字段值是否为“新墨西哥州”。
and() 方法将这些操作联系起来，因此管道阶段仅匹配满足这两个条件的文档。
current() .getArray("visitDates") .size() .gt(of(0)) .and(current() .getString("state") .eq(of("New Mexico")))
group() 等聚合阶段直接接受操作，而其他阶段则希望您首先将操作包含在 computed() 或 expr() 等方法中。这些方法采用 TExpression 类型的值，支持您在某些聚合中使用表达式。
要完成聚合管道阶段，请将表达式包含在聚合生成器方法中。以下列表举例说明了如何将表达式包含在常用聚合生成器方法中：
match(expr(<expression>))project(fields(computed("<field name>", <expression>)))group(<expression>)
要学习；了解有关这些方法的详情，请参阅聚合指南。
示例使用 listOf() 方法创建聚合阶段列表。该列表将传递给 MongoCollection 的 aggregate() 方法。
构造器方法
您可以使用这些构造方法来定义 Kotlin 聚合表达式所使用的值。
方法 | 说明 |
|---|---|
引用聚合管道正在处理的当前文档。 | |
将聚合管道正在处理的当前文档引用为映射值。 | |
返回与所提供基元相对应的 MqlValue 类型。 | |
返回与所提供基元数组相对应的 MqlValue 类型数组。 | |
返回条目值。 | |
返回一个空的地图值。 | |
返回 Query API 中存在的空值。 |
重要
当您向这些方法之一提供值时，驱动程序会按字面意思处理。例如，of("$x") 表示字符串值 "$x"，而不是名为 x 的字段。
有关使用这些方法的示例，请参阅操作中的任何部分。
操作
以下部分提供了驱动程序中可用聚合表达式操作的相关信息和示例。这些操作会按用途和功能进行分类。
每个部分均有一个表，其中描述了驱动程序中提供的聚合方法以及查询 API 中相应的表达式运算符。方法名称会链接到 API 文档，而聚合管道运算符名称则会链接到服务器手册文档中的描述和示例。虽然每个方法其实等效于相应的查询 API 表达式，但它们在预期参数与实现方面可能会有所不同。
注意
驱动程序生成的 Query API 表达式可能与每个示例提供的 Query API 表达式有所不同。不过，这两种表达式将产生相同的聚合结果。
重要
该驱动程序不为 Query API 中的所有聚合管道操作符提供方法。如果需要在聚合中使用不受支持的操作，则必须使用 BSON Document 类型定义整个表达式。要了解有关 Document 类型的详情，请参阅文档。
算术运算
您可以使用本部分所述方法对类型为 MqlInteger 或 MqlNumber 的值执行算术操作。
方法 | 聚合管道操作符 |
|---|---|
假设您有特定年份的天气数据，其中包括每天的降水量测量值（以英寸为单位）。您想查找每个月的平均降水量（以毫米为单位）。
multiply() 操作符将 precipitation 字段乘以 25.4，将值转换为毫米。avg() 累加器方法将平均值作为 avgPrecipMM 字段返回。group() 方法按每个文档 date 字段所提供的月份对值进行分组。
以下代码展示此聚合的管道：
val month = current().getDate("date").month(of("UTC")) val precip = current().getInteger("precipitation") listOf( Aggregates.group( month, Accumulators.avg("avgPrecipMM", precip.multiply(25.4)) ))
以下代码在 Query API 中提供等效的聚合管道：
[ { $group: { _id: { $month: "$date" }, avgPrecipMM: { $avg: { $multiply: ["$precipitation", 25.4] } } } } ]
数组运算
您可以使用本节中描述的方法对类型为 MqlArray 的值执行数组操作。
方法 | 聚合管道操作符 |
|---|---|
假设您有一个电影集合，其中每个集合都包含近期放映时间的嵌套文档数组。每个嵌套文档都包含一个数组，表示电影院的座位总数，其中第一个数组条目是高级座位数，第二个条目是普通座位数。每个嵌套文档还包含已购电影票的数量。此集合中的文档可能如下所示：
{ "_id": ..., "movie": "Hamlet", "showtimes": [ { "date": "May 14, 2023, 12:00 PM", "seats": [ 20, 80 ], "ticketsBought": 100 }, { "date": "May 20, 2023, 08:00 PM", "seats": [ 10, 40 ], "ticketsBought": 34 }] }
filter() 方法仅显示与提供的谓词匹配的结果。在这种情况下，谓词使用 sum() 计算座位总数，并将该值与 ticketsBought 和 lt() 的数量进行比较。project() 方法会将这些筛选后的结果存储为一个新的 availableShowtimes 数组。
提示
如果需要将数组的值用作特定类型，则您必须指定以 getArray() 方法检索的数组的类型。
在本示例中，我们指定 seats 数组包含类型为 MqlDocument 的值，以便从每个数组条目提取嵌套字段。
以下代码展示此聚合的管道：
val showtimes = current().getArray<MqlDocument>("showtimes") listOf( Aggregates.project( Projections.fields( Projections.computed("availableShowtimes", showtimes .filter { showtime -> val seats = showtime.getArray<MqlInteger>("seats") val totalSeats = seats.sum { n -> n } val ticketsBought = showtime.getInteger("ticketsBought") val isAvailable = ticketsBought.lt(totalSeats) isAvailable }) )))
注意
为了提高可读性，上例为 totalSeats 和 isAvailable 变量分配了中间值。即使这些变量没有获得中间值，代码仍然会产生相同的结果。
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { availableShowtimes: { $filter: { input: "$showtimes", as: "showtime", cond: { $lt: [ "$$showtime.ticketsBought", { $sum: "$$showtime.seats" } ] } } } } } ]
布尔运算
您可以使用本节中描述的方法对类型为 MqlBoolean 的值执行布尔运算。
假设您想将极低或极高的天气温度读数（华氏度）归类为极端温度。
or() 操作符通过比较 temperature 字段与 lt() 和 gt() 的预定义值，检查温度是否极端。project() 方法将此结果记录在 extremeTemp 字段中。
以下代码展示此聚合的管道：
val temperature = current().getInteger("temperature") listOf( Aggregates.project( Projections.fields( Projections.computed("extremeTemp", temperature .lt(of(10)) .or(temperature.gt(of(95)))) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { extremeTemp: { $or: [ { $lt: ["$temperature", 10] }, { $gt: ["$temperature", 95] } ] } } } ]
比较运算
您可以使用本节中描述的方法对类型为 MqlValue 的值执行比较操作。
提示
cond() 方法类似于 Java 中的三元运算符，而您应将其用于基于布尔值的简单分支。您应将 switchOn() 方法用于更复杂的比较操作，例如对值类型执行模式匹配或对该值执行其他任意检查。
方法 | 聚合管道操作符 |
|---|---|
以下示例展示与 location 字段的值为 "California" 的所有文档相匹配的管道：
val location = current().getString("location") listOf( Aggregates.match( Filters.expr(location.eq(of("California"))) ))
以下代码在 Query API 中提供等效的聚合管道：
[ { $match: { location: { $eq: "California" } } } ]
条件操作
您可以使用本部分所述方法执行条件操作。
方法 | 聚合管道操作符 |
|---|---|
假设您有一个客户集合，其中包含客户的会员信息。最初，客户要么是会员，要么不是。随着时间的推移，会员级别被引入并使用相同的字段。该字段所存储的信息可以有不同的类型，而您希望通过标准化的值来表示客户的会员级别。
switchOn() 方法会按顺序检查每个子句。如果该值与子句所表示的类型匹配，该子句则会确定与该成员资格级别相对应的字符串值。如果原始值为字符串，则表示成员资格级别，并会使用该值。如果数据类型为布尔值，则会为成员资格级别返回 Gold 或 Guest。如果数据类型为数组，则会返回数组中与最新成员资格级别相匹配的最新字符串。如果 member 字段的类型未知，switchOn() 方法则会提供默认值 Guest。
以下代码展示此聚合的管道：
val member = current().getField("member") listOf( Aggregates.project( Projections.fields( Projections.computed("membershipLevel", member.switchOn{field -> field .isString{s-> s} .isBoolean{b -> b.cond(of("Gold"), of("Guest"))} .isArray { a -> a.last()} .defaults{ d -> of("Guest")}}) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { membershipLevel: { $switch: { branches: [ { case: { $eq: [ { $type: "$member" }, "string" ] }, then: "$member" }, { case: { $eq: [ { $type: "$member" }, "bool" ] }, then: { $cond: { if: "$member", then: "Gold", else: "Guest" } } }, { case: { $eq: [ { $type: "$member" }, "array" ] }, then: { $last: "$member" } } ], default: "Guest" } } } } ]
便捷操作
您可以使用本节中描述的方法将自定义函数应用于类型为 MqlValue 的值。
为了提高可读性并允许重复使用代码，可以将冗余代码移至静态方法中。但是，在 Kotlin 中无法直接链接静态方法。passTo() 方法允许您将值链接到自定义静态方法中。
方法 | 聚合管道操作符 |
|---|---|
没有相应的操作符 |
假设您需要根据一些基准，确定某个班级的表现。您想要知道每个班级的平均期末成绩，并与基准值进行比较。
以下自定义方法 gradeAverage() 接收文档数组以及这些文档之间共享的整数字段的名称。该方法计算所提供数组的所有文档中该字段的平均值，并确定所提供数组的所有元素中该字段的平均值。evaluate() 方法将提供的值与两个提供的范围限值进行比较，并根据比较结果生成响应字符串：
fun gradeAverage(students: MqlArray<MqlDocument>, fieldName: String): MqlNumber { val sum = students.sum{ student -> student.getInteger(fieldName) } val avg = sum.divide(students.size()) return avg } fun evaluate(grade: MqlNumber, cutoff1: MqlNumber, cutoff2: MqlNumber): MqlString { val message = grade.switchOn{ on -> on .lte(cutoff1) { g -> of("Needs improvement") } .lte(cutoff2) { g -> of("Meets expectations") } .defaults{g -> of("Exceeds expectations")}} return message }
提示
passTo() 方法的优点之一是，您可以在其他聚合中重复使用这一自定义方法。您可以使用 gradeAverage() 方法，查找按入学年份或学区（而不仅仅是班级）等条件筛选的学生组的平均成绩。例如，您可以使用 evaluate() 方法来评估学生的个人表现或整个学校或学区的表现。
passArrayTo() 方法会获取所有学生的分数，并使用 gradeAverage() 方法计算平均分数。然后，passNumberTo() 方法使用 evaluate() 方法来确定班级的表现。此示例使用 project() 方法将结果存储为 evaluation 字段。
以下代码展示此聚合的管道：
val students = current().getArray<MqlDocument>("students") listOf( Aggregates.project( Projections.fields( Projections.computed("evaluation", students .passArrayTo { s -> gradeAverage(s, "finalGrade") } .passNumberTo { grade -> evaluate(grade, of(70), of(85)) }) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { evaluation: { $switch: { branches: [ { case: { $lte: [ { $avg: "$students.finalGrade" }, 70 ] }, then: "Needs improvement" }, { case: { $lte: [ { $avg: "$students.finalGrade" }, 85 ] }, then: "Meets expectations" } ], default: "Exceeds expectations" } } } } ]
转换操作
您可以使用本部分所介绍的方法执行转换操作，在某些 MqlValue 类型之间进行转换。
方法 | 聚合管道操作符 |
|---|---|
没有相应的操作符 | |
没有相应的操作符 | |
假设您有一个包含毕业年份的学生数据集合，并且这些数据以字符串形式存储。您想要计算他们五年重聚的年份并将该值存储在新字段中。
parseInteger() 方法将 graduationYear 转换为整数，这样 add() 就可以计算出重聚年份。addFields() 方法将此结果存储为新的 reunionYear 字段。
以下代码展示此聚合的管道：
val graduationYear = current().getString("graduationYear") listOf( Aggregates.addFields( Field("reunionYear", graduationYear .parseInteger() .add(5)) ))
以下代码在 Query API 中提供等效的聚合管道：
[ { $addFields: { reunionYear: { $add: [ { $toInt: "$graduationYear" }, 5 ] } } } ]
日期操作符
您可以使用本部分介绍的方法对 MqlDate 类型的值执行日期操作。
方法 | 聚合管道操作符 |
|---|---|
假设您有关于包裹递送的数据，需要匹配在 "America/New_York" 时区任何星期一发生的递送。
如果 deliveryDate 字段包含任何代表有效日期的字符串值，如 "2018-01-15T16:00:00Z" 或 "Jan 15, 2018, 12:00
PM EST"，则您可以使用 parseDate() 方法将这些字符串转换为日期类型。
dayOfWeek() 方法确定日期是星期几，并根据 "America/New_York" 参数，将其转换为哪天是星期一的数字。eq() 方法会将该值与 2 进行比较，后者根据所提供的时区参数对应于星期一。
以下代码展示此聚合的管道：
val deliveryDate = current().getString("deliveryDate") listOf( Aggregates.match( Filters.expr(deliveryDate .parseDate() .dayOfWeek(of("America/New_York")) .eq(of(2)) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $match: { $expr: { $eq: [ { $dayOfWeek: { date: { $dateFromString: { dateString: "$deliveryDate" } }, timezone: "America/New_York" }}, 2 ] } } } ]
文档操作
您可以使用本节中描述的方法对类型为 MqlDocument 的值执行文档操作。
方法 | 聚合管道操作符 |
|---|---|
没有相应的操作符 | |
假设您有一个旧客户数据集合，其中包括地址作为 mailing.address 字段下的子文档。您想查找目前居住在华盛顿州的所有客户。此集合中的文档可能如下所示：
{ "_id": ..., "customer.name": "Mary Kenneth Keller", "mailing.address": { "street": "601 Mongo Drive", "city": "Vasqueztown", "state": "CO", "zip": 27017 } }
getDocument() 方法会将 mailing.address 字段作为文档进行检索，因此可使用 getString() 方法来检索嵌套的 state 字段。eq() 方法会检查 state 字段的值是否为 "WA"。
以下代码展示此聚合的管道：
val address = current().getDocument("mailing.address") listOf( Aggregates.match( Filters.expr(address .getString("state") .eq(of("WA")) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $match: { $expr: { $eq: [{ $getField: { input: { $getField: { input: "$$CURRENT", field: "mailing.address"}}, field: "state" }}, "WA" ] }}}]
映射操作
您可以使用本节中描述的方法对类型为 MqlMap 或 MqlEntry 的值执行映射操作。
提示
如果数据将日期或列项 ID 等任意键映射到值，则您应将数据表示为映射。
方法 | 聚合管道操作符 |
|---|---|
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 |
假设您有一个库存数据集合，其中每个文档都代表您负责供应的单个物品。每个文档都包含一个字段，该字段是所有仓库的映射，以及目前在该物品的库存方面有多少副本。您要确定所有仓库中物品的副本总数。此集合中的文档可能如下所示：
{ "_id": ..., "item": "notebook" "warehouses": [ { "Atlanta", 50 }, { "Chicago", 0 }, { "Portland", 120 }, { "Dallas", 6 } ] }
entries() 方法会以数组的形式返回 warehouses 字段中的地图条目。sum() 方法会根据使用 getValue() 方法所检索到的数组中的值来计算各商品的总价值。此示例使用 project() 方法将结果存储为新的 totalInventory 字段。
以下代码展示此聚合的管道：
val warehouses = current().getMap<MqlNumber>("warehouses") listOf( Aggregates.project( Projections.fields( Projections.computed("totalInventory", warehouses .entries() .sum { v -> v.getValue() }) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { totalInventory: { $sum: { $getField: { $objectToArray: "$warehouses" }, } } } } ]
字符串操作
您可以使用本节介绍的方法对 MqlString 类型的值执行字符串操作。
方法 | 聚合管道操作符 |
|---|---|
假设您需根据员工的姓氏和员工 ID 为公司员工生成小写用户名。
append() 方法将 lastName 和 employeeID 字段合并为一个用户名，而 toLower() 方法可以使整个用户名小写。此示例使用 project() 方法将结果存储为新的 username 字段。
以下代码展示此聚合的管道：
val lastName = current().getString("lastName") val employeeID = current().getString("employeeID") listOf( Aggregates.project( Projections.fields( Projections.computed("username", lastName .append(employeeID) .toLower()) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { username: { $toLower: { $concat: ["$lastName", "$employeeID"] } } } } ]
类型检查操作
您可以使用本节中描述的方法对类型为 MqlValue 的值执行类型检查操作。
这些方法不返回布尔值。相反，您提供与该方法指定的类型匹配的默认值。如果校验值与方法类型匹配，则返回校验值。否则，将返回所提供的默认值。如果您要根据数据类型对分支逻辑进行编程，请参阅 switchOn()。
方法 | 聚合管道操作符 |
|---|---|
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 | |
没有相应的操作符 |
假设您有评级数据的集合。早期版本的评论模式允许用户提交没有星级的负面评论。您希望将这些没有星级的负面评论转换为最低值 1 星。
isNumberOr() 方法返回 rating 的值，如果 rating 不是数字或为空，则返回 1 的值。project() 方法将此值作为新的 numericalRating 字段返回。
以下代码展示此聚合的管道：
val rating = current().getField("rating") listOf( Aggregates.project( Projections.fields( Projections.computed("numericalRating", rating .isNumberOr(of(1))) )))
以下代码在 Query API 中提供等效的聚合管道：
[ { $project: { numericalRating: { $cond: { if: { $isNumber: "$rating" }, then: "$rating", else: 1 } } } } ]