🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
Guides / Managing results / Refine results / Filtering

Filters and facet filters

On this page

For most uses, the filters parameter is the best choice for filtering. However, numericFilters and facetFilters also offer comparable capabilities and can be used to suit different filtering needs.

Differences between filtering parameters

Whatever filtering parameter you use, the objective is to filter records based on their attributes. However, there are some differences:

filters

  Notes
Parameter filters
Syntax String
Best for Filtering with a mix of string and numeric filters
Key points A familiar SQL syntax. You can use boolean logical operators like AND and OR

Example

Copy 
1
2
3

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

numericFilters

  Notes
Parameter numericFilters
Syntax String
Best for Filtering dates and numeric values
Key points Similar to filters but limited to numeric data

Example

Copy 
1
2
3

index.search('', {
  numericFilters: 'price>20'
});

facetFilters

  Notes
Parameter facetFilters
Syntax String or string array
Best for Filtering with a mix of strings and complex boolean logic
Key points Can’t be used for numeric filtering
  • When you use a single array (["author:Stephen King", "genre:Horror"]), all the conditions in this array are combined with AND logic. It means a record must meet all these conditions to appear in the search results.
  • When you neat arrays ([["author:Stephen King", "genre:Horror"], "publisher:Penguin"]), each inner array is combined with OR logic. Different arrays are combined with AND logic.
  • You can negate facet filters with a minus sign (-) as a prefix (["category:Book", "category:-Movie"]).
  • You can use a simple string to define facet filters (facetFilters: "category:-Ebook")

Examples

Find books that are authored by Stephen King or belong to the horror genre, and are also published by Penguin.

Copy 
1
2
3

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

Exclude eBooks from the results:

Copy 
1
2
3

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

Combining filters and facetFilters

You can combine these filters in the same search query. For example:

Copy 
1
2
3
4

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

The results are those that match both the filters and the facetFilters criteria.

In this case, the results of this are the same as the preceding example for facetFilters but more generally may offer additional flexibility.
For example, you can use filters programmatically to create a reduced set of records based on a user’s profile, and then apply facetFilters to reflect the facets that the user has chosen.

Limits and performance

Since each filter adds complexity to queries, there’s a limit on the total number of combined filters you can use of 1,000.

Faceting on unique or uncommon attributes may degrade search performance and relevance.

Did you find this page helpful?