$meta

On this page本页内容

Definition定义

$meta

Returns the metadata associated with a document, e.g. "textScore" when performing text search.返回与文档关联的元数据，例如执行文本搜索时的"textScore"。

A $meta expression has the following syntax:$meta表达式语法如下所示：

{ $meta: <metaDataKeyword> }

The $meta expression can specify the following values as the <metaDataKeyword>:$meta表达式可以将以下值指定为<metaDataKeyword>：

Keyword关键词Description描述
"textScore"

Returns the score associated with the corresponding $text query for each matching document. 返回与每个匹配文档的相应$text查询关联的分数。The text score signifies how well the document matched the search term or terms.文本分数表示文档与搜索词的匹配程度。

Starting in MongoDB 4.4, must be used in conjunction with a $text query.从MongoDB 4.4开始，必须与$text查询结合使用。

In earlier versions, if not used in conjunction with a $text query, returns a score of null.在早期版本中，如果不与$text查询结合使用，则返回分数null。

"indexKey"

Returns an index key for the document if a non-text index is used. 如果使用非文本索引，则返回文档的索引键。The { $meta: "indexKey" } expression is for debugging purposes only, and not for application logic, and is preferred over cursor.returnKey().{ $meta: "indexKey" }表达式仅用于调试目的，不用于应用程序逻辑，优于cursor.returnKey()。

New in version 4.4.版本4.4中的新功能。

MongoDB Atlas Search provides additional $meta keywords, such as:

Refer to the Atlas Search documentation for details.有关详细信息，请参阅Atlas搜索文档。

Behavior行为

Text Score Metadata $meta: "textScore"

Requires $text Search

  • The { $meta: "textScore" } expression must be used in conjunction with $text search. For example:
    • In aggregation, you must specify a $match stage with a $text query in the pipeline to use the { $meta: "textScore" } expression in later stage(s). If you do not specify the $text query in the $match stage, the operation fails.
    • In find, you must specify the $text operator in the query predicate to use { $meta: "textScore" }. Starting in MongoDB 4.4, if you do not specify the $text operator in the query predicate, the operation fails.

Availability可用性

  • In aggregation, the { $meta: "textScore" } expression can be included in various stages that accept aggregation expressions, such as $project, $group $sort, etc.
  • In find, the { $meta: "textScore" } expression can be included in projection and in sort().

Usage In Projection投影中的用法

  • The { $meta: "textScore" } expression can be a part of the projection document to include the text score metadata.
  • The $meta expression can be present in either an inclusion or an exclusion projection.$meta表达式可以存在于包含投影或排除投影中。
  • If you set the expression to a field name that already exists in the document, the projected metadata value overwrites the existing value.如果将表达式设置为文档中已存在的字段名，则投影的元数据值将覆盖现有值。

Filter on Text Score筛选文本分数

  • In aggregation, following a stage that outputs a field with the text score value, you can specify a query condition or operate on the field in subsequent stages. 在聚合中，在输出带有文本分数值的字段的阶段之后，可以指定查询条件或在后续阶段对字段进行操作。For example, see Text Search in the Aggregation Pipeline.
  • In find, you cannot specify a query condition on the text score. 在“查找”中，不能对文本分数指定查询条件。Use aggregation instead.改用聚合。

Usage In Sort分类使用

  • The { $meta: "textScore" } expression can be used as a part of a sort operation to sort by the text score metadata; i.e.,{ $meta: "textScore" }表达式可以用作排序操作的一部分，以按文本分数元数据排序；例如。，
  • The "textScore" metadata sorts in descending order.
  • To use in a sort operation, set the { $meta: "textScore" } expression to an arbitrary field name. The field name is disregarded by the query system.

Sort without Projection无投影排序

  • In aggregation, you can sort the resulting documents by { $meta: "textScore" } without also having to project the textScore.
  • In find, starting in MongoDB 4.4, you can sort the resulting documents by { $meta: "textScore" } without also having to project the textScore.

    In MongoDB 4.2 and earlier, to use { $meta: "textScore" } expression with sort() for a find operation, you must also include the same expression in the projection.

