API Reference / API Parameters / filters
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, 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.

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\"'"
]);
Did you find this page helpful?