Optional Filters: Scoring

About optionalFilters

For performance reasons, filter scoring should not be used on searches that may return more than 100,000 results.

Optional filters divide records into two sets:

• those matching the optional filter
• all the rest

Adding scores to optionalFilters

Filter scoring is a way to create more nuanced ranking, by specifying different scores for different filters. For example, consider a scenario in which a user prefers the following ranking:

• Apple products should be returned first
• Samsung products should be returned next
• All other products should be returned last

The query could be more precise by giving each filter a score:

1
2
3
algolia.search("phone", {
  optionalFilters: ["brand:apple<score=2>", "brand:samsung<score=1>"]
});

Doing the same with filters

Filter scoring can also be used with filters and facetFilters.

In fact, you can do the same kind of scoring with filters. The only difference between filters and optional filters are that records which don’t match any filter will not be returned when using filters; whereas with optional filters, records that don’t match the filters will be returned but ranked lower than those that match the filter.

Note that filter and facet scoring only works with OR conditions.

1
2
3
algolia.search("phone", {
  filters: "brand:apple<score=2> OR brand:samsung<score=1>"]
});

1
2
3
4
5
algolia.search("phone", {
  facetFilters: [
    ["brand:apple<score=2>", "brand:samsung<score=1>"]
  ]
});

Filter scoring is fully available under all plans.

How the scores are calculated

The calculation of the total score, which will be used in the filters rule of the above Ranking Formula, follows two rules:

• When no score is specified, it defaults to 1
• When you specify scores on multiple filters, the global score is equal to the highest score of the matched filters

Consider these two examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
optionalFilters = ["brand:Apple", "brand:Samsung<score=2>"]
/* Will rank results in this order:
1. Samsung (score = 2)
2. Apple (score = 1)
3. other brands (score = 0) */

optionalFilters = ["brand:Apple", "brand:Samsung<score=2>", "users:user42<score=3>"]
/* Will rank results in this order:
1. Samsung and user42 (score = 3)
2. Apple and user42 (score = 3)
3. other brands and user42 (score = 3)
4. Samsung, no match on user42 (score = 2)
5. Apple, no match on user42 (score = 1)
6. other results (score = 0) */

Calculate the sum of “OR” Scores

As described above, optionalFilters considers only the highest scoring matched filter. However, this behavior can be changed with sumOrFiltersScores. Applied at query-time, this parameter tells the engine to sum the scores of matched filters instead of only taking the highest scoring match. With sumOrFiltersScores applied, the above scoring would now be a bit different:

1
2
3
4
5
6
7
8
9
optionalFilters = ["brand:Apple", "brand:Samsung<score=2>", "users:user42<score=3>"]
/* Will rank results in this order:
1. Samsung and user42 (score = 5)
2. Apple and user42 (score = 4)
3. other brands and user42 (score = 3)
4. Samsung, no match on user42 (score = 2)
5. Apple, no match on user42 (score = 1)
6. other results (score = 0) */