Promote records with optional filters

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 in attributesForFaceting at indexing time. You can do this either through the API or the Algolia dashboard.
Add the optional filter through a rule or send it with your query using 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 .
On the left sidebar, select Search.
Select your Algolia index and go to the Configuration tab.
Under Filtering and Faceting > Facets, click Add an attribute and select the optional filter attributes (for example, can_deliver_quickly).
Save your changes.

You can create a rule to boost records where can_deliver_quickly is true using either the Visual Editor or the Manual Editor.

Visual Editor
Manual Editor

Open Rules and select New rule > Visual Editor.
In Conditions, select Create conditionless rule and click Apply to apply the boost to every search. To limit the boost to specific queries, select Set query condition(s) instead.
In Consequences, select Boost categories. Select can_deliver_quickly as the attribute and true as its value, then click Apply.
Preview the results with an empty query, click Review and Publish, and click Publish.

Open Rules, select Create your first rule or New rule, and select Manual Editor.
In Condition(s), remove the default condition to make the rule apply to every search. To limit the boost to specific queries, configure a query condition instead.
In Consequence(s), click Add consequence and select Add Query Parameter. Enter { "optionalFilters": ["can_deliver_quickly:true"] }.
Save your changes.

Using the example dataset, the rule boosts records where can_deliver_quickly is true, while the other record remains in the results. To demote records instead, use Bury categories in the Visual Editor. For example, select can_deliver_quickly as the attribute and false as its value. In the Manual Editor, use Add Query Parameter with { "optionalFilters": ["can_deliver_quickly:-false"] } for the same effect.

Using the API

To run the code examples on this page, install the latest API client. Set the attribute to use for faceting with attributesForFaceting. For example:

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    AttributesForFaceting = new List<string> { "can_deliver_quickly", "restaurant" },
  }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    attributesForFaceting: [
      "can_deliver_quickly",
      "restaurant",
    ],
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetAttributesForFaceting(
    []string{"can_deliver_quickly", "restaurant"})))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings(
  "INDEX_NAME",
  new IndexSettings().setAttributesForFaceting(Arrays.asList("can_deliver_quickly", "restaurant"))
);

const response = await client.setSettings({
  indexName: 'INDEX_NAME',
  indexSettings: { attributesForFaceting: ['can_deliver_quickly', 'restaurant'] },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings =
      IndexSettings(attributesForFaceting = listOf("can_deliver_quickly", "restaurant")),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['attributesForFaceting' => [
        'can_deliver_quickly',

        'restaurant',
    ],
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "attributesForFaceting": [
            "can_deliver_quickly",
            "restaurant",
        ],
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(attributes_for_faceting: ["can_deliver_quickly", "restaurant"])
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      attributesForFaceting = Some(Seq("can_deliver_quickly", "restaurant"))
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(attributesForFaceting: ["can_deliver_quickly", "restaurant"])
)

Send the optional filters with your query. For example:

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      OptionalFilters = new OptionalFilters(
        new List<OptionalFilters> { new OptionalFilters("can_deliver_quickly:true") }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    optionalFilters: [
      "can_deliver_quickly:true",
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetOptionalFilters(search.ArrayOfOptionalFiltersAsOptionalFilters(
    []search.OptionalFilters{*search.StringAsOptionalFilters("can_deliver_quickly:true")})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setOptionalFilters(OptionalFilters.of(Arrays.asList(OptionalFilters.of("can_deliver_quickly:true")))),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { optionalFilters: ['can_deliver_quickly:true'] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        optionalFilters =
          OptionalFilters.of(listOf(OptionalFilters.of("can_deliver_quickly:true")))
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['optionalFilters' => [
        'can_deliver_quickly:true',
    ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "optionalFilters": [
            "can_deliver_quickly:true",
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(optional_filters: ["can_deliver_quickly:true"])
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        optionalFilters = Some(OptionalFilters(Seq(OptionalFilters("can_deliver_quickly:true"))))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(optionalFilters: SearchOptionalFilters
                .arrayOfSearchOptionalFilters([SearchOptionalFilters.string("can_deliver_quickly:true")])))
)

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

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      OptionalFilters = new OptionalFilters(
        new List<OptionalFilters> { new OptionalFilters("restaurant:-Bert's Inn") }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    optionalFilters: [
      "restaurant:-Bert's Inn",
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetOptionalFilters(search.ArrayOfOptionalFiltersAsOptionalFilters(
    []search.OptionalFilters{*search.StringAsOptionalFilters("restaurant:-Bert's Inn")})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject()
    .setQuery("query")
    .setOptionalFilters(OptionalFilters.of(Arrays.asList(OptionalFilters.of("restaurant:-Bert's Inn")))),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', optionalFilters: ["restaurant:-Bert's Inn"] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        query = "query",
        optionalFilters =
          OptionalFilters.of(listOf(OptionalFilters.of("restaurant:-Bert's Inn"))),
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'optionalFilters' => [
            "restaurant:-Bert's Inn",
        ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "optionalFilters": [
            "restaurant:-Bert's Inn",
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "query", optional_filters: ["restaurant:-Bert's Inn"])
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        optionalFilters = Some(OptionalFilters(Seq(OptionalFilters("restaurant:-Bert's Inn"))))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        optionalFilters: SearchOptionalFilters
            .arrayOfSearchOptionalFilters([SearchOptionalFilters.string("restaurant:-Bert's Inn")])
    ))
)

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.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Promote records with optional filters

Update your records

How to apply optional filters

Using the dashboard

Using the API

Optional or facet filters

See also

​Update your records

​How to apply optional filters

​Using the dashboard

​Using the API

​Optional or facet filters

​See also

Update your records

How to apply optional filters

Using the dashboard

Using the API

Optional or facet filters

See also