For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Expressions
Docs Home
/
Development
/
Query Language
/
Expressions
Docs Home
/
Development
/
Query Language
/
Expressions

$meta (expression operator)

Definition

$meta

Returns the metadata associated with a document, e.g. "textScore" when performing text search.

A $meta expression has the following syntax:

{ $meta: <metaDataKeyword> }

The $meta expression can specify the following values as the <metaDataKeyword>:

Keyword
Description

"textScore"

Returns the score associated with the corresponding $text query for each matching document. The text score signifies how well the document matched the search term or terms.

{ $meta: "textScore" } must be used in conjunction with a $text query.

In earlier versions, if not used in conjunction with a $text query, returns a score of 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().

MongoDB Search provides additional $meta keywords, such as:

Refer to the MongoDB Search documentation for details.

Important

The following $meta keywords are not supported in Stable API V1:

  • "textScore"

  • "indexKey"

  • "score"

  • "searchScore"

  • "scoreDetails"

  • "searchHighlights"

  • "searchSequenceToken"

  • "searchScoreDetails"

  • "vectorSearchScore"

  • "searchRootDocumentId"

You can use searchScore only in $search queries and vectorSearchScore only in $vectorSearch queries. If you use searchScore and vectorSearchScore in any other query, that query will fail.

You can use searchRootDocumentId only in $search queries with returnScope.

Behavior

Text Score Metadata $meta: "textScore"

Requires $text Search

  • The { $meta: "textScore" } expression must be used in conjunction with $text. 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" }. If you do not specify the $text operator in the query predicate, the operation fails.

    Note

    $text provides text query capabilities for self-managed (non-Atlas) deployments. For data hosted on MongoDB, MongoDB also offers an improved full-text query solution, MongoDB Search.

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.

  • 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 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.,

  • 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, you can sort the resulting documents by { $meta: "textScore" } without also having to project the textScore.

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. The field name in the sort is disregarded by the query system.

  • In find, 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.

Index Key Metadata $meta: "indexKey" (Aggregation and Find)

Usage

  • The { $meta: "indexKey" } expression is for debugging purposes only and not for application logic.

  • The { $meta: "indexKey" } expression is preferred over 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.

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

Examples

Back

$maxN-array-element

Next

$minN-array-element

On this page