Modify the Score

Fields

The boost option takes the following fields:

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.

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

[
  {
    plot: 'Epic tale about two generations of men in a wealthy Finnish family, spanning from the 1960s all the way through the early 1990s. The father has achieved his position as director of the ...',
    title: 'Kites Over Helsinki',
    score: 12.2470121383667
  },
  {
    plot: 'Alex is Finlander married to an Italian who works as a taxi driver in Berlin. One night in his taxi come two men with a briefcase full of money. Unluckily for Alex, they are being chased by...',
    title: 'Helsinki-Naples All Night Long',
    score: 9.56808090209961
  },
  {
    plot: 'The recession hits a couple in Helsinki.',
    title: 'Drifting Clouds',
    score: 4.5660295486450195
  },
  {
    plot: 'Two teenagers from Helsinki are sent on a mission by their drug dealer.',
    title: 'Sairaan kaunis maailma',
    score: 4.041563034057617
  },
  {
    plot: 'A murderer tries to leave his criminal past in East Helsinki and make a new life for his family',
    title: 'Bad Luck Love',
    score: 3.6251673698425293
  }
]

1
db.movies.aggregate([
2
  {
3
    "$search": {
4
      "compound": {
5
        "should": [{
6
          "text": {
7
            "query": "Helsinki",
8
            "path": "plot"
9
          }
10
        },
11
        {
12
          "text": {
13
            "query": "Helsinki",
14
            "path": "title",
15
            "score": {
16
              "boost": {
17
                "path": "imdb.rating",
18
                "undefined": 3
19
              }
20
            }
21
          }
22
        }]
23
      }
24
    }
25
  },
26
  {
27
    "$limit": 5
28
  },
29
  {
30
    "$project": {
31
      "_id": 0,
32
      "title": 1,
33
      "plot": 1,
34
      "score": { "$meta": "searchScore" }
35
    }
36
  }
37
])

[
  {
    plot: 'Epic tale about two generations of men in a wealthy Finnish family, spanning from the 1960s all the way through the early 1990s. The father has achieved his position as director of the ...',
    title: 'Kites Over Helsinki',
    score: 24.902257919311523
  },
  {
    plot: 'Alex is Finlander married to an Italian who works as a taxi driver in Berlin. One night in his taxi come two men with a briefcase full of money. Unluckily for Alex, they are being chased by...',
    title: 'Helsinki-Naples All Night Long',
    score: 20.411907196044922
  },
  {
    plot: 'The recession hits a couple in Helsinki.',
    title: 'Drifting Clouds',
    score: 4.5660295486450195
  },
  {
    plot: 'Two teenagers from Helsinki are sent on a mission by their drug dealer.',
    title: 'Sairaan kaunis maailma',
    score: 4.041563034057617
  },
  {
    plot: 'A murderer tries to leave his criminal past in East Helsinki and make a new life for his family',
    title: 'Bad Luck Love',
    score: 3.6251673698425293
  }
]

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
    "$limit": 5
23
  },
24
  {
25
    "$project": {
26
      "_id": 0,
27
      "title": 1,
28
      "plot": 1,
29
      "score": { "$meta": "searchScore" }
30
    }
31
  }
32
])

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
]

Fields

The embedded option takes the following fields:

Examples

The following sample query uses an index named default on the sample_analytics.transactions collection. The index configures an embeddedDocuments type on documents in the transactions array and string type for transactions.symbol and transactions.transaction_code fields.

{
  "mappings": {
    "dynamic": true,
    "fields": {
     "transactions": {
        "dynamic": true,
        "fields": {
          "symbol": {
            "type": "string"
          },
          "transaction_code": {
            "type": "string"
          }
        },
        "type": "embeddedDocuments"
      }
    }
  }
}

The sample query on the transactions field, which contains an array of documents, includes a $limit stage to limit the output to 10 results and a $project stage to:

• Exclude all fields except account_id and transaction_count.

