filters
'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:
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
searchAsync,
browseAsync,
deleteByAsync,
searchForFacetValues
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 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
andnum=1 OR num=2
, but do not supportfacet: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 supportNOT(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 filtergenres: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 declareauthors.mainAuthor
inattributesForFaceting
. - 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: