API Reference / API Parameters / filters
Type: string
Engine default: "" (no filters)
Parameter syntax
'filters' => 'facet:value'
             'NOT facet:value'
             // Optional: prefix with NOT to negate the filter condition
             '_tags:value'
             // Optional: prefix each filter with NOT to negate the filter condition
             'facet:value AND | OR facet:value'
             // Optional: prefix with NOT to negate the numeric filter conditions
             'numericFacet = | != | > | >= | < | <= number'
             'numericFacet:lower_value TO higher_value'

Can be used in these methods:

About this parameter

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

Filter combinations can be created using SQL-style boolean logic, including AND, OR, and parentheses for grouping.

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 names are case-sensitive but the facet value’s case doesn’t matter.

If ${facetName} contains string values, 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, declare it in attributesForFaceting.

Filter by date

Algolia can filter on date attributes, but they must be formatted as Unix timestamps.

Usage notes

Filtering array attributes

Filters on array attributes need only one array element to match. 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\"'"
]);
Did you find this page helpful?