Querying
Last updated
Last updated
Objects can be queried using the available query arguments, allowing developers to easily search large amounts using the API.
Query arguments are applied in the following order: where, sort, skip, limit
The where
argument limits the resulting document list using search criteria applied against indexed properties.
See Query Operators for more details and examples of available conditions.
For example, the following call finds all accounts where the last name starts with the letter s (case-insensitive) and sorts by last name, then by first name.Example
Sorting can be applied to indexed properties, or to any named property when a grouping is applied. The value can be a single property name sort=total
, or a JSON object containing
one or more property names with either 1 (ascending) or -1 (descending) as the value.
Or when specifying the sort order:
Or sorting by multiple properties:
The following shows an example of sorting a list of accounts by last name then by first name.
The skip argument lets you specify a number of results to skip in your result set.
For example, if you have a result set of 200, and you specify skip=100
, you would receive results 101-200.skip
Limitations of paging with skip
Paging using skip
should only be used for small result sets of a few hundred or less. For paging larger result sets, see Paging.
The limit argument allows you to specify a number of results to return, e.g. limit=2
. The default limit for an API request is 100. The max limit is 1000.
If you are dealing with a result set larger than 1000, you should either narrow your result set with a more specific where clause or use pagination to page through your full result set.
Most API calls that result in a list response can be paged by using the hasMore
property when it is true
. Paging results can be accomplished using limit
and where
query arguments or a combination of where
, limit
and skip
query arguments.
The recommended method for paging is using indexed, unique identifiers such as _id
, sorting by the identifier and applying a where argument. For example:
If forced to sort by non-unique fields, like name.last
, it is possible to fall back on using the skip
argument for paging, though it is not as efficient as using a unique indexed field. Additionally, paging using skip
is only effective for small result sets (e.g. less than a few hundred records).
In the below example, we have a custom "Conversation" object. Suppose there are 20 conversations available to a user. An initial call to GET /conversations?paths[]=_id&limit=2&sort={"_id": 1}
results in the following response:
The response's hasMore
property is true, so the caller knows there are more results. The last _id
in the list is used in the next where
argument like this:
Lists of contexts can be paged by prefixing query arguments with the property name. For example:
Name
Description
Example
where
Accepts A JSON object containing operators and expressions used to limit the search results.
where={“$and”: [{“created”: {“$gt”: “2015-01-01T00:00:00.000Z”}}, {“created”: {“$lt”: “2015-06-01T00:00:00.000Z”}}]}
sort
Used to sort results, can be an indexed property name or a named grouping (when group is used). Also accepts a JSON object containing one or more properties, the values of which must be 1 for ascending and -1 for descending.
sort=posts or sort={“posts”: 1, “_id”: 1}
skip
An integer representing the number of results to skip. Useful for paging where mapping or groupings have been applied, or where search the search criteria cannot be paged using unique fields.
skip=100
limit
An integer representing the number of results to return.
limit=20