Return the Score Details
On this page
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 totrue
, 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: NoteThe top-level |
description | string | Subset of the scoring formula including details about how the document was scored and factors considered in calculating the score. NoteThe top-level 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:
where:
| |
tf | Term frequency. Atlas Search computes the frequency using the following formula:
where:
|
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:
Queries run using text, near, compound, and embeddedDocument operators.
Queries with scores modified using
function
option expressions.
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.