Optional Filters: Scoring
On this page
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) */