Sort with Projection用投影排序

  • In aggregation, if you include the { $meta: "textScore" } expression in both the projection and sort, the projection and sort can have different field names for the expression. 在聚合中，如果在投影和排序中都包含{ $meta: "textScore" }表达式，则投影和排序可以为表达式指定不同的字段名。The field name in the sort is disregarded by the query system.查询系统将忽略排序中的字段名。
  • In find, starting in MongoDB 4.4, if you include the { $meta: "textScore" } expression in both the projection and sort, the projection and sort can have different field names for the expression. The field name in the sort is disregarded by the query system.在find中，从MongoDB 4.4开始，如果在投影和排序中都包含{ $meta: "textScore" }表达式，则投影和排序可以为表达式提供不同的字段名。查询系统将忽略排序中的字段名。

    In MongoDB 4.2 and earlier, to include the { $meta: "textScore" } in both the projection and sort for a find operation, you must specify the same field name in both places.在MongoDB 4.2及更早版本中，要在查找操作的投影和排序中包含{ $meta: "textScore" }，必须在两个位置指定相同的字段名。

Index Key Metadata $meta: “indexKey” (Aggregation and Find)索引键元数据$meta:“索引键”（聚合和查找）

Usage

  • The { $meta: "indexKey" } expression is for debugging purposes only and not for application logic.{ $meta: "indexKey" }表达式仅用于调试目的，不用于应用程序逻辑。
  • The { $meta: "indexKey" } expression is preferred over cursor.returnKey().{ $meta: "indexKey" }达式优先于cursor.returnKey()。

Availability可用性

  • In aggregation, the { $meta: "indexKey" } expression can be included in various stages that accept aggregation expressions, such as $project, $group $sortByCount, etc., but not $sort. However, with an aggregation pipeline, you can first project the { $meta: "indexKey" } expression (such as in a $project, $addFields, etc. ) and then, sort by that field in a subsequent $sort stage.
  • In find, the { $meta: "indexKey" } expression is only available as part of the projection document.

Return Value返回值

  • The value returned depends on how the database decides to represent values in an index and may change across versions. 返回的值取决于数据库决定如何在索引中表示值，并且可能会在不同版本之间更改。The represented value may not be the actual value for the field.表示的值可能不是字段的实际值。
  • The value returned depends on the execution plan chosen by the system. 返回的值取决于系统选择的执行计划。For example, if there are two possible indexes which can be used to answer the query, then the value of the “indexKey” metadata depends on which index is selected.例如，如果有两个可能的索引可用于回答查询，那么“indexKey”元数据的值取决于选择的索引。
  • If an index is not used, the { $meta: "indexKey" } expression does not return a value and the field is not included as part of the output.如果未使用索引，{ $meta: "indexKey" }表达式不会返回值，并且该字段不会作为输出的一部分包含。

Examples示例

$meta: "textScore"

Create an articles collection with the following documents:使用以下文档创建articles集合：

db.articles.insertMany([
   { "_id" : 1, "title" : "cakes and ale" },
   { "_id" : 2, "title" : "more cakes" },
   { "_id" : 3, "title" : "bread" },
   { "_id" : 4, "title" : "some cakes" },
   { "_id" : 5, "title" : "two cakes to go" },
   { "_id" : 6, "title" : "pie" }
])

Create a text index on the title field:在title字段上创建文本索引：

db.articles.createIndex( { title: "text"} )

The following aggregation operation performs a text search and uses the $meta operator to group by the text search score:以下聚合操作执行文本搜索，并使用$meta运算符根据文本搜索分数进行分组：

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake" } } },
     { $group: { _id: { $meta: "textScore" }, count: { $sum: 1 } } }
   ]
)

The operation returns the following results:操作返回以下结果：

{ "_id" : 0.75, "count" : 1 }
{ "_id" : 0.6666666666666666, "count" : 1 }
{ "_id" : 1, "count" : 2 }

For more examples, see Text Search in the Aggregation Pipeline.有关更多示例，请参阅聚合管道中的文本搜索。

The following query performs a text search for the term cake and uses the $meta operator in the projection document to include the score assigned to each matching document:以下查询对术语cake执行文本搜索，并在投影文档中使用$meta运算符来包括分配给每个匹配文档的分数：

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
)