• Add a field named score that applies an aggregation strategy and further score modification.

  Note

  You can use function inside the score option of the embeddedDocument operator's operator. However, for function score expressions that require the path option, the numeric field that you specify as the path for the expression must be inside the embeddedDocument operator's path. For example, in the following example query, the field transactions.amount that is specified inside the score option of the compound operator on line 24 is inside in the embeddedDocument operator's path transactions on line 4.

The query searches for accounts that have bought AMD and multiplies the largest single AMD purchase (by number of shares) by the log1p value of the number of transactions that the account has made in this period. It ranks the accounts based on the following:

• Number of AMD bought in a single transaction

• Number of transactions in the last period

1
db.transactions.aggregate({
2
  "$search": {
3
    "embeddedDocument": {
4
      "path": "transactions",
5
      "operator": {
6
        "compound": {
7
          "must": [
8
            {
9
              "text": {
10
                "path": "transactions.symbol",
11
                "query": "amd"
12
              }
13
            },
14
            {
15
              "text": {
16
                "path": "transactions.transaction_code",
17
                "query": "buy"
18
              }
19
            }
20
          ],
21
          "score": {
22
            "function": {
23
              "path": {
24
                "value": "transactions.amount",
25
                "undefined": 1.0
26
              }
27
            }
28
          }
29
        }
30
      },
31
      "score": {
32
        "embedded": {
33
          "aggregate": "maximum",
34
          "outerScore": {
35
            "function": {
36
              "multiply": [
37
                {
38
                  "log1p": {
39
                    "path": {
40
                      "value": "transaction_count"
41
                    }
42
                  }
43
                },
44
                {
45
                  "score": "relevance"
46
                }
47
              ]
48
            }
49
          }
50
        }
51
      }
52
    }
53
  }
54
},
55
{ "$limit": 10 },
56
{
57
  "$project": {
58
    "_id": 0,
59
    "account_id": 1,
60
    "transaction_count": 1,
61
    "score": { $meta: "searchScore" }
62
  }
63
})

Atlas Search ranks accounts that have made many transactions in the last period and bought many AMD in a single transaction highly.

1
[
2
  { account_id: 467651, transaction_count: 99, score: 19982 },
3
  { account_id: 271554, transaction_count: 96, score: 19851.822265625 },
4
  { account_id: 71148, transaction_count: 99, score: 19840 },
5
  { account_id: 408143, transaction_count: 100, score: 19836.76953125 },
6
  { account_id: 977774, transaction_count: 98, score: 19822.64453125 },
7
  { account_id: 187107, transaction_count: 96, score: 19754.470703125 },
8
  { account_id: 492843, transaction_count: 97, score: 19744.998046875 },
9
  { account_id: 373169, transaction_count: 93, score: 19553.697265625 },
10
  { account_id: 249078, transaction_count: 89, score: 19436.896484375 },
11
  { account_id: 77690, transaction_count: 90, score: 19418.017578125 }
12
]

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.

Arithmetic

Constant

Gaussian

Path

Score

Unary

An arithmetic expression adds or multiplies a series of numbers. For example, you can use arithmetic expression to modify relevance ranking through a numeric field from a data enrichment pipeline. 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. For example: Arithmetic Expression Syntax "function": { "add": [ {"path": "rating"}, {"score": "relevance"} ] } In the previous example, 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. For example: Arithmetic Expression Syntax "function": { "multiply": [ { "path": { "value": "popularity", "undefined": 2.5 } }, { "score": "relevance" }, { "constant": 0.75 } ] } In the previous example, 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.

A constant expression allows a constant number in the function score. For example, you can use constant to modify relevance ranking through a numeric value from a data enrichment pipeline. It must include the following option:

Option	Type	Description
constant	float	Number that indicates a fixed value. Atlas Search supports negative values.

Example

Constant Expression Syntax

{
  "function": {
    "constant": -23.78
  }
}

A gaussian decay expression allows you to decay, or reduce by multiplying, the final scores of the documents based on the distance of a numeric field value from a specified origin point. decay is computed as:

click to enlarge

where sigma is computed to assure that the score takes the value decay at distance scale from origin±offset:

click to enlarge

For example, you can use gauss to adjust the relevant score of documents based on document freshness, or date influencing higher ranking. gauss takes the following options:

