Result set may be narrowed to records satisfying some condition. Filtering is done
on per-attribute basis. Only items whose attributes meet given conditions are returned.
Basic filter consists of two elements: description of the attribute and the condition
attribute with given name must meet. Let’s consider query only for companies. This means
only records whose is_organisation attribute is set to true should be returned.
Note that after adding filtering total_count value has changed. This always
returns number of items matching query. If query contains no filters, it returns
number of all records user sending the request has access to. When additional filters
are applied, total_count returns number of items matched by the filters, that
the user has access to.
Filters can get arbitrarily complex, allowing to implement very wide range of custom behaviors.
Let’s now consider example data quality check pipeline, in which an organization wants to check
how many leads without any phone number were added by given sales rep. This can
be expressed by following filter query.
filter contains one and array element, which consists of two elements:
eq filter on owner.name attribute, which only matches leads whose owner’s name is John Doe
another and filter, which only matches leads that simultaneously meet two nested conditions:
phone_numbers.phone attribute is missing AND
phone_number.mobile attribute is missing
Filters can generally be divided into two categories:
Attribute filters, that describe condition a single attribute should meet. There are 10 types of attribute filters:
any - attribute must have one of provided values
all - attribute must have all of provided values (only applies to array attributes)
contains - string or keyword attribute must contain provided phrase
missing - attribute value must not be set (same as is_null)
starts_with - string or keyword attribute must start with provided phrase
eq - attribute value must be same as provided one
is_null - attribute value must not be set (same as missing)
range - attribute value must be within specified range
geo_distance - attribute point must be within specified range from some point (only applies to geo-point attributes)
graph_expression - attribute value must be in result set of some graph expression (more about graph expressions in related section)
Compound filters, that aggregate or modify behavior of other filters (compound or attribute)
and - describes array of filters, all of which must match in order for this filter to match
or - describes array of filters, at least one of which must match in order for this filter to match
not - wraps single filter, that must not match for this filter to mat
Not every combination of attribute type and filter type is legal, e.g. starts_with
filter can be applied to string attributes, but not to date_time attributes.
Contrary, range filter makes sense for date_time attributes but not for string ones.
More about legal filter/attribute types combinations in
Query language description.