The operation returns the following documents with the text score:该操作返回以下带有文本分数的文档：

{ "_id" : 4, "title" : "some cakes", "score" : 1 }
{ "_id" : 1, "title" : "cakes and ale", "score" : 0.75 }
{ "_id" : 5, "title" : "two cakes to go", "score" : 0.6666666666666666 }
{ "_id" : 2, "title" : "more cakes", "score" : 1 }

For additional examples of "textScore" projections and sorts, see Text Search Score Examples.有关"textScore"投影和排序的其他示例，请参阅文本搜索分数示例。

$meta: "indexKey"

Note

The { $meta: "indexKey" } expression is for debugging purposes only and not for application logic. { $meta: "indexKey" }表达式仅用于调试目的，不用于应用程序逻辑。MongoDB returns the value associated with the index chosen by the query system. MongoDB返回与查询系统选择的索引关联的值。The system can choose a different index upon subsequent execution.系统可以在后续执行时选择不同的索引。

For the selected index, the value returned depends on how the database decides to represent values in an index and may change across versions. 对于所选索引，返回的值取决于数据库决定如何表示索引中的值，并且可能会在不同版本之间发生变化。The represented value may not be the actual value for the field.表示的值可能不是字段的实际值。

Create an orders collection with the following documents:创建带有以下文档的orders集合：

db.orders.insertMany([
   { "item" : "abc", "price" : NumberDecimal("12"), "quantity" : 2, "type": "apparel" },
   { "item" : "jkl", "price" : NumberDecimal("20"), "quantity" : 1, "type": "electronics" },
   { "item" : "abc", "price" : NumberDecimal("10"), "quantity" : 5, "type": "apparel" }
])

Create the following compound index on the type and item fields:在type和item字段上创建以下复合索引：

db.orders.createIndex( { type: 1, item: 1 } )

The following aggregation operation finds all documents with type equal to apparel and uses the $meta operator to include the index key value for the matching document if an index was used:以下聚合操作将查找type等于apparel的所有文档，如果使用了索引，则使用$meta运算符包含匹配文档的索引键值：

db.orders.aggregate(
   [
     { $match: { type: "apparel" } },
     { $addFields: { idxKey: { $meta: "indexKey" } } }
   ]
)

The following operation finds all documents with type equal to apparel and uses the $meta operator to include the index key value for the matching document if an index was used:

db.orders.find( { type: "apparel" }, { idxKey: { $meta: "indexKey" } } )

The operation returns the matching documents with their corresponding index key:该操作返回匹配文档及其相应的索引键：

{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"),
   "item" : "abc",
   "price" : NumberDecimal("12"),
   "quantity" : 2,
   "type" : "apparel",
"idxKey" : { "type" : "apparel", "item" : "abc" }}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"),
   "item" : "abc",
   "price" : NumberDecimal("10"),
   "quantity" : 5,
   "type" : "apparel",
"idxKey" : { "type" : "apparel", "item" : "abc" }}

If no index is used, the { $meta: "indexKey" } does not return anything.

For example, the following operation does not use an index since no index exists on the price field to support the match condition:例如，以下操作不使用索引，因为price字段上不存在支持匹配条件的索引：

db.orders.aggregate(
   [
     { $match: { price: { $gte: NumberDecimal("10") } } },
     { $addFields: { idxKey: { $meta: "indexKey" } } }
   ]
)

For example, the following operation does not use an index since no index exists on the price field to support the match condition:例如，以下操作不使用索引，因为price字段上不存在支持匹配条件的索引：

db.orders.find(
   { price: { $gte: NumberDecimal("10") } },
   { idxKey: { $meta: "indexKey" } }
)

The operation returns the matching documents without the idxKey field:该操作返回匹配的文档，但不包含idxKey字段：

{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"),
   "item" : "abc",
   "price" : NumberDecimal("12"),
   "quantity" : 2,
   "type" : "apparel"
}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcdf"),
   "item" : "jkl",
   "price" : NumberDecimal("20"),
   "quantity" : 1,
   "type" : "electronics"
}
{
   "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"),
   "item" : "abc",
   "price" : NumberDecimal("10"),
   "quantity" : 5,
   "type" : "apparel"
}