Field	Type	Necessity	Description
decay	double	Optional	Rate at which you want to multiply the scores. Value must be a positive number between 0 and 1 exclusive. If omitted, defaults to 0.5. For documents whose numeric field value (specified using path) is at a distance (specified using scale) away from origin plus or minus (±) offset, Atlas Search multiplies the current score using decay.
offset	double	Optional	Number to use to determine the distance from origin. The decay operation is performed only for documents whose distances are greater than origin plus or minus (±) offset. If ommitted, defaults to 0.
origin	double	Required	Point of origin from which to calculate the distance.
path	expression	Required	Name of the numeric field whose value you want to use to multiply the base score.
scale	double	Required	Distance from origin plus or minus (±) offset at which scores must be multiplied.

Example

Gaussian Expression Syntax

{
  "function": {
    "gauss": {
      "path": {
        "value": "rating",
        "undefined": 50
      },
      "origin": 95,
      "scale": 5,
      "offset": 5,
      "decay": 0.5
    }
  }
}

Suppose the max rating is 100. Atlas Search uses the rating field in the documents to decay the score:

• Retains the current score for documents with rating between 90 to 100.

• Multiplies the current score by 0.5 for documents with a rating lower than 90.

• Multiplies the current score by 0.25 for documents with a rating lower than 85, and so on.

A path expression incorporates an indexed numeric field value into a function score. It can either be a string or an object.

If string, the value is the name of the numeric field to search over for the path expression.

Example

Path Expression Syntax

{
  "function": {
    "path": "rating"
  }
}

Atlas Search incorporates the numeric value of the rating field in the final score of the document.

If object, the path expression takes the following options:

Option	Type	Necessity	Description
value	string	Required	Name of numeric field. Field can contain negative numeric values.
undefined	float	Optional	Value to use if the numeric field specified using value is missing in the document. If omitted, defaults to 0.

Example

Path Expression Syntax

{
  "function": {
    "path": {"value": "quantity", "undefined": 2}
  }
}

Atlas Search incorporates numeric value of the quantity field or 2, if the quantity field is not present in the document, in the final score of the document.

A path expression can't be an array and can't contain regex or wildcard in the path.

A score expression represents the relevance score, which is the score Atlas Search assigns documents based on relevance, of the query. It is the same as the current score of the document. It must include the following option:

Option	Type	Description
score	string	Value of relevance score of the query. Value must be relevance.

Example

Score Expression Syntax

{
  "function": {
    "score": "relevance"
  }
}

A unary expression is an expression that takes a single argument. In Atlas Search, you can use unary expressions to calculate the log10(x) or log10(x+1) of a specified number. For example, you can use log1p to influence the relevance score by document popularity score. It must include one of the following options:

Option	Type	Description
log	expression	Calculates the log10 of a number. For example: Unary Expression Syntax { "function": { "log": { "multiply": [ {"path": "popularity"}, {"constant": 0.5}, {"score": "relevance"} ] } } } In the previous example, Atlas Search calculates the log10 of the arithmetic expression that uses the multiply option to calculate the product of the numeric value of the popularity field, the constant value of 0.5, and the relevance score assigned by Atlas Search. If the expression specified for the log option evaluates to less than or equal to 0, then the log evaluates to undefined. For example: Unary Expression syntax { "function": { "log": { "constant": -5.1 } } } In the previous example, Atlas Search evaluates the the log10 of the constant expression -5.1 to undefined. Therefore, the final score of the document is 0.
log1p	expression	Adds 1 to the number and then calculates its log10. For example: Unary Expression Syntax { "function": { "log1p": { "path": { "value": "rating", "undefined": 4 } } } } In the previous example, Atlas Search adds 1 to the expression that uses the path option to evaluate to the numeric value of the rating field, then calculates the log10 of the resulting sum.

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.

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" }
  }
}])

{ "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 }

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "path": "title",
        "query": "men",
        "score": {
          "function":{
            "constant": 3
          }
        }
      }
    }
  },
  {
    $limit: 5
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      "score": { "$meta": "searchScore" }
    }
  }
])

