optionalFilters
'optionalFilters' => [ 'attribute:value', ['attribute1:value', 'attribute2:value'], ]
Can be used in these methods:
search,
browseObjects,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
browse_objects,
generate_secured_api_key,
add_api_key,
update_api_key
search,
browseObjects,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
browse_objects,
generate_secured_api_key,
add_api_key,
update_api_key
search,
browse,
generateSecuredApiKey,
addAPIKey,
updateAPIKey
search,
browseObjects,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
Browse,
GenerateSecuredApiKey,
AddApiKey,
UpdateApiKey
Search,
browse,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
BrowseObjects,
GenerateSecuredAPIKey,
AddAPIKey,
UpdateAPIKey
search,
browse index,
generateSecuredApiKey,
add key,
update key
About this parameter
Boost or bury records based on specific criteria, but without hiding those records.
Use optional filters to promote certain records.
The boolean syntax is the same as facetFilters
.
Use negative optional filters to:
- Promote records that don’t match a filter
- Demote records that do match a filter.
For example, to promote items that don’t belong to the books category, add a category:-Books
filter.
If you signed up for the Community, Essential, or Plus plans before December 15, 2018, you can only use one optional filter per query.
- Optional filters require the Filters criterion to be in your ranking formula (as it is by default).
- Optional filters are not compatible with virtual replicas and will lead to unexpected behaviors since virtual replicas solely rely on custom ranking to sort results.
- If you’re using exhaustive sorting or sort by attribute, optional filters are applied after the sort-by criteria. You can’t use them to boost items to the top of your ranking, as sort-by always takes precedence.
- You can’t perform numeric comparisons with optional filters.
Usage notes
Negation
If your facet value starts the -
character, you must escape it to prevent Algolia from interpreting it as a negative optional filter.
For example, to add a filter for the category -movie
, the negative optional filter should be category:\-movie
.
Advanced queries
Enabling advancedSyntax
lets users:
- Add double quotes around phrases in a query to specify that a record must contain that phrase.
- Prefix a word with a minus (
-
) character to specify that a record must not contain that phrase.
Examples
Apply optional filters on a search query
This example boosts all books written by John Doe.
1
2
3
4
5
6
$results = $index->search('query', [
'optionalFilters' => [
"category:Book",
"author:John Doe"
]
]);
Apply negative optional filters on a search query
This example demotes all books written by John Doe.
1
2
3
4
5
6
$results = $index->search('query', [
'optionalFilters' => [
"category:Book",
"author:-John Doe"
]
]);