Customize the Score in Results

On this page

Behavior

Options
boost
Fields
Examples
constant
Examples
function
Expressions
Examples

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. After a $project stage, you do not need to include a descending $sort because Atlas Search returns the documents from highest score to lowest by default.

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.

Options

The following score modifying options are available to all operators. For details and examples, click any of the following options:

boost
constant
function

`boost`

The boost option multiplies a result's base score by a given number or the value of a numeric field in the documents. For example, you can use boost to increase the importance of certain matching documents in the result.

Note

The boost and constant options can't be used together.
The boost option with path is the same as multiplying using the function option with a 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 movies collection in the sample_mflix database. If you have the sample dataset on your cluster, you can create the Atlas Search default index and run the example queries on your cluster.

The sample compound queries demonstrate how to increase the importance of one search criteria over another. The queries include a $project stage to exclude all fields except title and score.

`constant`

The constant option replaces the base score with a specified number.

Note

The constant and boost options may not be used together.

Examples

The following example uses the default index on the sample_mflix.movies collection to query the plot and title fields using the compound operator. In the query, the text operator uses score with the constant option to replace all score results with 5 for results that match the query against the title field only.

1 db.movies.aggregate([
2   {
3     $search: {
4       "compound": {
5         "should": [{
6           "text": {
7             "query": "tower",
8             "path": "plot"
9           }
10         },
11         {
12           "text": {
13             "query": "tower",
14             "path": "title",
15             "score": { "constant": { "value": 5 } }
16           }
17         }]
18       }
19     }
20   },
21   {
22     $project: {
23       "_id": 0,
24       "title": 1,
25       "score": { "$meta": "searchScore" }
26     }
27   }
28 ])

The above query returns the following results, in which the score for documents that match the query against the title field only is replaced with the specified constant value:

1 [
2   {
3     plot: 'Several months after witnessing a murder, residents of Tower Block 31 find themselves being picked off by a sniper, pitting those lucky enough to be alive into a battle for survival.',
4     title: 'Tower Block',
5     score: 8.15460205078125
6   },
7   {
8     plot: "When a group of hard-working guys find out they've fallen victim to their wealthy employer's Ponzi scheme, they conspire to rob his high-rise residence.",
9     title: 'Tower Heist',
10     score: 5
11   },
12   {
13     plot: 'Toru Kojima and his friend Koji are young student boys with one thing in common - they both love to date older women. Koji is a playboy with several women, young and older, whereas Toru is a romantic with his heart set on on certain lady.',
14     title: 'Tokyo Tower',
15     score: 5
16   },
17   {
18     plot: 'A middle-aged mental patient suffering from a split personality travels to Italy where his two personalities set off all kinds of confusing developments.',
19     title: 'The Leaning Tower',
20     score: 5
21   },
22   {
23     plot: 'A documentary that questions the cost -- and value -- of higher education in the United States.',
24     title: 'Ivory Tower',
25     score: 5
26   }
27 ]

`function`

The function option allows you to alter the final score of the document using a numeric field . You can specify the numeric field for computing the final score through an expression. If the final result of the function score is less than 0, Atlas Search replaces the score with 0.

Expressions

Use the following expressions with the function option to alter the final score of the document:

Arithmetic expressions, which add or multiply a series of numbers.
Constant expressions, which allow a constant number in the function score.
Gaussian decay expressions, which decay, or reduces, the scores by multiplying at a specified rate.
Path expressions, which incorporate an indexed numeric field value into a function score.
Score expressions, which return the relevance score assigned by Atlas Search.
Unary expressions, which are expressions that take a single argument. In Atlas Search, you can calculate the log10(x) or log10(x+1) of a specified number.

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.

← Construct a Query Path Highlight Search Terms in Results →

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	db.movies.aggregate([
2	{
3	$search: {
4	"compound": {
5	"should": [{
6	"text": {
7	"query": "tower",
8	"path": "plot"
9	}
10	},
11	{
12	"text": {
13	"query": "tower",
14	"path": "title",
15	"score": { "constant": { "value": 5 } }
16	}
17	}]
18	}
19	}
20	},
21	{
22	$project: {
23	"_id": 0,
24	"title": 1,
25	"score": { "$meta": "searchScore" }
26	}
27	}
28	])

1	[
2	{
3	plot: 'Several months after witnessing a murder, residents of Tower Block 31 find themselves being picked off by a sniper, pitting those lucky enough to be alive into a battle for survival.',
4	title: 'Tower Block',
5	score: 8.15460205078125
6	},
7	{
8	plot: "When a group of hard-working guys find out they've fallen victim to their wealthy employer's Ponzi scheme, they conspire to rob his high-rise residence.",
9	title: 'Tower Heist',
10	score: 5
11	},
12	{
13	plot: 'Toru Kojima and his friend Koji are young student boys with one thing in common - they both love to date older women. Koji is a playboy with several women, young and older, whereas Toru is a romantic with his heart set on on certain lady.',
14	title: 'Tokyo Tower',
15	score: 5
16	},
17	{
18	plot: 'A middle-aged mental patient suffering from a split personality travels to Italy where his two personalities set off all kinds of confusing developments.',
19	title: 'The Leaning Tower',
20	score: 5
21	},
22	{
23	plot: 'A documentary that questions the cost -- and value -- of higher education in the United States.',
24	title: 'Ivory Tower',
25	score: 5
26	}
27	]