{ "title" : "Men Without Women", "score" : 3 }
{ "title" : "One Hundred Men and a Girl", "score" : 3 }
{ "title" : "Of Mice and Men", "score" : 3 }
{ "title" : "All the King's Men", "score" : 3 }
{ "title" : "The Men", "score" : 3 }

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "path": "title",
        "query": "shop",
        "score": {
          "function":{
            "gauss": {
              "path": {
                "value": "imdb.rating",
                "undefined": 4.6
              },
              "origin": 9.5,
              "scale": 5,
              "offset": 0,
              "decay": 0.5
            }
          }
        }
      }
    }
  },
  {
    "$limit": 10
  },
  {
    "$project": {
      "_id": 0,
      "title": 1,
      "imdb.rating": 1,
      "score": { "$meta": "searchScore" }
    }
  }
])

[
  { title: 'The Shop Around the Corner', imdb: { rating: 8.1 }, score: 0.9471074342727661 },
  { title: 'Exit Through the Gift Shop', imdb: { rating: 8.1 }, score: 0.9471074342727661 },
  { title: 'The Shop on Main Street', imdb: { rating: 8 }, score: 0.9395227432250977 },
  { imdb: { rating: 7.4 }, title: 'Chop Shop', score: 0.8849083781242371 },
  { title: 'Little Shop of Horrors', imdb: { rating: 6.9 }, score: 0.8290896415710449 },
  { title: 'The Suicide Shop', imdb: { rating: 6.1 }, score: 0.7257778644561768 },
  { imdb: { rating: 5.6 }, title: 'A Woman, a Gun and a Noodle Shop', score: 0.6559237241744995 },
  { title: 'Beauty Shop', imdb: { rating: 5.4 }, score: 0.6274620294570923 }
]

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "path": "title",
        "query": "shop"
      }
    }
  },
  {
    "$limit": 10
  },
  {
    "$project": {
      "_id": 0,
      "title": 1,
      "imdb.rating": 1,
      "score": { "$meta": "searchScore" }
    }
  }
])

[
  { title: 'Beauty Shop', imdb: { rating: 5.4 }, score: 4.111973762512207 },
  { imdb: { rating: 7.4 }, title: 'Chop Shop', score: 4.111973762512207 },
  { title: 'The Suicide Shop', imdb: { rating: 6.1 }, score: 3.5363259315490723 },
  { title: 'Little Shop of Horrors', imdb: { rating: 6.9 }, score: 3.1020588874816895 },
  { title: 'The Shop Around the Corner', imdb: { rating: 8.1 }, score: 2.762784481048584 },
  { title: 'The Shop on Main Street', imdb: { rating: 8 }, score: 2.762784481048584 },
  { title: 'Exit Through the Gift Shop', imdb: { rating: 8.1 }, score: 2.762784481048584 },
  { imdb: { rating: 5.6 }, title: 'A Woman, a Gun and a Noodle Shop', score: 2.0802340507507324 }
]

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

{ "title" : "12 Angry Men", "score" : 8.899999618530273 }
{ "title" : "The Men Who Built America", "score" : 8.600000381469727 }
{ "title" : "No Country for Old Men", "score" : 8.100000381469727 }
{ "title" : "X-Men: Days of Future Past", "score" : 8.100000381469727 }
{ "title" : "The Best of Men", "score" : 8.100000381469727 }

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

{ "title" : "Men...", "score" : 3.4457783699035645 }
{ "title" : "The Men", "score" : 2.8848698139190674 }
{ "title" : "Simple Men", "score" : 2.8848698139190674 }
{ "title" : "X-Men", "score" : 2.8848698139190674 }
{ "title" : "Mystery Men", "score" : 2.8848698139190674 }

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

{ "title" : "12 Angry Men", "score" : 0.9493899941444397 }
{ "title" : "The Men Who Built America", "score" : 0.9344984292984009 }
{ "title" : "No Country for Old Men", "score" : 0.9084849953651428 }
{ "title" : "X-Men: Days of Future Past", "score" : 0.9084849953651428 }
{ "title" : "The Best of Men", "score" : 0.9084849953651428
}