Filtering¶
Plural endpoints (such as collections) support restricting the set of returned results by means of filters. Filters are predicates that can be expressed by query parameters. Elements of the plural endpoint (such as records) that do not match the predicates are omitted from the response.
Most filters are expressed using a query parameter of the form
[operator_]field=value
. The (optional) operator is one from the
list below. The field name can be simple or a dotted field
name. Values can be any JSON encoded value (e.g. 24
, "hello"
,
[1, 2, 4]
, {"flavor": "strawberry"}
, true
, or
null
). Anything not recognized as a JSON value is interpreted as a
string.
Single value¶
/collection?field=value
Examples:
/collection?author=2
Matches any record whose
author
field is equal to the number 2./collection?author="Ben"
Matches any record whose
author
field is equal to the string Ben./collection?author=Ben
Same as the previous example, but relying on the behavior that anything that isn’t JSON is a string.
/collection?author="2.0"
Matches any record whose
author
field is equal to the string value"2.0"
. This is useful if your records contain something numeric-ish but not quite numeric, like a version number.
It also works with multiple values:
/collection?field=[1,2]
Or even objects:
/collection?field={"checked": true}
Sub-objects¶
/collection?field.subfield=value
Search in array fields¶
/collection?contains_field=value
Matches any records whose
field
array field containsvalue
. Value can be an integer, a string, an object, or a list of such.In the value is a list, it only matches records whose field contains all the values listed.
/collection?contains_any_field=value
Same as the previous filter, but if the value is a list, it matches all records whose field contains at least one of the listed values.
Examples:
/collection?contains_colors=["red","blue"]
Matches any record whose
colors
array field containsred
andblue
elements./collection?contains_any_colors=["red","blue"]
Matches any record whose
colors
array field containsred
orblue
strings./collection?contains_any_aliases=[{"ll": "ls -l"}, {"gti": "git"}]
Matches any record whose
aliases
array field contains{"ll": "ls -l"}
or{"gti": "git"}
objects.
Comparison¶
The filters lt
and gt
are available to compare against values.
/collection?gt_orders=100
Retrieve any records whose
orders
field is (strictly) greater than 100.
This bound is exclusive (i.e., in the previous example, it would not
retrieve a record whose orders
field was equal to 100). To check
“greater than or equal”, use min
. To check “less than or equal”,
use max
.
/collection?min_orders=100
Retrieve any records whose
orders
field is greater than or equal to 100.
At the present time, the comparison order between values of different
types is not defined. For example, if you have a record like
{"author": 1}
and another like {"author": "2"}
, requesting
/collection?gt_author=1
may return the second one, or it may
not. However, a comparison operator will match whatever order you get
by sorting, and the ordering will include all records.
Multiple values¶
Prefix field with in_
and provide comma-separated values.
/collection?in_status=1,2,3
Search string fields¶
Prefix field name with like_
:
/collection?like_field=foo
The specified value can also contain wildchars:
/collection?like_field=foo*
(starts withfoo
)/collection?like_field=*foo
(ends withfoo
)/collection?like_field=*foo*
(equivalent tolike_field=foo
)
Field existence¶
You can request records that have a certain field (for example, author
) using has_author=true
or those that don’t have that field by using has_author=false
.
/collection?has_field=true
Note that a record like {"author": null}
still counts as “having” that field.
Polling for changes¶
Note
The ETag
and Last-Modified
response headers will always be the same as
the unfiltered collection.
One important use of this is when polling for changes.
The _since
parameter is provided as an alias for gt_last_modified
.
/collection?_since=1437035923844
When filtering on last_modified
every deleted records will appear in the
list with a deleted
flag and a last_modified
value that corresponds
to the deletion event.
If the If-None-Match: "<timestamp>"
request header is provided as described in
the section about timestamps and if the
collection was not changed, a 304 Not Modified
response is returned.
Note
The _before
parameter is also available, and is an alias for
lt_last_modified
(strictly inferior).
Note
_since
and_before
also accept a value between quotes ("
) as it would be returned in theETag
response header (see response timestamps)._since
and_before
also accept anull
value, which is equivalent to the parameter not being specified.
Request:
GET /articles?_since=1437035923844 HTTP/1.1
Accept: application/json
Authorization: Basic bWF0Og==
Host: localhost:8000
Response:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, ETag, Next-Page, Last-Modified
Content-Length: 436
Content-Type: application/json; charset=UTF-8
Date: Tue, 28 Apr 2015 12:08:11 GMT
Last-Modified: Mon, 12 Apr 2015 11:12:07 GMT
ETag: "1430222877724"
{
"data": [
{
"id": "dc86afa9-a839-4ce1-ae02-3d538b75496f",
"last_modified": 1430222877724,
"title": "MoCo",
"url": "https://mozilla.com",
},
{
"id": "23160c47-27a5-41f6-9164-21d46141804d",
"last_modified": 1430140411480,
"title": "MoFo",
"url": "https://mozilla.org",
},
{
"id": "11130c47-37a5-41f6-9112-32d46141804f",
"deleted": true,
"last_modified": 1430140411480
}
]
}