Documentation API Reference

Query Language

Request envelope

Attribute Type Description
items Array[SearchRequest] multipleSearchRequests (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 byquery(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 totrue
cursor String pagination token for stateless iteration over data set
page Integer page number of results to be returned (a page isper_pagerecords), defaults to0
per_page Integer maximum number of records to display at a time, defaults to50
offset Integer number of results to skip (after all filters and sorting are applied), defaults to0

Validation rules

  • cursor,offsetandpageare mutually exclusive
  • pagemust be non-negative
  • per_pagemust be within range0-200

Example query request

             

              
POST /v3/deals/search

             
             

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

Query

Attribute Type Description
projection Array[Attribute] 投影定义:获取属性的列表for every record (by default onlyidandversionare 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] ANDlogical operator for filters
or Array[Filter] ORlogical operator for filters
not Filter NOTlogical 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 thatattributemust 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 == nullmust evaluate tomissing(same asis_null)
is_null Boolean attribute == nullmust evaluate tois_null(same asmissing)
range Range attribute value must be withinrange
geo_distance GeoDistance 地理点属性必须在指定范围内

Validation rules

  • All elements inanyorallmust be of the same type and that type must match filtered argument type
  • Exactly one ofFilterOperators 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 hasfilter_fieldset 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 thefromlocation (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

  • Allowedaggregation_typevalues:
    • sum
    • avg
    • min
    • max
    • count
    • terms
  • Allowedaggregation_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

  • namemust be defined in mapping for given index (either directly, e.g.display_namefor contacts or as field of an object with dot notation, e.g.address.streetin contacts)