Filtering documents

To filter the documents (or files) embedded in a collection (or bucket) representation, use the filter query parameter.

The value of the filter query parameter is any * MongoDB query

RESTHeart use the stric mode representation of BSON: in some cases, notably the ObjectId, the property type must be specified. See example 1.


how to use the ObjectId is filters

http -a a:a GET"{'_id':{'\$oid':'56053ea1c2e6b6654c501db2'}}"

the backslash prepending $oid is only needed in Linux or MacOS terminals, that whould interpret it as an environmental variable, thus need to be escaped.

  • the condition {'_id':{'$oid':'56053ea1c2e6b6654c501db2'}} checks the _id to be an ObjectId
  • the condition {'_id':'56053ea1c2e6b6654c501db2'} checks the _id to be a String

return the document whose _id is title starts with “Star Trek”

$ http GET "{'title':{'$regex':'(?i)^STAR TREK.*'}}"

return documents whose title starts with “Star Trek”

$ http GET "{'title':{'$regex':'(?i)^STAR TREK.*'}}"

This query uses the mongodb $regex operator where the i option performs a case-insensitive match for documents with title value that starts with “star trek”.

documents whose title starts with “Star Trek” and publishing_date is later than 4/9/2015, 8AM

$ http -a a:a GET "{'$and':[{'title': {'$regex':'(?i)^STAR TREK.*'}, {'publishing_date':{'$gte':{'$date':'2015-09-04T08:00:00Z'}}}]}"
$ http -a a:a GET "{'title':{'$regex':'(?i)^STAR TREK.*'}&filter={'publishing_date':{'$gte':{'$date':'2015-09-04T08:00:00Z'}}}"

Note the second form of the last example. If multiple filter query parameters are specified, they are logically composed with the AND operator. This can be very useful in conjunction with path based security permission. For instance the following permission can be used with the simple file based Access Manager to restrict users to GET a collection only specifying a filter on the author property to be equal to their username: regex[pattern="/test/coll/\?.*filter={'author':'(.*?)'}.*", value="%R", full-match=true] and equals[%u, "${1}"]

Documentation references

How to use the examples

The examples make use of the brilliant httpie CLI HTTP client and are ment to be used with RESTHeart stareted on the localhost without the authentication enabled.

Eventually pass username and password with the -a username:password option.