🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API Reference / API Parameters / filters
Type: string
Engine default: "" (no filters)
Parameter syntax
'filters' => 'attribute:value [AND | OR | NOT](#boolean-operators) attribute:value'
             'numeric_attribute [= | != | > | >= | < | <=](#numeric-comparisons) numeric_value'
             'attribute:lower_value TO higher_value'
             '[facetName:facetValue](#facet-filters)'
             '_tags:value'
             'attribute:value'

Can be used in these methods:

About this parameter

Filter the query with numeric, facet, or tag filters.

You can use an SQL-like syntax for combining filters with boolean operators and parenthesis.

You must declare every attribute you use as a filter in attributesForFaceting, except _tags, which are automatically included.

Numeric comparisons

  • Format: ${attributeName} ${operator} ${value}
  • Example: price > 12.99

${value} must be numeric.

The following operators are supported: <, <=, =, !=, >= and >.

Numeric range

  • Format: ${attributeName}:${lowerBound} TO ${upperBound}
  • Example: price:5.99 TO 100

${lowerBound} and ${upperBound} must be numeric. Both bounds are included in the range.

Facet filters

  • Format: ${facetName}:${facetValue}
  • Example: category:Book

Facet matching is case-sensitive on the facet name, but not on the facet value.

If ${facetName} contains string values, you need to declare it in attributesForFaceting.

Tag filters

  • Format: _tags:${value} or just ${value}
  • Example: _tags:published

Tag matching is case-sensitive.

For example: public OR user_42 is the same as _tags:public OR _tags:user_42.

Boolean filters

  • Format: facetName:${boolean_value}
  • Example: isEnabled:true

If ${facetName} contains boolean values, you need to declare it in attributesForFaceting.

Boolean operators

Example: price < 10 AND (category:Book OR NOT category:Ebook)

You can combine individual filters with these boolean operators:

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

Use parentheses (( )) for grouping.

The following boolean combinations are NOT supported:

  • You can’t mix different filter categories (facet, tag, numerical), inside a disjunction (OR).

    • Supported: facet:value1 OR facet:value2, num=1 OR num=2
    • Unsupported: facet:value OR num=3 OR tag1
  • You can’t negate a group of filters.

    • Supported: NOT filter1
    • Unsupported: NOT(filter1 OR filter2)
  • Filter expressions can be conjunctions (ANDs) of disjunctions (ORs), but not disjunctions of conjunctions.

    • Supported: filter1 AND (filter2 OR filter3)
    • Unsupported: filter1 OR (filter2 AND filter3).

Use the filters syntax validator to test your filter combinations.

Usage notes

Filtering array attributes

For a filter to match an array attribute, it only needs to match one element of the array.

For example, if a record contains the array attribute genres: ["fiction", "thriller", "sci-fi"], the filter genres:thriller returns this record.

Nested attributes for filtering

For example, authors.mainAuthor:"John Doe" is a valid filter, as long as you declare authors.mainAuthor in attributesForFaceting.

Use of quotes

Use quotes in these cases (single or double, depending on the language):

Advanced queries

Enabling advancedSyntax lets users:

  • Add double quotes around phrases in a query to specify that a record must contain that phrase.
  • Prefix a word with a minus (-) character to specify that a record must not contain that phrase.

Examples

Apply filters on a search query

1
2
3
$index->search('query', [
  'filters' => '(category:Book OR category:Ebook) AND _tags:published'
]);

Apply complex filters

1
2
3
4
5
6
7
8
9
10
$filters = 'available = 1'.
          ' AND (category:Book OR NOT category:Ebook)'.
          ' AND _tags:published'.
          ' AND publication_date:1441745506 TO 1441755506'.
          ' AND inStock > 0'.
          ' AND author:"John Doe"';

$index->search('query', [
  'filters' => $filters
]);

Handle attributes with spaces

1
2
3
$index->search('query', [
  'filters' => "category:'Books and Comics'"
]);

Handle attributes conflicting with keywords

1
2
3
$index->search('query', [
  'filters' => "keyword:'OR'"
]);

Handle attributes with single quotes

1
2
3
$index->search('query', [
  'filters' => "content:'It\\'s a wonderful day'"
]);

Handle attributes with double quotes

1
2
3
$index->search('query', [
  'filters' => "content:'She said \"Hello World\"'"
]);

Filters syntax validator

Type your filter to validate it:


      

Did you find this page helpful?