Documentation API Reference

Filtering

Simple attribute filters

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 whoseis_organisationattribute is set totrueshould be returned.

Note that after adding filteringtotal_countvalue 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_countreturns number of items matched by the filters, that the user has access to.

Fetch contacts

             

              
POST/v3/contacts/search

             
             

              
Authorization:Bearer $ACCESS_TOKENContent-Type:application/json{"items":[{"data":{"query":{"filter":{"filter":{"attribute":{"name":"is_organisation"},"parameter":{"eq":true}}},"projection":[{"name":"is_organisation"},{"name":"display_name"}]}},"per_page":1}]}

             
             

              
Content-Type:application/json; charset=UTF-8{"items":[{"successful":true,"items":[{"data":{"id":9876,"display_name":"Large Company","is_organisation":true,"version":55},"meta":{"type":"contact"}}],"meta":{"count":1,"http_status":"200 OK","links":{"next_page":"nextPageToken=="},"total_count":5634,"type":"collection"}}]}

Complex filters

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.

filtercontains oneandarray element, which consists of two elements:

  • eqfilter onowner.nameattribute, which only matches leads whose owner's name isJohn Doe
  • anotherandfilter, which only matches leads that simultaneously meet two nested conditions:
    • phone_numbers.phoneattribute is missing AND
    • phone_number.mobileattribute is missing

Fetch contacts

             

              
POST/v3/contacts/search

             
             

              
Authorization:Bearer $ACCESS_TOKENContent-Type:application/json{"items":[{"data":{"query":{"filter":{"and":[{"filter":{"attribute":{"name":"owner.name"},"parameter":{"eq":"John Doe"}}},{"and":[{"filter":{"attribute":{"name":"phone_numbers.phone"},"parameter":{"missing":true}}},{"filter":{"attribute":{"name":"phone_numbers.mobile"},"parameter":{"missing":true}}}]}]}}}}]}

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——必须提供所有的属性values (only applies to array attributes)
  • contains-stringorkeywordattribute must contain provided phrase
  • missing- attribute value must not be set (same asis_null)
  • starts_with-stringorkeywordattribute must start with provided phrase
  • eq- attribute value must be same as provided one
  • is_null- attribute value must not be set (same asmissing)
  • 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_withfilter can be applied tostringattributes, but not todate_timeattributes. Contrary,rangefilter makes sense fordate_timeattributes but not forstringones.

More about legal filter/attribute types combinations inQuery language description.