> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Return the Score Details You can use the `scoreDetails` boolean option in your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage for a detailed breakdown of the score for each document in the query results. When you set `scoreDetails: true` in your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage, MongoDB Search returns detailed scoring information for each matching document. This information explains why a document matched the query and received its relevance score in the search results. By default, scoring is based on the [bm25](https://www.mongodb.com/docs/search/query/score/get-details.md#std-label-fts-bm25) formula: - Term frequency: How often a search term appears in the document - Inverse document frequency: How common the search term is across all documents - Field length: The length of the field matching the query The `scoreDetails` option breaks down these factors to help you analyze why a document matched the query and received its score. To view the metadata, you must use the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression in the [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage. ## Syntax ```json { "$search": { "": { }, "scoreDetails": true | false } }, { "$project": { "scoreDetails": {"$meta": "searchScoreDetails"} } } ``` ## Options *In the $search stage*, the `scoreDetails` boolean option takes one of the following values: - `true` - to include details of the score for the documents in the results. If set to `true`, MongoDB Search returns a detailed breakdown of the score for each document in the result. This provides information on why certain documents matched a MongoDB Search query. To learn more, see [Output.](https://www.mongodb.com/docs/search/query/score/get-details.md#std-label-fts-score-details-output) - `false` - to exclude details of the score breakdown for the results. (Default) If omitted, the `scoreDetails` option defaults to `false`. *In the $project stage*, the `scoreDetails` field takes the [`$meta`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta.md#mongodb-expression-exp.-meta) expression, which requires the following value: | `searchScoreDetails` | Returns a detailed breakdown of the score for each document in the results. | | --- | --- | ## Output The `scoreDetails` option returns the following fields in the `details` array inside the `scoreDetails` object for each document in the result: | Field | Type | Description | | --- | --- | --- | | `value` | float | Contribution towards the score by a subset of the scoring formula. The top-level `value` shows the entire score of the result document, and is equal to the value of `$searchScore`. The scoring formula varies based on the operator used in the query. For example, MongoDB Search uses a [distance decay function](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-query-score) to calculate the score for the [near](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-ref) operator. | | `description` | string | Subset of the scoring formula including details about how the document was scored and factors considered in calculating the score. The top-level `description` shows the entire scoring formula used to score the document. To learn more, see [Factors That Contribute to the Score.](https://www.mongodb.com/docs/search/query/score/get-details.md#std-label-fts-score-details-factors) | | `details` | array of objects | Breakdown of the score for each match in the document based on the subset of the scoring formula. The value is an array of score details objects, recursive in structure. | ## Factors That Contribute to the Score Different query operators use different algorithms to calculate the `searchScore` for each document in the results. The following sections describe how common query operators handle scoring: ### text, phrase, queryString, and autocomplete Operators By default, the [text](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref), [phrase](https://www.mongodb.com/docs/search/query/operators-collectors/phrase.md#std-label-phrase-ref), [queryString](https://www.mongodb.com/docs/search/query/operators-collectors/querystring.md#std-label-querystring-ref) and [autocomplete](https://www.mongodb.com/docs/search/query/operators-collectors/autocomplete.md#std-label-autocomplete-ref) operators use the `bm25` similarity algorithm to score documents. We recommend using the `stableTfl` or `boolean` algorithms when you need consistent results across multiple queries, especially if both of the following are true: - Your application sorts results by `searchScore` and [paginates results](https://www.mongodb.com/docs/search/query/paginate-results.md#std-label-fts-paginate-results), which relies on deterministic scoring to prevent duplicates or skipped documents - Your deployment uses [dedicated MongoDB Search nodes](https://www.mongodb.com/docs/search/deployment/deployment-options.md#std-label-node-architecture) or has [read preference](https://www.mongodb.com/docs/manual/core/read-preference.md#std-label-replica-set-read-preference) set to `secondary` or `nearest`, which increases the likelihood that initial and subsequent queries are routed to different MongoDB Search nodes `bm25` scores might not be consistent between subsequent queries. Each MongoDB Search node builds MongoDB Search indexes and performs update and delete operations independently, resulting in a document corpus that might vary between different MongoDB Search nodes. Since `bm25` calculations depend on the document corpus, subsequent queries that are routed to different MongoDB Search nodes might calculate different `bm25` scores for the same documents. To use a different similarity algorithm, specify the `similarity.type` property in the MongoDB Search index definition for fields that you index as MongoDB Search `string` or `autocomplete` type. To learn how to configure a MongoDB Search index for these types, see [How to Index String Fields](https://www.mongodb.com/docs/search/indexes/field-types/string-type.md#std-label-bson-data-types-string) or [How to Index Fields for Autocompletion.](https://www.mongodb.com/docs/search/indexes/field-types/autocomplete-type.md#std-label-bson-data-types-autocomplete) You can choose from the following similarity algorithms when you specify the `similarity.type` property in your MongoDB Search index definition: #### bm25 `bm25` is a popular ranking algorithm that ranks documents based on: - Term frequency: How often a search term appears in the document - Inverse document frequency: How common the search term is across all documents - Field length: The length of the field matching the query `bm25` computes the score as `boost * idf * tf`, where each factor is defined as follows: | Factor | Description | | --- | --- | | `boost` | Factor specified at query time using the query operator's `score.boost` option. You can set `boost` to a positive number or the value of a numeric field in the documents. To learn more, see [boost.](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-boost) | | `idf` | Inverse document frequency of the query. MongoDB Search computes the frequency using the following formula: `idf = log(1 + (N - n + 0.5) / (n + 0.5))` where: `N` is the total number of documents with the query field.; `n` is the number of documents containing the query term. | | `tf` | Term frequency. MongoDB Search computes the frequency using the following formula: `tf = freq / (freq + k1 * (1 - b + b * dl / avgdl))` where: `freq` is the number of occurrences of the term within the document.; `k1` is the internally specified term saturation parameter. It affects how much the score increases with each reoccurrence of the term.; `b` is the internally specified length normalization parameter. `b` is multiplied by the ratio of `dl` to `avgdl`. If `b` increases, the effects of the ratio of `dl` to `avgdl` is amplified.; `dl` is the length of the field in the document.; `avgdl` is the average length of the field across all documents. | #### boolean `boolean` is a scoring algorithm that checks whether each query term is present in a document and counts how many terms are found. All matching terms are treated equally, with no adjustment for term importance or frequency. For `boolean`, the score is computed as the sum of all query terms which are present in the document, where each term contributes a value of `1` to the score if it is present in the document. #### stableTfl `stableTfl` is a custom MongoDB Search ranking algorithm that uses the length of terms to derive term rarity. This is based on **Zipf's law**, which states that longer words appear less frequently (are more rare). `stableTfl` computes the score as `boost * tr * tf`, where each factor is defined as follows: | Factor | Description | | --- | --- | | `boost` | Factor specified at query time using the query operator's `score.boost` option. You can set `boost` to a positive number or the value of a numeric field in the documents. To learn more, see [boost.](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-boost) | | `tf` | Decaying function. MongoDB Search computes the decaying function using the following formula: `tf = freq / (freq + k1)` where: `freq` is the frequency of the query term in a document.; `k1` is the internally specified term saturation parameter. It affects how much the score increases with each reoccurrence of the term. | | `tr` | Term rarity. MongoDB Search computes the term rarity using the following formula: `tr = log(1 + (1 - p + 0.05)/(p + 0.05))` where: `p` is the probability of the query term appearing in the document based on the term length. This is based on **Zipf's law**, which states that longer words appear less frequently. To determine term rarity, MongoDB uses a decaying function based on term length. | | `p` | Probability function based on **Zipf's law**. MongoDB Search computes the probability of the query term appearing in the document using the following formula: `p = 1 - (1 - m * 2 ^ (-c * tl)) ^ dl` where: `m` is the internally specified multiplicative constant to term probability.; `c` is the internally specified decaying constant. It controls how fast `p` decreases as term length increases.; `tl` is the length of the query term, measured in unicode codepoints.; `dl` is the length of document d, measured in tokens. | ### near Operator The [near](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-ref) operator uses a distance decay function to score documents. It measures the proximity of the MongoDB Search results to the number, date, or geographic [point](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geojson-point) that you set as the `origin` value. The distance decay function computes the score as `pivot / (pivot + distance)`, where each factor is defined as follows: | Factor | Description | | --- | --- | | `pivot` | Value specified as a reference point to make the score equal to `0.5` if the distance between `fieldValue` and `origin` is equal to it. This defines how quickly the score decays as the distance between `fieldValue` and `origin` grows. For a given distance between `fieldValue` and `origin`, if `pivot` decreases, the score also decreases. | | `distance` | Absolute distance between `fieldValue` and `origin`. MongoDB Search computes this value using the following formula: `abs(fieldValue - origin)` where: `fieldValue` is the value of the field that you are querying in the document.; `origin` is the number, date, or geographic point to search near. | ## Examples The following examples show how to retrieve the details of the scores in the results for the following: - Queries run using [text](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref), [near](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-ref), [compound](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref), and [embeddedDocument](https://www.mongodb.com/docs/search/query/operators-collectors/embedded-document.md#std-label-embedded-document-ref) operators. - Queries with scores modified using [`function`](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-function) option expressions. **Tip:** To view details of the score recursively in the arrays of objects, configure the settings in [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) by running the following: ```shell config.set('inspectDepth', Infinity) ``` ### Operator Examples The following examples demonstrate how to retrieve a breakdown of the score using the [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) `scoreDetails` option for the documents in the results for the [text](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref), [near](https://www.mongodb.com/docs/search/query/operators-collectors/near.md#std-label-near-ref), [compound](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref), and [embeddedDocument](https://www.mongodb.com/docs/search/query/operators-collectors/embedded-document.md#std-label-embedded-document-ref) operator queries. ### text The following example uses the [text](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref) operator to query the `title` field in the `sample_mflix.movies` collection for the term `autumn`. The query specifies the `scoreDetails` option in the [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage to retrieve a detailed breakdown of the score for each document in the results. The query uses the [`$limit`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit) stage to limit the results to three documents and the [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage to do the following: - Exclude the `_id` field. - Include only the `title` field. - Add the `score` field to the results to return the score of the document and the `scoreDetails` field to the results to return a detailed breakdown of the score for the document. ```json db.movies.aggregate([ { "$search": { "text": { "path": "title", "query": "autumn" }, "scoreDetails": true } }, { "$limit": 3 }, { "$project": { "_id": 0, "title": 1, "score": { "$meta": "searchScore" }, "scoreDetails": { "$meta": "searchScoreDetails" } } } ]) ``` **Output:** ```json [ { title: 'Autumn Leaves', score: 3.834893226623535, scoreDetails: { value: 3.834893226623535, description: '$type:string/title:autumn [BM25Similarity], result of:', details: [ { value: 3.834893226623535, description: 'score(freq=1.0), computed as boost * idf * tf from:', details: [ { value: 7.39188289642334, description: 'idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:', details: [ { value: 14, description: 'n, number of documents containing term', details: [] }, { value: 23529, description: 'N, total number of documents with field', details: [] } ] }, { value: 0.5187978744506836, description: 'tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:', details: [ { value: 1, description: 'freq, occurrences of term within document', details: [] }, { value: 1.2000000476837158, description: 'k1, term saturation parameter', details: [] }, { value: 0.75, description: 'b, length normalization parameter', details: [] }, { value: 2, description: 'dl, length of field', details: [] }, { value: 2.868375301361084, description: 'avgdl, average length of field', details: [] } ] } ] } ] } }, { title: 'Late Autumn', score: 3.834893226623535, scoreDetails: { value: 3.834893226623535, description: '$type:string/title:autumn [BM25Similarity], result of:', details: [ { value: 3.834893226623535, description: 'score(freq=1.0), computed as boost * idf * tf from:', details: [ { value: 7.39188289642334, description: 'idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:', details: [ { value: 14, description: 'n, number of documents containing term', details: [] }, { value: 23529, description: 'N, total number of documents with field', details: [] } ] }, { value: 0.5187978744506836, description: 'tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:', details: [ { value: 1, description: 'freq, occurrences of term within document', details: [] }, { value: 1.2000000476837158, description: 'k1, term saturation parameter', details: [] }, { value: 0.75, description: 'b, length normalization parameter', details: [] }, { value: 2, description: 'dl, length of field', details: [] }, { value: 2.868375301361084, description: 'avgdl, average length of field', details: [] } ] } ] } ] } }, { title: 'Cheyenne Autumn', score: 3.834893226623535, scoreDetails: { value: 3.834893226623535, description: '$type:string/title:autumn [BM25Similarity], result of:', details: [ { value: 3.834893226623535, description: 'score(freq=1.0), computed as boost * idf * tf from:', details: [ { value: 7.39188289642334, description: 'idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:', details: [ { value: 14, description: 'n, number of documents containing term', details: [] }, { value: 23529, description: 'N, total number of documents with field', details: [] } ] }, { value: 0.5187978744506836, description: 'tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:', details: [ { value: 1, description: 'freq, occurrences of term within document', details: [] }, { value: 1.2000000476837158, description: 'k1, term saturation parameter', details: [] }, { value: 0.75, description: 'b, length normalization parameter', details: [] }, { value: 2, description: 'dl, length of field', details: [] }, { value: 2.868375301361084, description: 'avgdl, average length of field', details: [] } ] } ] } ] } } ] ``` MongoDB Search takes into account the following `BM25Similarity` factors for calculating the score: | Factor | Description | | --- | --- | | `boost` | Factor specified at query time using the query operator's `score.boost` option. You can set `boost` to a positive number or the value of a numeric field in the documents. To learn more, see [boost.](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-scoring-boost) | | `idf` | Inverse document frequency of the query. MongoDB Search computes the frequency using the following formula: `idf = log(1 + (N - n + 0.5) / (n + 0.5))` where: `N` is the total number of documents with the query field.; `n` is the number of documents containing the query term. | | `tf` | Term frequency. MongoDB Search computes the frequency using the following formula: `tf = freq / (freq + k1 * (1 - b + b * dl / avgdl))` where: `freq` is the number of occurrences of the term within the document.; `k1` is the internally specified term saturation parameter. It affects how much the score increases with each reoccurrence of the term.; `b` is the internally specified length normalization parameter. `b` is multiplied by the ratio of `dl` to `avgdl`. If `b` increases, the effects of the ratio of `dl` to `avgdl` is amplified.; `dl` is the length of the field in the document.; `avgdl` is the average length of the field across all documents. | ### Custom Score Examples The following examples demonstrate how to retrieve a breakdown of the score using the [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) `scoreDetails` option for the documents in the results for the [function expression example](https://www.mongodb.com/docs/search/query/score/modify-score.md#std-label-function-score-egs) queries against the `sample_mflix.movies` collection. ### Arithmetic ```json db.movies.aggregate([{ "$search": { "text": { "path": "title", "query": "men", "score": { "function":{ "multiply":[ { "path": { "value": "imdb.rating", "undefined": 2 } }, { "score": "relevance" } ] } } }, "scoreDetails": true } }, { $limit: 5 }, { $project: { "_id": 0, "title": 1, "score": { "$meta": "searchScore" }, "scoreDetails": {"$meta": "searchScoreDetails"} } }]) ``` **Output:** ```json [ { title: 'Men...', score: 23.431293487548828, scoreDetails: { value: 23.431293487548828, description: 'FunctionScoreQuery($type:string/title:men, scored by (imdb.rating * scores)) [BM25Similarity], result of:', details: [ { value: 23.431293487548828, description: '(imdb.rating * scores)', details: [] } ] } }, { title: '12 Angry Men', score: 22.080968856811523, scoreDetails: { value: 22.080968856811523, description: 'FunctionScoreQuery($type:string/title:men, scored by (imdb.rating * scores)) [BM25Similarity], result of:', details: [ { value: 22.080968856811523, description: '(imdb.rating * scores)', details: [] } ] } }, { title: 'X-Men', score: 21.34803581237793, scoreDetails: { value: 21.34803581237793, description: 'FunctionScoreQuery($type:string/title:men, scored by (imdb.rating * scores)) [BM25Similarity], result of:', details: [ { value: 21.34803581237793, description: '(imdb.rating * scores)', details: [] } ] } }, { title: 'X-Men', score: 21.34803581237793, scoreDetails: { value: 21.34803581237793, description: 'FunctionScoreQuery($type:string/title:men, scored by (imdb.rating * scores)) [BM25Similarity], result of:', details: [ { value: 21.34803581237793, description: '(imdb.rating * scores)', details: [] } ] } }, { title: 'Matchstick Men', score: 21.05954933166504, scoreDetails: { value: 21.05954933166504, description: 'FunctionScoreQuery($type:string/title:men, scored by (imdb.rating * scores)) [BM25Similarity], result of:', details: [ { value: 21.05954933166504, description: '(imdb.rating * scores)', details: [] } ] } } ] ```