Promote records with optional filters

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.

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
  }
]

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:

Go to the Algolia dashboard and select your Algolia application.
On the left sidebar, select Search.
Select your Algolia index:
Click the Configuration tab.
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).
Save your changes.

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

Go to the Algolia dashboard and select your Algolia application.
On the left sidebar, select Search.
Select your Algolia index:
Click Rules in the sidebar
Create a new Rule and choose Visual Editor.
Click the Set query condition(s) button under It all starts here.
Click Filters, and in Filter Name, enter the name of your optional filter (for example, can_deliver_quickly)
In Value, type true
Type something into the Query box, such as * (to display all matching records)
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:

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
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 {
  setSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "can_deliver_quickly",
      "restaurant"
    ))
  )
}

Send the optional filters with your query. For example:

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"
        ))
      )
    )
  )
}

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

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"
        ))
      )
    )
  )
}

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.

Promote records with optional filters

On this page

Update your records

How to apply optional filters

Using the dashboard

Using the API

An alternative: facet filters

Further reading

On this page