> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # $meta (expression operator) ## Definition Returns the metadata associated with a document, e.g. `"textScore"` when performing text search. A [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression has the following syntax: ```javascript { $meta: } ``` The [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression can specify the following values as the ``: | Keyword | Description | | --- | --- | | `"textScore"` | Returns the score associated with the corresponding [`$text`](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#mongodb-query-op.-text) query for each matching document. The text score signifies how well the document matched the [search term or terms.](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#std-label-match-operation-stemmed-words) `{ $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](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-text.md#std-label-index-type-text) index is used. The `{ $meta: "indexKey" }` expression is for debugging purposes only, and not for application logic, and is preferred over [`cursor.returnKey()`.](https://www.mongodb.com/docs/manual/reference/method/cursor.returnkey.md#mongodb-method-cursor.returnKey) | [MongoDB Search](https://www.mongodb.com/docs/atlas/full-text-search/) provides additional `$meta` keywords, such as: - ["searchScore"](https://www.mongodb.com/docs/atlas/atlas-search/scoring/) - ["searchHighlights"](https://www.mongodb.com/docs/atlas/atlas-search/highlighting/) - ["searchScoreDetails"](https://www.mongodb.com/docs/atlas/atlas-search/scoring/) - ["searchSequenceToken"](https://www.mongodb.com/docs/atlas/atlas-search/paginate-results/) - ["searchRootDocumentId"](https://www.mongodb.com/docs/atlas/atlas-search/return-scope/) - ["vectorSearchScore"](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/#mongodb-vector-search-score) Refer to the MongoDB Search documentation for details. **Important:** The following `$meta` keywords are not supported in [Stable API](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-stable-api) V1: - `"textScore"` - `"indexKey"` - `"score"` - `"searchScore"` - `"scoreDetails"` - `"searchHighlights"` - `"searchSequenceToken"` - `"searchScoreDetails"` - `"vectorSearchScore"` - `"searchRootDocumentId"` You can use `searchScore` only in [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) queries and `vectorSearchScore` only in [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch) queries. If you use `searchScore` and `vectorSearchScore` in any other query, that query will fail. You can use `searchRootDocumentId` only in [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) queries with `returnScope`. ## Behavior ### Text Score Metadata `$meta: "textScore"` #### Requires $text Search - The `{ $meta: "textScore" }` expression must be used in conjunction with [`$text`](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#mongodb-query-op.-text). For example: - In aggregation, you must specify a [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-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.](https://www.mongodb.com/docs/atlas/atlas-search/) #### Availability - In aggregation, the `{ $meta: "textScore" }` expression can be included in various stages that accept aggregation expressions, such as [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project), [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort), etc. - In find, the `{ $meta: "textScore" }` expression can be included in [projection](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#std-label-find-projection) and in [`sort()`.](https://www.mongodb.com/docs/manual/reference/method/cursor.sort.md#mongodb-method-cursor.sort) #### Usage In Projection - The `{ $meta: "textScore" }` expression can be a part of the [projection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-projection) document to include the text score metadata. - The [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-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.](https://www.mongodb.com/docs/manual/tutorial/text-search-in-aggregation.md) - 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., - In aggregation, [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort) stage. - In find, [`sort()`](https://www.mongodb.com/docs/manual/reference/method/cursor.sort.md#mongodb-method-cursor.sort) method. - 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" }`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) 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" }`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) 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()`.](https://www.mongodb.com/docs/manual/reference/method/cursor.returnkey.md#mongodb-method-cursor.returnKey) #### Availability - **In aggregation**, the `{ $meta: "indexKey" }` expression can be included in various stages that accept aggregation expressions, such as [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project), [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) [`$sortByCount`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortbycount.md#mongodb-pipeline-pipe.-sortByCount), etc., but not [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort). However, with an aggregation pipeline, you can first project the `{ $meta: "indexKey" }` expression (such as in a [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project), [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields), etc. ) and then, sort by that field in a subsequent [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort) stage. - **In find**, the `{ $meta: "indexKey" }` expression is only available as part of the [projection](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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 ### `$meta: "textScore"` Create an `articles` collection with the following documents: ```javascript 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](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-text/create-text-index.md#std-label-create-text-index) on the `title` field: ```javascript db.articles.createIndex( { title: "text"} ) ``` The following aggregation operation performs a text search and uses the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) operator to group by the text search score: ```javascript db.articles.aggregate( [ { $match: { $text: { $search: "cake" } } }, { $group: { _id: { $meta: "textScore" }, count: { $sum: 1 } } } ] ) ``` The operation returns the following results: ```javascript { "_id" : 0.75, "count" : 1 } { "_id" : 0.6666666666666666, "count" : 1 } { "_id" : 1, "count" : 2 } ``` For more examples, see [$text in the Aggregation Pipeline.](https://www.mongodb.com/docs/manual/tutorial/text-search-in-aggregation.md) The following query performs a text search for the term `cake` and uses the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) operator in the projection document to include the score assigned to each matching document: ```javascript db.articles.find( { $text: { $search: "cake" } }, { score: { $meta: "textScore" } } ) ``` The operation returns the following documents with the text score: ```javascript { "_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 [Relevance Score Examples.](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#std-label-ex-text-search-score) ### `$meta: "indexKey"` **Note:** The `{ $meta: "indexKey" }` expression is for debugging purposes only and not for application logic. MongoDB returns the value associated with the index chosen by the query system. 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: ```javascript db.orders.insertMany([ { "item" : "abc", "price" : Decimal128("12"), "quantity" : 2, "type": "apparel" }, { "item" : "jkl", "price" : Decimal128("20"), "quantity" : 1, "type": "electronics" }, { "item" : "abc", "price" : Decimal128("10"), "quantity" : 5, "type": "apparel" } ]) ``` Create the following compound index on the `type` and `item` fields: ```javascript db.orders.createIndex( { type: 1, item: 1 } ) ``` The following aggregation operation finds all documents with `type` equal to `apparel` and uses the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) operator to include the index key value for the matching document if an index was used: ```javascript 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) operator to include the index key value for the matching document if an index was used: ```javascript db.orders.find( { type: "apparel" }, { idxKey: { $meta: "indexKey" } } ) ``` The operation returns the matching documents with their corresponding index key: ```javascript { "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"), "item" : "abc", "price" : Decimal128("12"), "quantity" : 2, "type" : "apparel", "idxKey" : { "type" : "apparel", "item" : "abc" } } { "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"), "item" : "abc", "price" : Decimal128("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: ```javascript db.orders.aggregate( [ { $match: { price: { $gte: Decimal128("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: ```javascript db.orders.find( { price: { $gte: Decimal128("10") } }, { idxKey: { $meta: "indexKey" } } ) ``` The operation returns the matching documents without the `idxKey` field: ```javascript { "_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" } ``` The C# examples on this page use the `sample_mflix` database from the [Atlas sample datasets](https://www.mongodb.com/docs/atlas/sample-data/). To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see [Get Started](https://www.mongodb.com/docs/drivers/csharp/current/quick-start/) in the MongoDB .NET/C# Driver documentation. The following `Movie` class models the documents in the `sample_mflix.movies` collection: ```csharp public class Movie { public ObjectId Id { get; set; } public string Plot { get; set; } public List Genres { get; set; } public int Runtime { get; set; } public List Cast { get; set; } public string Title { get; set; } [BsonElement("lastupdated")] public DateTime LastUpdated { get; set; } public string Rated { get; set; } public int Year { get; set; } public ImdbData Imdb { get; set; } public string Type { get; set; } public int Index { get; set; } public string[] Comments { get; set; } public List Highlights { get; set; } public float Score { get; set; } [BsonElement("scoreDetails")] public SearchScoreDetails ScoreDetails { get; set; } [BsonElement("searchScoreDetails")] public SearchScoreDetails SearchScoreDetails { get; set; } [BsonElement("paginationToken")] public string PaginationToken { get; set; } [BsonElement("plot_embedding")] public float[] PlotEmbedding { get; set; } } ``` **Note: ConventionPack for Pascal Case** The C# classes on this page use Pascal case for their property names, but the field names in the MongoDB collection use camel case. To account for this difference, you can use the following code to register a `ConventionPack` when your application starts: ```csharp var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() }; ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true); ``` To include the text search score by using the .NET/C# driver, call the [MetaTextScore()](https://mongodb.github.io/mongo-csharp-driver/3.11.0/api/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaTextScore.html) method on the projection builder. First, run the following code to create a text index on the `Title` field: ```csharp var indexModel = new CreateIndexModel( Builders.IndexKeys.Text(m => m.Title)); movieCollection.Indexes.CreateOne(indexModel); ``` Then, add the following code to your application. The code performs a text search for the term `"future"` and uses the `MetaTextScore()` method to include the score assigned to each matching document. The code then sorts the results in descending order by their text score and returns the document with the highest score. ```csharp var filter = Builders.Filter.Text("future"); var projection = Builders.Projection .Include(m => m.Title) .Include(m => m.Plot) .MetaTextScore(m => m.Score); var result = movieCollection.Find(filter) .Sort(Builders.Sort.MetaTextScore("score")) .Project(projection) .FirstOrDefault(); ``` The preceding operation returns the following document: ```json { "_id": { "$oid": "573a1398f29313caabceb500" }, "plot": "After visiting 2015, Marty McFly must repeat his visit to 1955 to prevent disastrous changes to 1985... without interfering with his first trip.", "title": "Back to the Future Part II", "score": 1.59375 } ```