Optional filters

Unlike filters, optional filters influence ranking without excluding that don’t match them. Records must still match the query and any required filters. Combine optional filters to give results different priorities. Use this to boost results you want to show before others or bury results you want to show last.

Before you begin

Declare each attribute used in optional filters in the attributesForFaceting index setting. Your ranking formula must include the Filters ranking criterion. To run the code examples on this page, install the latest API client.

Optional filters, replicas, and sorting

On standard replicas, a sort-by attribute takes precedence over optional filters. Optional filters can’t override the order determined by that attribute.

Filter scoring

You can add extra nuance to your ranking by specifying scores for different optional filters. For example, you want to display your matching products in the following order:

Apple products first
Samsung products second
Huawei products last

In this scenario, products from any other brand appear after Apple and Samsung products and before Huawei products. You can achieve this by using scored optional filters to boost Apple and Samsung products and negative filters to bury Huawei products. A negative filter negates the filter value. It doesn’t assign a negative numeric score.

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      OptionalFilters = new OptionalFilters(
        new List<OptionalFilters>
        {
          new OptionalFilters("brand:Apple<score=3>"),
          new OptionalFilters("brand:Samsung<score=2>"),
          new OptionalFilters("brand:-Huawei"),
        }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    optionalFilters: [
      "brand:Apple<score=3>",
      "brand:Samsung<score=2>",
      "brand:-Huawei",
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetOptionalFilters(search.ArrayOfOptionalFiltersAsOptionalFilters(
    []search.OptionalFilters{
      *search.StringAsOptionalFilters("brand:Apple<score=3>"),
      *search.StringAsOptionalFilters("brand:Samsung<score=2>"),
      *search.StringAsOptionalFilters("brand:-Huawei"),
    },
  )))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setOptionalFilters(
    OptionalFilters.of(
      Arrays.asList(
        OptionalFilters.of("brand:Apple<score=3>"),
        OptionalFilters.of("brand:Samsung<score=2>"),
        OptionalFilters.of("brand:-Huawei")
      )
    )
  ),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { optionalFilters: ['brand:Apple<score=3>', 'brand:Samsung<score=2>', 'brand:-Huawei'] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        optionalFilters =
          OptionalFilters.of(
            listOf(
              OptionalFilters.of("brand:Apple<score=3>"),
              OptionalFilters.of("brand:Samsung<score=2>"),
              OptionalFilters.of("brand:-Huawei"),
            )
          )
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['optionalFilters' => [
        'brand:Apple<score=3>',

        'brand:Samsung<score=2>',

        'brand:-Huawei',
    ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "optionalFilters": [
            "brand:Apple<score=3>",
            "brand:Samsung<score=2>",
            "brand:-Huawei",
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(
    optional_filters: ["brand:Apple<score=3>", "brand:Samsung<score=2>", "brand:-Huawei"]
  )
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        optionalFilters = Some(
          OptionalFilters(
            Seq(
              OptionalFilters("brand:Apple<score=3>"),
              OptionalFilters("brand:Samsung<score=2>"),
              OptionalFilters("brand:-Huawei")
            )
          )
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(optionalFilters: SearchOptionalFilters
                .arrayOfSearchOptionalFilters([
                    SearchOptionalFilters.string("brand:Apple<score=3>"),
                    SearchOptionalFilters.string("brand:Samsung<score=2>"),
                    SearchOptionalFilters.string("brand:-Huawei"),
                ])))
)

For information about how Algolia turns these scores into a ranking, see Optional filter scores.

Performance

Optional filters are powerful but have some significant performance limitations.

For attributes that you need for filtering but not faceting, use the filterOnly modifier in the attributesForFaceting index setting. For example:

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

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

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

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

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

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

$response = $client->setSettings(
    'INDEX_NAME',
    ['attributesForFaceting' => [
        'filterOnly(brand)',
    ],
    ],
);

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

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

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

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

Prefer attributes with fewer unique values for optional filters. For example, if brand has fewer unique values than product_name, use brand.
Use as few optional filters as possible. Aim for queries to return a smaller result set.
Depending on your plan, it may be possible to apply sharding and other custom settings to optimize your implementation. For more information, contact the support team.

For performance reasons, don’t use filter scoring on searches that may return more than 100,000 results.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Optional filters

Before you begin

Optional filters, replicas, and sorting

Filter scoring

Performance

See also

​Before you begin

​Optional filters, replicas, and sorting

​Filter scoring

​Performance

​See also

Before you begin

Optional filters, replicas, and sorting

Filter scoring

Performance

See also