Docs Menu

Docs Home → Launch & Manage MongoDB → MongoDB Atlas

Return the Score Details

On this page

  • Syntax
  • Options
  • Output
  • Factors That Contribute to the Score
  • Examples
  • Operator Examples
  • Custom Score Examples

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. 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, Atlas Search returns a detailed breakdown of the score for each document in the result. 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 scoring formula varies based on the operator used in the query. For example, Atlas Search uses the following scoring formula for a compound query with text and near operators: BM25Similarity + distance decay function.

Note

The top-level value shows the entire score of the result document, and is equal to the value of $searchScore.

description
string

Subset of the scoring formula including details about how the document was scored and factors considered in calculating the score.

Note

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

For BM25Similarity, the score is computed as boost * idf * tf. Atlas Search takes into account the following BM25Similarity factors for calculating the score:

boost
Increase the importance of the term.
freq
Frequency of the query term.
idf

Inverse document frequency of the query. Atlas Search computes the frequency using the following formula:

log(1 + (N - n + 0.5) / (n + 0.5))

where:

  • N is the total number of documents with the field.

  • n is the number of documents containing the term.

tf

Term frequency. Atlas Search computes the frequency using the following formula:

freq / (freq + k1 * (1 - b + b * dl / avgdl))

where:

  • freq is the number of occurrences of the term within the document.

  • k1 is the term saturation parameter that is specified internally. It affects how much the score increases with each reoccurrence of the term.

  • avgdl is the average length of the field across all documents.

  • dl is the length of the field in the document.

  • b is the length normalization parameter that is also set internally. b is multiplied by the ratio of dl to avgdl. If b increases, the effects of the ratio of dl to avgdl is amplified.

For distance decay function, the score is computed as pivot / (pivot + abs(fieldValue - origin)). Atlas Search takes into account the following factors for calculating the score:

origin
Value to search near. This is the origin point from which the proximity of the results are measured.
fieldValue
Value of the field that you are querying in the document. The closer the fieldValue is to origin, the higher the score of the near query.
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.

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.

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.

← Modify the Score
Normalize the Score →

On this page