Query Language

Request envelope

Attribute	Type	Description
items	Array[SearchRequest]	multiple SearchRequests (allows for batch querying)

SearchRequest

Attribute	Type	Description
data	QueryRequest	single QueryRequest to execute

QueryRequest

Attribute	Type	Description
query	Query	Definition of projections (attributes to fetch for each record), filters to apply on results and sorting options
aggregations	Array[Aggregation]	List of aggregations to perform on result set returned by query (after all the filters, including default permission filters, are applied)
suggestions	Array[Suggestion]	List of search values for which suggestions are to be found
hits	Boolean	indicates whether search results should be returned or not (e.g. in case of aggregation request, single components may not be needed), defaults to true
cursor	String	pagination token for stateless iteration over data set
page	Integer	page number of results to be returned (a page is per_page records), defaults to 0
per_page	Integer	maximum number of records to display at a time, defaults to 50
offset	Integer	number 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

The cursor property is not included in the initial HTTP request. If the search results span multiple pages, this initial request returns a cursor value, which can be used in a subsequent pagination request to retrieve the next page of results.

Example query request

POST /v3/deals/search

{
	"items": [{
		"data": {
			"query": {},
			"aggregations": [],
			"suggestions": [],
			"hits": true,
			"per_page": 10
		}
	}]
}

Query

Attribute	Type	Description
projection	Array[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)
filter	Filter	Filters 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)
sort	Array[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

Attribute	Type	Description
and	Array[Filter]	AND logical operator for filters
or	Array[Filter]	OR logical operator for filters
not	Filter	NOT logical operator for filters
filter	FilterOperand	concrete filter specifying an attribute and condition it must meet for this filter to match

FilterOperand

Attribute	Type	Description
attribute	Attribute	attribute to filter records on
parameter	FilterOperator	concrete condition that attribute must meet

FilterOperator

Attribute	Type	Description
any	Array[AnyType]	attribute must have one of specified values
all	Array[AnyType]	attribute must have all of specified values (applies to array attributes)
contains	String	attribute must contain specified phrase
starts_with	String	attribute must start with specified phrase (limited to 256 characters, longer input will be trimmed to that length)
eq	AnyType	attribute value must be equal to specified
missing	Boolean	attribute == null must evaluate to missing (same as is_null)
is_null	Boolean	attribute == null must evaluate to is_null (same as missing)
range	Range	attribute value must be within range
geo_distance	GeoDistance	geo 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

Type	Allowed filters
Id	any eq range missing is_null
Version	any eq range graph_expression
PermissionsOwner PermissionsTeam PermissionsGroup	any eq
short byte integer long double	any eq range missing is_null
string	starts_with any eq contains missing is_null
boolean	any eq missing is_null
date date-time	any eq range missing is_null
array	Filters allowed by type of stored elements, plus additional filter: all
object	Filtering 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).
CustomField	Every CustomField has some underlying data type. All of them are described above, and undergo the same rules.
GeoPoint	geo_distance

Range

Attribute	Type	Description
gte	AnyType	lower range bound (inclusive)
gt	AnyType	lower range bound (exclusive)
lte	AnyType	upper range bound (inclusive)
lt	AnyType	upper 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

Attribute	Type	Description
distance_meters	Decimal	radius of circle centred in the from location (in meters)
from	GeoPoint	center of the circle

GeoPoint

Attribute	Type	Description
lat	Decimal	latitude specified in degrees within (-90, 90)
lon	Decimal	longitude 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

Attribute	Type	Description
attribute	Attribute	attribute to sort by
order	Enum	allowed values: ascending, descending

Example sort request

POST /v3/leads/search

{
	"items": [{
		"data": {
			"query": {
				"sort": [
					{
						"attribute": {
							"name": "display_name"
						},
						"order": "ascending"
					}
				]
			}
		}
	}]
}

---

Aggregations

Attribute	Type	Description
attribute	Attribute	attribute on which to perform aggregation
aggregation_type	Enum	see below for allowed values

Validation rules

• Allowed aggregation_type values:
  • sum
  • avg
  • min
  • max
  • count
  • terms
• Allowed aggregation_types per attribute type

Type	Allowed aggregations
Id	none
Version	sum avg min max count
short byte integer long double	sum avg min max count terms
string arrays CustomField	count terms
boolean	count 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

Attribute	Type	Description
attribute	Attribute	attribute to apply suggestions to
search	String	searched 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

Attribute	Type	Description
name	String	name of attribute
missing	AnyType	value 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)