facetFilters
[]
'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:
search,
browseObjects,
deleteBy,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
browse_objects,
delete_by,
search_for_facet_values,
generate_secured_api_key,
add_api_key,
update_api_key
search,
browseObjects,
deleteBy,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
browse_objects,
delete_by,
search_for_facet_values,
generate_secured_api_key,
add_api_key,
update_api_key
search,
browse,
deleteBy,
searchForFacetValues,
generateSecuredApiKey,
addAPIKey,
updateAPIKey
search,
browseObjects,
deleteObjectBy,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
Browse,
DeleteBy,
SearchForFacetValues,
GenerateSecuredApiKeys,
AddApiKey,
UpdateApiKey
Search,
browse,
deleteBy,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
BrowseObjects,
DeleteBy,
SearchForFacetValues,
GenerateSecuredAPIKey,
AddAPIKey,
UpdateAPIKey
search,
browse index,
delete by,
search into facet values,
generateSecuredApiKey,
add key,
update key
About this parameter
Filter hits by facet value.
It’s recommended that you use the filters
parameter instead of facetFilters
since filters
has a more straightforward, SQL-like syntax,
and supports both filters and facets.
The general format for referencing a facet value is ${attributeName}:${value}
. This attribute/value combination represents a filter on a given facet value.
Usage notes
Multiple filters
If you specify multiple filters, Algolia interprets them as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.
["category:Book", "author:John Doe"]
translates ascategory:Book AND author:"John Doe"
.[["category:Book", "category:Movie"], "author:John Doe"]
translates as(category:Book OR category:Movie) AND author:"John Doe"
.- You can’t filter nested ORs of ANDs conditions. For example, you can’t generate a filter for
(category:Book AND category:Movie) OR author:"John Doe"
Escape characters
If your facet value starts with a -
character, you must escape the character with a \
character to prevent Algoliafrom interpreting this as a negative facet filter.
For example, the facet filter category:\-Movie
returns all records with the category “-Movie”.
Negative numbers
To filter negative numbers, escape the minus with a \
character to prevent Algolia from interpreting this as a negative facet filter.
Filtering on count:\-12
returns records with both string (“-12”) and numeric values (-12).
To return only records with numeric values, use numericFilters
: this treats the minus sign (-
) as a negative, so you can use count=-12
to retrieve all records with a count of -12.
Range filters
To filter on a range of numbers, use the filters
parameter and set numeric upperBound
and lowerBound
limits on that parameter.
Negation
Prefix a value with a minus sign (-
) to exclude records with that facet value.
For example: ["category:Book", "category:-Movie"]
translates as category:Book AND NOT category:Movie
.
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
Simple filter on a single facet
An example of filtering on category:Book
.
1
2
3
4
5
$results = $index->search('query', [
'facetFilters' => [
"category:Book"
]
]);
Simple AND filter
An example of filtering on 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
An example of filtering on (category:Book OR category:Movie)
.
1
2
3
4
5
$results = $index->search('query', [
'facetFilters' => [
["category:Book", "category:Movie"]
]
]);
AND and OR filter combination
An example of filtering on (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"
]
]);