Search…
Querying
Query Arguments
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
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
Where
The
where argument limits the resulting document list using search criteria applied against indexed properties.1
?where={<query conditions>}
Copied!
See Query Operators for more details and examples of available conditions.
Examples
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
Example Request
Result
1
GET /accounts?where={"name.last": {"$regex": "/^s/i"}}
Copied!
1
{
2
"data": [
3
{
4
"_id": "5888b91d35f8c91536c6ddea",
5
"access": 6,
6
"c_enrollments": [],
7
"c_study_groups": [],
8
"created": "2017-01-25T14:41:33.297Z",
9
"email": "[email protected]",
10
"favorite": false,
11
"gender": "m",
12
"inherited_roles": [
13
"000000000000000000000007",
14
"000000000000000000000006"
15
],
16
"key": {
17
"fingerprint": "8e53d430-e30c-11e6-aaeb-99172490c13b",
18
"secret": "heBcf2Wgh6hjezADTAc88wHJNGcJgwUd"
19
},
20
"locale": "en_US",
21
"locked": false,
22
"mobile": "+12223334449",
23
"name": {
24
"first": "John",
25
"last": "Silver"
26
},
27
"object": "account",
28
"roles": [
29
"000000000000000000000004"
30
],
31
"shared": false,
32
"state": "verified",
33
"updated": "2017-01-25T14:42:54.970Z",
34
"updater": {
35
"_id": "5888b91d35f8c91536c6ddea",
36
"object": "account",
37
"path": "/accounts/5888b91d35f8c91536c6ddea"
38
}
39
}
40
],
41
"hasMore": false,
42
"object": "list"
43
}
Copied!
Sort
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.1
?where={<query conditions>}&sort=<property>
Copied!
Or when specifying the sort order:
1
?where={<query conditions>}&sort={<property>: <sort order>}
Copied!
Or sorting by multiple properties:
1
?where={<query conditions>}&sort={<property1>: <sort order>, <property2>: <sort order>, ...}
Copied!
Examples
The following shows an example of sorting a list of accounts by last name then by first name.
Example Request
Result
1
GET /accounts/?paths[]=name&sort={"name.last": 1, "name.first": 1}
Copied!
1
{
2
"data": [
3
{
4
"_id": "507f1f77bcf86cd799439011",
5
"name": {
6
"first": "John",
7
"last": "Smith"
8
},
9
"object": "account"
10
},
11
{
12
"_id": "55ff9db67a00a89c14aa31a6",
13
"name": {
14
"first": "Stan",
15
"last": "Smith"
16
},
17
"object": "account"
18
},
19
{
20
"_id": "507f191e810c19729de860ea",
21
"name": {
22
"first": "Jane",
23
"last": "Svenson"
24
},
25
"object": "account"
26
},
27
...
28
],
29
"hasMore": true,
30
"object": "list"
31
}
Copied!
Skip
The skip argument lets you specify a number of results to skip in your result set.
1
?where={<query conditions>}&skip=<positive integer>
Copied!
Examples
For example, if you have a result set of 200, and you specify
skip=100, you would receive results 101-200.skip1
GET /accounts/?paths[]=name&skip=2
2
3
{
4
"data": [
5
{
6
"_id": "507f191e810c19729de860ea",
7
"name": {
8
"first": "Jane",
9
"last": "Svenson"
10
},
11
"object": "account"
12
}
13
],
14
"hasMore": false,
15
"object": "list"
16
}
17
18
/* if the full result set was
19
[
20
{
21
"_id": "507f1f77bcf86cd799439011",
22
"name": {
23
"first": "John",
24
"last": "Smith"
25
},
26
"object": "account"
27
},
28
{
29
"_id": "55ff9db67a00a89c14aa31a6",
30
"name": {
31
"first": "Stan",
32
"last": "Smith"
33
},
34
"object": "account"
35
},
36
{
37
"_id": "507f191e810c19729de860ea",
38
"name": {
39
"first": "Jane",
40
"last": "Svenson"
41
},
42
"object": "account"
43
}
44
]
45
*/
Copied!
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.Limit
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.1
?where={<query conditions>}&limit=<positive integer>
Copied!
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.
Examples
1
GET /accounts/?paths[]=name&limit=2
2
3
{
4
"data": [
5
{
6
"_id": "507f1f77bcf86cd799439011",
7
"name": {
8
"first": "John",
9
"last": "Smith"
10
},
11
"object": "account"
12
},
13
{
14
"_id": "55ff9db67a00a89c14aa31a6",
15
"name": {
16
"first": "Stan",
17
"last": "Smith"
18
},
19
"object": "account"
20
}
21
],
22
"hasMore": true,
23
"object": "list"
24
}
Copied!
Paging
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:1
?where={"_id": {"$gt": "561b5a700000000000000000"}}&sort={"_id": 1}
Copied!
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:1
GET /c_conversations?paths[]=_id&limit=2&sort={"_id": 1}
2
3
{
4
"data": [
5
{
6
"_id": "551c76c3bad12f302b343481",
7
"object": "c_conversation"
8
},
9
{
10
"_id": "551c76c4bad12f302b343489",
11
"object": "c_conversation"
12
}
13
],
14
"hasMore": true,
15
"object": "list"
16
}
Copied!
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:1
GET /conversations?paths[]=_id&limit=2&where={"_id": {"$gt": "551c76c4bad12f302b343489"}}&sort={"_id": 1}
2
3
{
4
"data": [
5
{
6
"_id": "551c76c3bad12f302b343492",
7
"object": "c_conversation"
8
},
9
{
10
"_id": "551c76c4bad12f302b343511",
11
"object": "c_conversation"
12
}
13
],
14
"hasMore": true,
15
"object": "list"
16
}
Copied!
List Property Paging
Lists of contexts can be paged by prefixing query arguments with the property name. For example:
1
GET /c_patientfiles/550891732390ac1832f3317f/?paths[]=connections.access&connections.where={"_id":{"$gt":"550b9a25c59c1ef032ab641c"}}
2
3
{
4
"_id": "550891732390ac1832f3317f",
5
"object": "c_patientfile",
6
"connections": {
7
"object": "list",
8
"hasMore": "false",
9
"data: [{
10
"_id": "551ce5dfcd3227a41dfa7e9d",
11
"object": "connection",
12
"access": 2
13
}]
14
}
15
}
Copied!
Last modified 8mo ago