Guides / Managing results / Rules / Merchandising and promoting items

Oct. 14, 2020

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 or disfavors 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 legacy plans (Community, Essential, Plus, signed up before December 15, 2018), optional filters are limited to only one per query.

Imagine you have the following dataset:

Copy
[
  {
    "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.

Copy
[
  {
    "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 optional filter with can_deliver_quickly=true.

Let’s assume your user has left a bad review for one of the restaurants, Bert’s Inn. We may want to push this item to the bottom of the list, so that it’s still available to the user, but the results are more relevant. You can do this with a negative optional filter on the restaurant’s name.

Using the API

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

Copy

1
2
3
4
5
6
$index->setSettings([
  'attributesForFaceting' => [
    "can_deliver_quickly",
    "restaurant"
  ]
]);

1
2
3
4
5
6
7
let settings = Settings()
  .set(\.attributesForFaceting, to: ["can_deliver_quickly", "restaurant"])
index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
final JSONObject res = index.setSettings(
  new JSONObject().put(
    "attributesForFaceting",
    new JSONArray()
      .put("can_deliver_quickly")
      .put("restaurant")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
IndexSettings settings = new IndexSettings
{
    AttributesForFaceting = new List<string>
    {
      "can_deliver_quickly",
      "restaurant"
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
8
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "can_deliver_quickly",
      "restaurant"
    ))
  )
}

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

Copy

1
2
3
4
5
$results = $index->search("hungry", [
  'optionalFilters' => [
    "can_deliver_quickly:true"
  ]
]);

1
2
3
4
5
6
7
8
let query = Query("hungry")
  .set(\.optionalFilters, to: ["can_deliver_quickly:true"])

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
var query = new Query()
{
  SearchQuery = "hungry",
  OptionalFilters = new List<List<string>>
  {
    new List<string> { "can_deliver_quickly:true" }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
client.execute {
  search into "myIndex" query Query(
    query = Some("hungry"),
    customParameters = Some(
      Map(
        "optionalFilters" -> Some(Seq(
          "can_deliver_quickly:true"
        ))
      )
    )
  )
}

If you want to disfavor a specific restaurant, you can add a negative optional filter on the restaurant attribute.

Copy

1
2
3
4
5
$results = $index->search("hungry", [
  'optionalFilters' => [
    "restaurant:-Bert's Inn"
  ]
]);

1
2
3
4
5
6
7
8
let query = Query("hungry")
  .set(\.optionalFilters, to: ["restaurant:-Bert's Inn"])

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
var query = new Query()
{
  SearchQuery = "hungry",
  OptionalFilters = new List<List<string>>
  {
    new List<string> { "restaurant:-Bert's Inn" }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
client.execute {
  search into "myIndex" query Query(
    query = Some("hungry"),
    customParameters = Some(
      Map(
        "optionalFilters" -> Some(Seq(
          "restaurant:-Bert's Inn"
        ))
      )
    )
  )
}

Using the Dashboard

You can set your attribute to be used for faceting in your Algolia dashboard:

Go to your dashboard and select your index.
Click the Configuration tab.
In the Facets subsection of Filtering and Faceting, click the “Add an attribute” button and select the can_deliver_quickly attribute from the dropdown.
Don’t forget to save your changes!

Regarding filters (or optional filters), you can’t set them to be applied directly in the dashboard since you can only filter at query time. However, you can test filters and optional filters in the dashboard before using them in your search code.

Go to your dashboard and select your index.
Click the Add Query Parameter button, which is just below the search bar.
Go to the Custom tab.
Add your filter as JSON: { "optionalFilters": "can_deliver_quickly:true" }.
Click Apply.

Note that you can alternatively use facet filters. Click the Add Query Parameter button, go to the Filters tab and enter your targeted facet filter(s).

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Optional Filters

On this page