API Reference / API Parameters / facetFilters
Feb. 26, 2019
Type: list of strings
Engine default: []
Parameter syntax
'facetFilters' => [
  'attribute:value', // (single string)

  // attribute1:value AND attribute2:value (multiple strings)
  'attribute1:value', 'attribute2:value'

  // attribute1:value OR attribute2:value (multiple strings within an array)
  ['attribute1:value', 'attribute2:value'],

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ['attribute1:value', 'attribute2:value'], 'attribute3:value',

  ...
]

Can be used in these methods:

About this parameter

Filter hits by facet value.

The filters parameter provides an easier to use, SQL-like syntax, and it supports both filters and facets. We recommend using it instead of facetFilters.

Usage notes:

  • Format: The general format for referencing a facet value is ${attributeName}:${value}. This attribute/value combination represents a filter on a given facet value.

  • Multiple filters: If you specify multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

    • ["category:Book", "author:John Doe"] translates as category:Book AND author:"John Doe".
    • [["category:Book", "category:Movie"], "author:John Doe"] translates as (category:Book OR category:Movie) AND author:"John Doe".
  • Negation is supported by prefixing the value with a minus sign (-), sometimes called a dash. For example: ["category:Book", "category:-Movie"] translates as category:Book AND NOT category:Movie.

  • Escape characters: On the other hand, if your facet value starts with a -, meaning it contains the -, then you can escape the character with a \ to prevent the engine from interpreting this as a negative facet filter. For example, filtering on category:\-Movie will filter on all records that have a category equal to “-Movie”.

Examples

Simple filter on a single facet

This example translates as category:Book.

1
2
3
4
5
$results = $index->search('query', [
  'facetFilters' => [
    "category:Book"
  ]
]);

Simple AND filter

This example translate as category:Book AND author:John Doe.

1
2
3
4
5
6
$results = $index->search('query', [
  'facetFilters' => [
    "category:Book",
    "author:John Doe"
  ]
]);

Simple OR filter

This example translate as (category:Book OR category:Movie).

1
2
3
4
5
$results = $index->search('query', [
  'facetFilters' => [
    ["category:Book", "category:Movie"]
  ]
]);

AND and OR filter combination

This example translate as (category:Book OR category:Movie) AND author:John Doe.

1
2
3
4
5
6
$results = $index->search('query', [
  'facetFilters' => [
    ["category:Book", "category:Movie"],
    "author:John Doe"
  ]
]);

Did you find this page helpful?