API Reference / API Parameters / filters
Feb. 26, 2019
Type: string
Engine default: "" (no filters)
Parameter syntax
'filters' => 'attribute:value AND | OR | NOT attribute:value'
             'numeric_attribute = | != | > | >= | < | <= numeric_value'
             'attribute:lower_value TO higher_value'
             'facetName:facetValue'
             '_tags:value'
             'attribute:value'

Can be used in these methods:

About this parameter

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

This parameter uses SQL-like syntax, where you can use boolean operators and parentheses to combine individual filters.


Numeric Comparisons

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

The ${value} must be numeric. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages.


Numeric Range

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

${lowerBound} and ${upperBound} must be numeric. Both are inclusive.


Facet filters

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

Facet matching is not case sensitive.

When ${facetName} contains string values, it needs to be declared inside attributesForFaceting


Tag filters

Format: _tags:${value} (or, alternatively, just ${value})
Example: _tags:published

Tag matching is case sensitive.

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.


Boolean filters

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

When ${facetName} needs to be declared inside attributesForFaceting


Boolean operators

Example:

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

Individual filters can be combined via boolean operators. 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

Parentheses, ( and ), can be used for grouping.

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.

For performance reasons, filter expressions are limited to a conjunction (ANDs) of disjunctions (ORs). 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).


Usage notes:

  • Array Attributes: Any attribute set up as an array will match the filter as soon as one of the values in the array match.
  • Keywords are case-sensitive.
  • When to use quotes (simple or double, depending on the language):
    • If a value or attribute name contains spaces (see example).
    • If a value or attribute name conflicts with a keyword (see example).
    • Phrases that includes quotes, like content:"It's a wonderful day" (see example).
    • Phrases that includes quotes, like attribute:"She said "Hello World"" (see example).
  • Nested attributes can be used for filtering, so authors.mainAuthor:"John Doe" is a valid filter, as long as authors.mainAuthor is declared as an attributesForFaceting.

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:

A OR B

Did you find this page helpful?