DocumentationAPI Reference

Query Language

Request envelope

AttributeTypeDescription
itemsArray[SearchRequest]multiple SearchRequests (allows for batch querying)

SearchRequest

AttributeTypeDescription
dataQueryRequestsingle QueryRequest to execute

QueryRequest

AttributeTypeDescription
queryQueryDefinition of projections (attributes to fetch for each record), filters to apply on results and sorting options
aggregationsArray[Aggregation]List of aggregations to perform on result set returned by query (after all the filters, including default permission filters, are applied)
suggestionsArray[Suggestion]List of search values for which suggestions are to be found
hitsBooleanindicates whether search results should be returned or not (e.g. in case of aggregation request, single components may not be needed), defaults to true
cursorStringpagination token for stateless iteration over data set
pageIntegerpage number of results to be returned (a page is per_page records), defaults to 0
per_pageIntegermaximum number of records to display at a time, defaults to 50
offsetIntegernumber of results to skip (after all filters and sorting are applied), defaults to 0

Validation rules

  • cursor, offset and page are mutually exclusive
  • page must be non-negative
  • per_page must be within range 0-200

Example query request

POST /v3/deals/search
{	"items": [{		"data": {			"query": {},			"aggregations": [],			"suggestions": [],			"hits": true,			"cursor": "WyJzb21lLWtleXdvcmQiLCJlbnRpdHktdHlwZSMxMjM0NTY3Il0=",			"per_page": 10		}	}]}

Query

AttributeTypeDescription
projectionArray[Attribute]Projection definition: list of attributes to fetch for every record (by default only id and version are fetched, anything else must be requested explicitly)
filterFilterFilters to apply to results set (permissions and visibility filters are always applied whether requested or not, so that user sees only records she has access to)
sortArray[Sort]List of attributes to sort result set on; sorts are applied in order they are specified, meaning if records have the same value of some sort attribute, then the next sort attribute (if defined) is used to order records within that group

Filter

AttributeTypeDescription
andArray[Filter]AND logical operator for filters
orArray[Filter]OR logical operator for filters
notFilterNOT logical operator for filters
filterFilterOperandconcrete filter specifying an attribute and condition it must meet for this filter to match

FilterOperand

AttributeTypeDescription
attributeAttributeattribute to filter records on
parameterFilterOperatorconcrete condition that attribute must meet

FilterOperator

AttributeTypeDescription
anyArray[AnyType]attribute must have one of specified values
allArray[AnyType]attribute must have all of specified values (applies to array attributes)
containsStringattribute must contain specified phrase
starts_withStringattribute must start with specified phrase (limited to 256 characters, longer input will be trimmed to that length)
eqAnyTypeattribute value must be equal to specified
missingBooleanattribute == null must evaluate to missing (same as is_null)
is_nullBooleanattribute == null must evaluate to is_null (same as missing)
rangeRangeattribute value must be within range
geo_distanceGeoDistancegeo point attribute must be within specified range

Validation rules

  • All elements in any or all must be of the same type and that type must match filtered argument type
  • Exactly one of FilterOperators attributes must be non-null
  • Filter type must be allowed by attribute type
TypeAllowed filters
Idany
eq
range
missing
is_null
Versionany
eq
range
graph_expression
PermissionsOwner
PermissionsTeam
PermissionsGroup
any
eq
short
byte
integer
long
double
any
eq
range
missing
is_null
stringstarts_with
any
eq
contains
missing
is_null
booleanany
eq
missing
is_null
date
date-time
any
eq
range
missing
is_null
arrayFilters allowed by type of stored elements, plus additional filter:
all
objectFiltering cannot be done explicitly on an object, but it can be done on it's attributes. If object has filter_field set in mapping, then any filter specified directly on this object will be resolved against that attribute (including type validation).
CustomFieldEvery CustomField has some underlying data type. All of them are described above, and undergo the same rules.
GeoPointgeo_distance

Range

AttributeTypeDescription
gteAnyTypelower range bound (inclusive)
gtAnyTypelower range bound (exclusive)
lteAnyTypeupper range bound (inclusive)
ltAnyTypeupper range bound (exclusive)

Validation rules

  • At most one of lower bounds [gte, gt] may be specified
  • At most one of upper bound [lte, lt] may be specified

GeoDistance

AttributeTypeDescription
distance_metersDecimalradius of circle centred in the from location (in meters)
fromGeoPointcenter of the circle

GeoPoint

AttributeTypeDescription
latDecimallatitude specified in degrees within (-90, 90)
lonDecimallongitude specified in degrees within (-180, 180)

Example filtering request

POST /v3/contacts/search
{	"items": [{		"data": {			"query": {				"filter": {					"and": [						{							"filter": {								"attribute": {									"name": "display_name"								},								"parameter": {									"starts_with": "jane"								}							}						},						{							"filter": {								"attribute": {									"name": "created_at"								},								"parameter": {									"range": {										"gte": "2015-02-01"								}							}							}						}					]				}			}		}	}]}

Sort

AttributeTypeDescription
attributeAttributeattribute to sort by
orderEnumallowed values: ascending, descending

Example sort request

POST /v3/leads/search
{	"items": [{		"data": {			"query": {				"sort": [					{						"attribute": {							"name": "display_name"						},						"order": "ascending"					}				]			}		}	}]}

Aggregations

AttributeTypeDescription
attributeAttributeattribute on which to perform aggregation
aggregation_typeEnumsee below for allowed values

Validation rules

  • Allowed aggregation_type values:
    • sum
    • avg
    • min
    • max
    • count
    • terms
  • Allowed aggregation_types per attribute type
TypeAllowed aggregations
Idnone
Versionsum
avg
min
max
count
short
byte
integer
long
double
sum
avg
min
max
count
terms
string
arrays
CustomField		count
terms
booleancount
terms
date
date-time
count
min
max

Example aggregation request

POST /v3/deals/search
{    "items": [        {            "data": {                "aggregations": [                    {                        "attribute": {                            "name": "decimal_value"                        },                        "aggregation_type": "avg"                    }                ],                "hits": false            }        }    ]}

Suggestion

AttributeTypeDescription
attributeAttributeattribute to apply suggestions to
searchStringsearched phrase (limited to 256 characters, longer input will be trimmed to that length)

Example suggestion request

POST /v3/deals/search
{    "items": [        {            "data": {                "suggestions": [                    {                        "attribute": {                            "name": "name"                        },                        "search": "de"                    }                ],                "hits": false            }        }    ]}

Attribute

AttributeTypeDescription
nameStringname of attribute
missingAnyTypevalue to use (in filtering, sorts and aggregations) if attribute is missing in record

Validation rules

  • name must be defined in mapping for given index (either directly, e.g. display_name for contacts or as field of an object with dot notation, e.g. address.street in contacts)