Icon searching white

Filtering

Last updated 01 August 2017

Overview

Filters allow you to limit the results returned to a specific subset of your data. In terms of user experience, providing filters enables users to drill down and further refine their search based off certain attribute values. Algolia permits you to filter your data in a wide variety of ways.

Declaring Attributes for Faceting

In order to be able to facet filter by a custom attribute (any attribute other than tags), you will need to add the attribute to your attributesForFaceting list. You can either define attributes for faceting in the dashboard or through the API.

For example, if you wanted to make categories and author attributes available for filtering, you would need to apply the following setting:

index.set_settings({
  'attributesForFaceting': ['category', 'author']
})

If you will only be using the attribute for filtering and not faceting, you can specify this to the engine via a filterOnly() wrapper for improved performance.

index.set_settings({
  'attributesForFaceting': ['filterOnly(category)', 'filterOnly(author)']
})

Filtering

Results can be filtered with numeric, facet and/or tag filters. If a filtered attribute contains an array of values, any matching value will cause the filter to match.

Basic Filtering

Algolia allows you to leverage boolean operators and parentheses to combine individual filters, similar to SQL expression syntax.

The following operators are supported:

  • OR: must match any of the combined conditions (disjunction)
  • AND: must match all of the combined conditions (conjunction)
  • NOT: negate a filter

Finally, parentheses, ( and ), can be used for grouping.

For example, if you would like your retrieved products to be either books or ebooks, as well as by the author JK Rowling, your query would look like this:

index.search({
  filters: '(category:Book OR category:Ebook) AND author:"JK Rowling"'
});

There are a few caveats to keep in mind:

  • If no attribute name is specified, the filter applies to _tags. For example: public OR user_42 will translate into _tags:public OR _tags:user_42.
  • For performance reasons, filter expressions are limited to a disjunction of conjunctions. In other words, you can have ANDs of ORs (e.g. filter1 AND (filter2 OR filter3)), but not ORs of ANDs (e.g. filter1 OR (filter2 AND filter3).
  • You cannot mix different filter categories inside a disjunction (OR). For example, num=3 OR tag1 OR facet:value is not allowed.
  • You cannot negate a group of filters, only an individual filter. For example, NOT(filter1 OR filter2) is not allowed.

Negative Filters

In order to exclude a subset of items matching a certain filter from a list of results, you will need to negate the filter using NOT. For example, to retrieve all books that are not also ebooks, you would use this filter:

index.search({
  filters: 'category:Book OR NOT category:Ebook'
});

Filter by Numerical Value

Algolia allows you to numerically filter results either via a comparison or a range, as long as the operand is a numeric value.

Comparison

Comparison operators can be used to retrieve results matching a specified numeric condition based on a supplied attribute. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages. For example, it’s possible to restrict the search to all in stock items with the following filter:

index.search({
  filters: 'stock_quantity > 0'
});

Range

By specifying a lower and upper bound for an attribute, it’s possible to return a range of matching results. The range bounds are inclusive on both ends. As an example, retrieving all results between the years 2011 and 2017 would require this type of filter:

index.search({
  filters: 'year: 2011 TO 2017'
});

Filter by Tag Values

The _tags attribute is reserved for filtering by tag values. _tags:published (or, alternatively published) would match all objects containing exactly the keyword “published” in their _tags attribute. Tag filtering is mainly used for programmatic filtering.

Filter by Date

By default the engine doesn’t interpret strings following the ISO date format. To enable filtering by date, you must convert your dates into numeric values (generally a UNIX timestamp).

Facet Filters

While it’s generally easier to use the filter syntax, it is possible to filter hits by facet value using the facetFilters parameter. This syntax is especially useful if you need to leverage filter scoring capabilites. In the case of multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), you will need to use a nested array.

For example, a filter that would retrieve either books or ebooks by the author JK Rowling would be written like this:

index.search({
  facetFilters: [["category:Book", "category:Ebook"], "author:JK Rowling"]
});

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

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

Filters Scoring

Algolia provides the ability to rank records by facet filter scores. As an example, consider a case where a user has created a portfolio, and assigned an interest level score to certain companies. By leveraging filter scores and the sumOrFiltersScores parameter, it’s possible to rank items with the highest summed filter score first.

Here’s what this query might look like:

index.search({
  facetFilters: "(company:Google<score=3>, company:Amazon<score=2>, company:Facebook<score=1>)",
  sumOrFiltersScores: true
});

Results that contained the companies Google, Amazon, and Facebook as company attributes would rank highest, as they would have a score of 6. Results containing only the company Facebook would rank lowest, with a score of 1.

What’s Next

Continue building your Algolia knowledge with these concepts:

If you want to get started implementing filters, we have a tutorial you might find helpful:

© Algolia - Privacy Policy