Scoring¶

Every document returned by an Atlas Search query is assigned a score based on relevance, and the documents included in a result set are returned in order from highest score to lowest.

Behavior¶

Many factors can influence a document's score, including:

The position of the search term in the document,
The frequency of occurrence of the search term in the document,
The type of operator the query uses,
The type of analyzer the query uses.

The score assigned to a returned document is part of the document's metadata. You can include each returned document's score along with the result set by using a $project in your aggregation pipeline.

The following example query uses a $project stage to add a field named score to the returned documents:

1 db.movies.aggregate([
2   {
3     $search: {
4       "text": {
5         "query": "Helsinki",
6         "path": "plot"
7       }
8     }
9   },
10   {
11     $project: {
12       plot: 1,
13       title: 1,
14       score: { $meta: "searchScore" }
15     }
16   }
17 ])

More information about the Lucene scoring algorithm can be found in the Lucene documentation.

Score Modifiers¶

The following score modifying options are available to the search and term operators.

`boost`¶

The boost option multiplies a result's base score by a given number or the value of a numeric field in the documents.

Note

The boost and constant options can't be used together.
The boost option with path is the same as multiplying using function option with path expression.

Fields¶

The boost option takes the following fields:

Field	Type	Necessity	Description
`value`	float	Conditional	Number to multiply the default base score by. Value must be a positive number. Either `value` or `path` is required, but you can't specify both.
`path`	string	Conditional	Name of the numeric field whose value to multiply the default base score by. Either `path` or `value` is required, but you can't specify both.
`undefined`	float	Optional	Numeric value to substitute for `path` if the numeric field specified through `path` is not found in the documents. If omitted, defaults to `0`. You can specify this only if you specify `path`.

Examples¶

The following examples use the default index on the sample_mflix.movies collection to query the title field. The sample queries include a $project stage to exclude all fields except title and score.

In the following example, the text operator uses score with the boost option to multiply the score results by 3.

1 db.movies.aggregate([
2   {
3     $search: {
4       "text": {
5         "query": "Helsinki",
6         "path": "title",
7         "score": { "boost": { "value": 3 } }
8       }
9     }
10   },
11   {
12     $project: {
13       "_id": 0,
14       "title": 1,
15       "score": { "$meta": "searchScore" }
16     }
17   }
18 ])

The above query returns the following results, in which the score is multiplied by 3 from its base value:

{ "title" : "Kites Over Helsinki", "score" : 12.247001647949219 }
{ "title" : "Helsinki-Naples All Night Long", "score" : 9.568056106567383 }

`constant`¶

The constant option replaces the base score with a given number. In the following example, the term operator uses score with the constant option to replace all score results with 5.

1 db.movies.aggregate([
2   {
3     $search: {
4       "text": {
5         "query": "tower",
6         "path": "title",
7         "score": { "constant": { "value": 5 } }
8       }
9     }
10   },
11   {
12     $project: {
13       "_id": 0,
14       "title": 1,
15       "score": { "$meta": "searchScore" }
16     }
17   }
18 ])

The above query returns the following results, in which the score is replaced with the specified constant value:

1 { "title": "Tower Heist", "score": 5 }
2 { "title": "Tokyo Tower", "score": 5 }
3 { "title": "The Leaning Tower", "score": 5 }
4 { "title" : "Tower Block", "score" : 5 }
5 { "title": "Ivory Tower", "score": 5 }

Note

The constant and boost options may not be used together.

`function`¶

The function option allows the value of a numeric field to alter the final score of the document. You can specify the numeric field for computing the final score through an expression.

Expressions¶

An arithmetic expression adds or multiplies a series of numbers. It must include one of the following options:

Option

Type

Description

add

array of expressions

Adds a series of numbers. Takes an array of expressions, which can have negative values. Array length must be greater than or equal to 2.

Example

"function": {
  "add": [
    {"path": "rating"},
    {"score": "relevance"}
  ]
}

Atlas Search uses the path and score expressions to add the following:

Numeric value of the rating field or 0, if the rating field is not present in the document
Relevance score, which is the score Atlas Search assigns based on relevance

multiply

array of expressions

Multiplies a series of numbers. Takes an array of expressions, which can have negative values. Array length must be greater than or equal to 2.

Example

"function": {
  "multiply": [
    {
      "path": {
        "value": "popularity",
        "undefined": 2.5
      }
    },
    {"score": "relevance"},
    {"constant": 0.75}
  ]
}

Atlas Search uses the path, score, and constant expressions to alter the final score of the document. It multiplies the following:

Numeric value of the path expression, which is the numeric value of the popularity field or 2.5, if the popularity field is not present in the document
Relevance score, which is the score Atlas Search assigns based on relevance
Constant value of 0.75

Note

You can't replace an arithmetic expression that evaluates to undefined with a constant value.

Examples¶

The following examples use the default index on the sample_mflix.movies collection to query the title field. The sample queries include a $limit stage to limit the output to 5 results and a $project stage to exclude all fields except title and score.

Example

In this example, the text operator uses score with the function option to multiply the following:

Numeric value of the path expression, which is the value of the imdb.rating field in the documents or 2, if the imdb.rating field is not in the document
Relevance score, or the current score of the document

db.movies.aggregate([{
  "$search": {
    "text": {
      "path": "title",
      "query": "men",
      "score": {
        "function":{
          "multiply":[
            {
              "path": {
                "value": "imdb.rating",
                "undefined": 2
              }
            },
            {
              "score": "relevance"
            }
          ]
        }
      }
    }
  }
},
{
  $limit: 5
},
{
  $project: {
    "_id": 0,
    "title": 1,
    "score": { "$meta": "searchScore" }
  }
}])

The preceding query returns the following results, in which the score is replaced with the specified function value:

{ "title" : "Men...", "score" : 23.431293487548828 }
{ "title" : "12 Angry Men", "score" : 22.080968856811523 }
{ "title" : "X-Men", "score" : 21.34803581237793 }
{ "title" : "X-Men", "score" : 21.34803581237793 }
{ "title" : "Matchstick Men", "score" : 21.05954933166504 }

Give Feedback

← Performance Considerations Highlighting →

1	db.movies.aggregate([
2	{
3	$search: {
4	"text": {
5	"query": "Helsinki",
6	"path": "plot"
7	}
8	}
9	},
10	{
11	$project: {
12	plot: 1,
13	title: 1,
14	score: { $meta: "searchScore" }
15	}
16	}
17	])

1	{ "title": "Tower Heist", "score": 5 }
2	{ "title": "Tokyo Tower", "score": 5 }
3	{ "title": "The Leaning Tower", "score": 5 }
4	{ "title" : "Tower Block", "score" : 5 }
5	{ "title": "Ivory Tower", "score": 5 }

Scoring¶

Behavior¶

Score Modifiers¶

boost¶

Fields¶

Examples¶

constant¶

function¶

Expressions¶

Examples¶

`boost`¶

`constant`¶

`function`¶