Skip to main content
Optional filters are a powerful tool for influencing the ranking of search results. Use them to boost or bury records based on specific criteria, but without hiding those records. For example, on a website that handles fast food deliveries, if a user types “hungry” and clicks the “deliver quickly” option, the website will show the restaurants that can deliver the fastest at the top of the list but still show other restaurants. You can also use negative optional filters to demote records. For example, to lower the ranking of restaurants with poor reviews.
This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

​
Update your records

Since optional filters only work with exact matches, you might need to update your records. Using the fast food delivery website as an example, flag restaurants that can deliver within 20 minutes by adding a boolean attribute called can_deliver_quickly and set it to true or false for each record.
JSON
[
  {
    "name": "Pasta Bolognese",
    "restaurant": "Millbrook Deli",
    "delivery_waiting_time": 20,
    "can_deliver_quickly": true,
    "popularity": 80
  },
  {
    "name": "Pasta Bolognese",
    "restaurant": "The Hive",
    "delivery_waiting_time": 15,
    "can_deliver_quickly": true,
    "popularity": 80
  },
  {
    "name": "Pasta Bolognese",
    "restaurant": "Bert's Inn",
    "delivery_waiting_time": 40,
    "can_deliver_quickly": false,
    "popularity": 90
  }
]

​
How to apply optional filters

To use optional filters, you need to:
  • Set the attribute as an attributeForFaceting at indexing time. You can do this either through the API or the Algolia dashboard.
  • Add the optional filter to your query with the API.

​
Using the dashboard

Set the attribute to use for faceting in your Algolia dashboard:
  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index and go to the Configuration tab.
  4. Under Filtering and Faceting > Facets, click Add an attribute and select the optional filter attributes (for example, can_deliver_quickly).
  5. Save your changes.
You can test filters in the Visual Editor before using them in your code:
  1. In the sidebar, select [Enhance > Rules] Rules.
  2. Click New rule and select Visual Editor.
  3. Under Conditions, select Set query condition(s).
  4. Click Filters. In the Name field, enter the name of your optional filter (for example, can_deliver_quickly). In the Value field, enter true.
  5. Type something into the Query box, such as * (to display all matching records)
  6. Click Apply.
Using the example dataset and the query `*“, two out of three records will be displayed. Previewing filtering in Rules Visual Editor

​
Using the API

Set the attribute to use for faceting with attributesForFaceting. For example: 
var response = await client.SetSettingsAsync(
  "ALGOLIA_INDEX_NAME",
  new IndexSettings
  {
    AttributesForFaceting = new List { "can_deliver_quickly", "restaurant" },
  }
);
Send the optional filters with your query. For example: 
var response = await client.SearchSingleIndexAsync(
  "ALGOLIA_INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      OptionalFilters = new OptionalFilters(
        new List { new OptionalFilters("can_deliver_quickly:true") }
      ),
    }
  )
);
You can also add negative optional filters. For example, to demote a specific restaurant: 
var response = await client.SearchSingleIndexAsync(
  "ALGOLIA_INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      OptionalFilters = new OptionalFilters(
        new List { new OptionalFilters("restaurant:-Bert's Inn") }
      ),
    }
  )
);

​
Optional or facet filters

Whether to use optional filters or facet filters depends on your goals:
  • Use optional filters to boost records.
  • Use facet filters if you need to filter out records.

​
Optional filters, replicas and sorting

Optional filters are incompatible with virtual replicas and relevant sorting. Trying to use optional filters with virtual replicas leads to unexpected behavior.

​
See also

⌘I