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 and/or tag filters.

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

You must declare each attribute you use as a filter in attributesForFaceting, except for _tags, which we automatically consider as attributesForFaceting.

Numeric Comparisons

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

The ${value} must be numeric.

We support the following operators: <, <=, =, !=, >= 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 case-sensitive on the facet name, but not on the facet value.

When ${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.

If you don’t specify an attribute name, the filter applies to the _tags attribute.

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

When ${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 using boolean operators. We support the following operators:

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

You can use parentheses (( )) for grouping.

For performance reasons, we do not support the following boolean combinations:

  • You cannot mix different filter categories (i.e., facet, tag, and numerical) inside a disjunction (OR). For example, we support facet:value1 OR facet:value2 and num=1 OR num=2, but do not support facet:value OR num=3 OR tag1.

  • You cannot negate a group of filters, only an individual filter. For example, we support NOT filter1, but do not support NOT(filter1 OR filter2).

  • We limit filter expressions to a conjunction (ANDs) of disjunctions (ORs). For example you can use filter1 AND (filter2 OR filter3)), but not ORs of ANDs (e.g. filter1 OR (filter2 AND filter3).

If you are unsure if your syntax is correct, use the filters syntax validator.

Usage notes

  • You can filter on array attributes. In order 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.
  • You can use nested attributes for filtering. For example, authors.mainAuthor:"John Doe" is a valid filter, as long as you declare authors.mainAuthor in attributesForFaceting.
  • You must use quotes in the following cases (single or double, depending on the language):
    • If an attribute name or value contains spaces (see example).
    • If an attribute name or value conflicts with a keyword, e.g., NOT, OR, AND(see example).
    • If an attribute name or value contains single quotes, e.g., content:"It's a wonderful day" (see example).
    • If an attribute name or value contains double quotes, e.g., attribute:"She said "Hello World"" (see example).

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?