filters
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,
GenerateSecuredApiKey,
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 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
.
Boolean operators
Example: price < 10 AND (category:Book OR NOT category:Ebook)
You can combine individual filters with these boolean operators:
OR
: match any of the combined conditions (disjunction)AND
: match all of the combined conditions (conjunction)NOT
: negate a filter
Use parentheses (( )
) for grouping.
The following boolean combinations are NOT supported:
-
You can’t mix different filter categories (facet, tag, numerical), inside a disjunction (OR).
- Supported:
facet:value1 OR facet:value2
,num=1 OR num=2
- Unsupported:
facet:value OR num=3 OR tag1
- Supported:
-
You can’t negate a group of filters.
- Supported:
NOT filter1
- Unsupported:
NOT(filter1 OR filter2)
- Supported:
-
Filter expressions can be conjunctions (ANDs) of disjunctions (ORs), but not disjunctions of conjunctions.
- Supported:
filter1 AND (filter2 OR filter3)
- Unsupported:
filter1 OR (filter2 AND filter3)
.
- Supported:
Use the filters syntax validator to test your filter combinations.
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):
- Attribute names or values with spaces.
- Attribute names or values conflict with keywords, such as,
NOT
,OR
, orAND
. - Attribute names or values with single quotes, such as
content:"It's a wonderful day"
. - Attribute names or values with double quotes, such as
attribute:"She said "Hello World""
.
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\"'"
]);
Filters syntax validator
Type your filter to validate it: