Promote records with optional filters

Learn how to use optional filters to modify your custom ranking.

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.

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.

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:

4. Click the Configuration tab.

5. In the Facets subsection of Filtering and Faceting, click the “Add an attribute” button and select the optional filter attributes from the drop-down menu (for example, can_deliver_quickly).

6. Save your changes.

You can test filters in the Rules Visual Editor before using them in your code:

1. Go to the Algolia dashboard and select your Algolia application.

2. On the left sidebar, select Search.

3. Select your Algolia index:

4. Click Rules in the sidebar

5. Create a new Rule and choose Visual Editor.

6. Click the Set query condition(s) button under It all starts here.

7. Click Filters, and in Filter Name, enter the name of your optional filter (for example, can_deliver_quickly)

8. In Value, type true

9. Type something into the Query box, such as * (to display all matching records)

10. Click Apply.

Using the example dataset and the query * `, two out of three records will be displayed.

Using the API

Set the attribute to use for faceting with attributesForFaceting. For example:

Send the optional filters with your query. For example:

You can also add negative optional filters. For example, to demote a specific restaurant:

An alternative: facet filters

An alternative to optional filters is facet filters. To determine whether to use optional filters or facet filters, consider your specific goals:

• Use optional filters to boost records
• Use facet filters if you only need to filter out records.

Further reading

• Filter scoring
• Fuzzy search: optional filters