🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API Reference / API Parameters / optionalFilters
Type: list of strings
Engine default: []
Parameter syntax
'optionalFilters' => [
    'attribute:value',
    ['attribute1:value', 'attribute2:value'],
]

Can be used in these methods:

About this parameter

Boost or bury records based on specific criteria, but without hiding those records.

Use optional filters to promote certain records.

Use negative optional filters to:

  • Promote records that don’t match a filter
  • Demote records that do match a filter.

Optional filters aren’t available on the Grow plan.

If you signed up for the Community, Essential, or Plus plans before December 15, 2018, you can only use one optional filter per query.

Usage notes

  • Optional filters require the Filters criterion to be in your ranking formula (as it is by default).

  • Optional filters are ignored on virtual replicas 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.

  • The boolean syntax is the same as facetFilters.

  • You can’t perform numeric comparisons with optional filters.

  • Negative optional filters use the - syntax to boost items that don’t match your optional filter. For example, to promote items that don’t belong to the books category, add a category:-Books filter.

  • 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.

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"
  ]
]);
Did you find this page helpful?