Optional Filters

Filters don’t have to be exclusive. They don’t only remove records that don’t match the filter values. Sometimes, you may want to use filters in a way that only favors records that match with those that don’t match a filter.

For example, if someone uses the term “hungry” in their search query and clicks on the “deliver quickly” facet, you may interpret this as them looking for restaurants that can deliver as quickly as possible. Yet, you wouldn’t necessarily want to filter out other restaurants, especially if most of them can’t deliver right away. You can achieve this with Algolia’s optionalFilters feature.

For all customers on legacy plans (Community, Essential, Plus), who signed up before December 15, 2018, optional filters are limited to only one per query. Free plans do not have access to optional filters. For all other plans (Enterprise, Pro, Starter), optional filters are unlimited.

Imagine you have the following dataset:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[
  {
    "name": "Pasta Bolognese",
    "restaurant": "Millbrook Deli",
    "delivery_waiting_time": 20,
    "popularity": 80
  },
  {
    "name": "Pasta Bolognese",
    "restaurant": "The Hive",
    "delivery_waiting_time": 15,
    "popularity": 80
  },
  {
    "name": "Pasta Bolognese",
    "restaurant": "Bert's Inn",
    "delivery_waiting_time": 40,
    "popularity": 90
  }
]

Let’s say you have set descending custom ranking on popularity, and ascending custom ranking on delivery_waiting_time. If a user searches for “pasta bolognese”, the first result would be “Bert’s Inn”, because it has higher popularity. Then you would have “The Hive” and “Millbrook Deli” because they have the same popularity, so the engine would move on to delivery_waiting_time to tie break. The top result would, therefore, be the most popular one, not necessarily the one that can deliver as fast as possible.

To push the records that can deliver quickly first, regardless of the custom ranking, we can use optional filters. The optionalFilters parameter only applies on exact matches, you can’t do numeric comparisons like with filters. Therefore, you need to alter your dataset so you can match on exact values.

For example, if you think that a waiting time of 20 minutes or less is quick enough, you could create an attribute can_deliver_quickly and set it to true for each record that has a delivery_waiting_time of “20” or less.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[
  {
    "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
  }
]

When users click on the “deliver quickly” facet, you want to automatically boost every record in which can_deliver_quickly is equal to true. To do so, you first need to set can_deliver_quickly in your list of attributes for faceting. Then you would create an filter with can_deliver_quickly=true.

Using the API

First, you need to set can_deliver_quickly as attributesForFaceting. This happens at indexing time.

api_faceting_optional_example

Then, you can send the optional filters with your query.

1
2
3
algolia.search("hungry", {
  optionalFilters: ["can_deliver_quickly:true"]
});

Using the Dashboard

You can set your attribute for faceting in your Algolia dashboard.

  • Go to your dashboard and select your index.
  • Click the Display tab.
  • In the Faceting section, click the Add an attribute button and select the “can_deliver_quickly” attribute in the Attributes for faceting dropdown.
  • Don’t forget to save your changes.

Regarding filters, you can’t set them directly in the dashboard since you can only filter at query time. Yet, you can test for specific filters in the dashboard before using them in your search code.

  • Go to your dashboard and select your index.
  • Click the Add Query Param button.
  • Click the Custom tab.
  • Add your filter as JSON: { "optionalFilters": "can_deliver_quickly:true" }.
  • Click Apply.

Note that you can also use facet filters to do the same thing. Click the Add Query Param button, go to the Filters tab and select the right facet filter(s) in the Facet filters dropdown.

Did you find this page helpful?