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
/ /
score
Docs Home
/ /
Search Options
/
score
Docs Home
/
Development
/
Search
/
Queries & Indexes
/
Query Reference
/
Search Options
/
score

Return the Score Details

You can use the scoreDetails boolean option in your $search stage for a detailed breakdown of the score for each document in the query results.

When you set scoreDetails: true in your $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 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 expression in the $project stage.

Syntax

{
  "$search": {
    "<operator>": {
      <operator-specification>
    },
    "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.

  • 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 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 to calculate the score for the near 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.

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, phrase, queryString and autocomplete 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, which relies on deterministic scoring to prevent duplicates or skipped documents

  • Your deployment uses dedicated MongoDB Search nodes or has 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 or How to Index Fields for Autocompletion.

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.

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.

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 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 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:

Tip

To view details of the score recursively in the arrays of objects, configure the settings in mongosh by running the following:

config.set('inspectDepth', Infinity)

Operator Examples

The following examples demonstrate how to retrieve a breakdown of the score using the $search scoreDetails option for the documents in the results for the text, near, compound, and embeddedDocument operator queries.

The following example uses the text 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 stage to retrieve a detailed breakdown of the score for each document in the results. The query uses the $limit stage to limit the results to three documents and the $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.

1db.movies.aggregate([
2  {
3    "$search": {
4      "text": {
5        "path": "title",
6        "query": "autumn"
7      },
8      "scoreDetails": true
9    }
10  },
11  {
12    "$limit": 3
13  },
14  {
15    "$project": {
16      "_id": 0,
17      "title": 1,
18      "score": { "$meta": "searchScore" },
19      "scoreDetails": { "$meta": "searchScoreDetails" }
20    }
21  }
22])
1[
2  {
3    title: 'Autumn Leaves',
4    score: 3.834893226623535,
5    scoreDetails: {
6      value: 3.834893226623535,
7      description: '$type:string/title:autumn [BM25Similarity], result of:',
8      details: [
9        {
10          value: 3.834893226623535,
11          description: 'score(freq=1.0), computed as boost * idf * tf from:',
12          details: [
13            {
14              value: 7.39188289642334,
15              description: 'idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:',
16              details: [
17                {
18                  value: 14,
19                  description: 'n, number of documents containing term',
20                  details: []
21                },
22                {
23                  value: 23529,
24                  description: 'N, total number of documents with field',
25                  details: []
26                }
27              ]
28            },
29            {
30              value: 0.5187978744506836,
31              description: 'tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:',
32              details: [
33                {
34                  value: 1,
35                  description: 'freq, occurrences of term within document',
36                  details: []
37                },
38                {
39                  value: 1.2000000476837158,
40                  description: 'k1, term saturation parameter',
41                  details: []
42                },
43                {
44                  value: 0.75,
45                  description: 'b, length normalization parameter',
46                  details: []
47                },
48                {
49                  value: 2,
50                  description: 'dl, length of field',
51                  details: []
52                },
53                {
54                  value: 2.868375301361084,
55                  description: 'avgdl, average length of field',
56                  details: []
57                }
58              ]
59            }
60          ]
61        }
62      ]
63    }
64  },
65  {
66    title: 'Late Autumn',
67    score: 3.834893226623535,
68    scoreDetails: {
69      value: 3.834893226623535,
70      description: '$type:string/title:autumn [BM25Similarity], result of:',
71      details: [
72        {
73          value: 3.834893226623535,
74          description: 'score(freq=1.0), computed as boost * idf * tf from:',
75          details: [
76            {
77              value: 7.39188289642334,
78              description: 'idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:',
79              details: [
80                {
81                  value: 14,
82                  description: 'n, number of documents containing term',
83                  details: []
84                },
85                {
86                  value: 23529,
87                  description: 'N, total number of documents with field',
88                  details: []
89                }
90              ]
91            },
92            {
93              value: 0.5187978744506836,
94              description: 'tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:',
95              details: [
96                {
97                  value: 1,
98                  description: 'freq, occurrences of term within document',
99                  details: []
100                },
101                {
102                  value: 1.2000000476837158,
103                  description: 'k1, term saturation parameter',
104                  details: []
105                },
106                {
107                  value: 0.75,
108                  description: 'b, length normalization parameter',
109                  details: []
110                },
111                {
112                  value: 2,
113                  description: 'dl, length of field',
114                  details: []
115                },
116                {
117                  value: 2.868375301361084,
118                  description: 'avgdl, average length of field',
119                  details: []
120                }
121              ]
122            }
123          ]
124        }
125      ]
126    }
127  },
128  {
129    title: 'Cheyenne Autumn',
130    score: 3.834893226623535,
131    scoreDetails: {
132      value: 3.834893226623535,
133      description: '$type:string/title:autumn [BM25Similarity], result of:',
134      details: [
135        {
136          value: 3.834893226623535,
137          description: 'score(freq=1.0), computed as boost * idf * tf from:',
138          details: [
139            {
140              value: 7.39188289642334,
141              description: 'idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:',
142              details: [
143                {
144                  value: 14,
145                  description: 'n, number of documents containing term',
146                  details: []
147                },
148                {
149                  value: 23529,
150                  description: 'N, total number of documents with field',
151                  details: []
152                }
153              ]
154            },
155            {
156              value: 0.5187978744506836,
157              description: 'tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:',
158              details: [
159                {
160                  value: 1,
161                  description: 'freq, occurrences of term within document',
162                  details: []
163                },
164                {
165                  value: 1.2000000476837158,
166                  description: 'k1, term saturation parameter',
167                  details: []
168                },
169                {
170                  value: 0.75,
171                  description: 'b, length normalization parameter',
172                  details: []
173                },
174                {
175                  value: 2,
176                  description: 'dl, length of field',
177                  details: []
178                },
179                {
180                  value: 2.868375301361084,
181                  description: 'avgdl, average length of field',
182                  details: []
183                }
184              ]
185            }
186          ]
187        }
188      ]
189    }
190  }
191]

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.

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 scoreDetails option for the documents in the results for the function expression example queries against the sample_mflix.movies collection.

1db.movies.aggregate([{
2  "$search": {
3    "text": {
4      "path": "title",
5      "query": "men",
6      "score": {
7        "function":{
8          "multiply":[
9            {
10              "path": {
11                "value": "imdb.rating",
12                "undefined": 2
13              }
14            },
15            {
16              "score": "relevance"
17            }
18          ]
19        }
20      }
21    },
22    "scoreDetails": true
23  }
24},
25{
26  $limit: 5
27},
28{
29  $project: {
30    "_id": 0,
31    "title": 1,
32    "score": { "$meta": "searchScore" },
33    "scoreDetails": {"$meta": "searchScoreDetails"}
34  }
35}])
[
  {
    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: []
        }
      ]
    }
  }
]
Back
Score Options
Next
sort
Rate this page

On this page