Filters and Facet Filters

As an alternative to the filters parameter, you can use other parameters that provide nearly the same functionality. They include facetFilters for strings and booleans, and numericFilters for numbers and dates.

Whether you use the filters parameter or the combination facetFilters and numericFilters parameters, the functionality is mostly the same - to filter records based on certain attributes. However,there are some differences:

• Their syntax is different
• You cannot use facet filtering on numbers, so you’ll need to use a second parameter (numericFilters)

For most developers, the filters parameter will be easier to use because of its familiar SQL syntax as well as its ability to mix string and numeric filters within the same parameter.

One suggestion is to use facetFilters when handling frontend faceting. But this is not necessary - all facet filtering can be handled by filters.

Syntax difference between filters and facetFilters

The first difference is that filters needs to be a string and facetFilters needs to be an array.

1
2
3
index.search('', {
  filters: 'author:"Stephen King"'
});

1
2
3
4
5
index.search('', {
  facetFilters: [
    "author:Stephen King"
  ]
});

Multiple filters

The syntax for multiple filtering is also different.

For filtering, you use ANDs and ORs when combining more than one filter.

1
2
3
index.search('', {
  filters: '("author:Stephen King" OR "genre:Horror") AND "publisher:Penguin"'
});

For facet filtering, all you need to do is list the attributes using brackets. Without brackets, the entire list is interpreted as combining filters with AND. Within brackets [,], the list is interpreted with ORs.

So the equivalent facet filtering for the above is as follows:

1
2
3
index.search('', {
  facetFilters: [["author:Stephen King", "genre:Horror"], "publisher:Penguin"]
});

Note that in the case of multiple filters, every value within the main bracket is interpreted as a conjunction (AND). If you want to use a disjunctive (OR), you will need to use a nested array (for example: ["author:Stephen King", "genre:Horror"]).

Additionally, Algolia allows you to negate facet filters using a minus sign (-), sometimes called a dash. In this example, ebooks would be excluded from the results.

1
2
3
index.search('', {
  facetFilters: "category:-Ebook"
});

Combining filters and facetFilters within the same search

You can also combine filters and facetFilters. There is one rule: we combine them using AND - meaning, we take the set of filters from each parameter and link them with AND.

So, continuing with our above query, we get the same results with the following:

1
2
3
4
 index.search('', {
   filters: '("author:Stephen King" OR "genre:Horror")',
   facetFilters: ["publisher:Penguin"]
 });

Which is the equivalent of saying “Search all penguins books AND which are either written by stephen king OR in the genre horror”.

There are many reasons to do this. For example, you can create filters programmatically to create a reduced recordset based on a user’s profile, and then apply facetFilters to reflect the facets that the user has chosen.

Limits on the number of filters

Filtering adds complexity to queries, and as such, the total number of filters (including filters, facetFilters, optionalFilters, etc.) is limited to 1000.

Using facets for attributes that are unique or uncommon may degrade search performance and relevance. See the facets usage notes for more information.