optionalFilters

Promote or demote records in the search results.

• Type: list<string>
• Default: []
• Scope: search

Optional filters use the same syntax as facetFilters, but they behave differently:
They don’t exclude records. Instead, they influence the record’s ranking.

Use them to promote or demote results without filtering them out. For example:

• To promote books by John Doe: ["category:Book", "author:John Doe"]
• To demote items from the Books category: ["category:-Books"]

Usage

• Optional filters only have an effect if the Filters ranking criterion is present in your ranking formula (default behavior).
• They’re applied after any sorting criteria (sorting by attribute)
• On virtual replicas, optional filters are applied after the replica’s relevant sort.
• Numeric comparisons aren’t supported.
• If the Filters ranking criterion is applied before custom ranking (default), the optional filters take precedence over the custom ranking in the tie-breaking algorithm.
• To use an attribute as an optional filter, it must be included in the attributesForFaceting setting.

Escape minus signs

If a facet value starts with - and isn’t a negative filter, escape it: category:\-movie.

Example

Current API clients

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "ALGOLIA_INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      OptionalFilters = new OptionalFilters(
        new List<OptionalFilters> { new OptionalFilters("can_deliver_quickly:true") }
      ),
    }
  )
);

Legacy API clients

C#

var query = new Query()
{
  SearchQuery = "query",
  OptionalFilters = new List>
  {
    new List { "category:Book", "author:John Doe" }
  }
};