Page tree

RESTHeart 3.0 is the latest stable version.

Skip to end of metadata
Go to start of metadata


In RESTHeart, GET collection resource requests (GET /db/coll) retrieve documents from the collection as embedded resources.

RESTHeart represents resources with the HAL format where resources have state, links and embedded resources. Refer to Representation Format for more information about HAL.

This section also applies to File Bucket and Schema Store resources, that embed File and JSON schema resources respectively.


To retrieve the first 100 documents of a collection:

GET /test/coll?pagesize=100&np
Response (headers omitted)
HTTP/1.1 200 OK

    "_embedded": {
        "rh:doc": [
            { <DOC1> }, { <DOC2> }, { <DOC3> }, ..., { <DOC100> }
    "_returned": 100

default sorting

The query parameter np (No Properties) excludes the collection properties from the response.

default sorting

The default sorting of the documents is by the _id descending.

In the usual case where the type of the ids of the documents is ObjectId, this makes the documents sorted by creation time by default (ObjectId have a timestamp in the most significant bits).

See sorting section to know how to specify a different sorting criterium.


The filter query parameter allows to specify conditions on the documents to return.

The filter qparam value is any mongodb query.

Note that system properties (properties starting with _ that are managed automatically by RESTHeart) are not affected by this option.


Return documents whose title starts with "Star Trek"

GET /test/coll?filter={'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 the string "STAR TREK".

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

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

mutli filter qparams

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}"]


Specifying the count query parameter, RESTHeart returns:

  • the total number of documents in the collection with the _size parameter
  • the total number of available pages with the _total_pages parameter. It also add the last link, i.e. the link to the last page, to the _links; The pagination links (first, last, next, previous) are only returned on hal full mode (hal=f query parameter); see HAL mode for more information.


count involves querying the collection twice: once for counting and once of actually retrieving the data; this has performance implications.


The embedded documents are paginated, i.e. only a subset of the collection's document is returned on each request.

The number of documents to return is controlled via the pagesize query parameter. Its default value is 100, maximum size is 1000.

The pages to return is specified with the page query parameter. The pagination links (first, last, next, previous) are only returned on hal full mode (hal=f query parameter); see HAL mode for more information.

For instance, to return documents from 20 to 29 (page 3):

GET /test/coll?count&page=3&pagesize=10&hal=f&np
Response (headers omitted)
HTTP/1.1 200 OK
    "_embedded": {
        "rh:doc": [
            { <DOC30> }, { <DOC31> }, ... { <DOC39> }
    "_returned": 10,
    "_size": 343
	"_total_pages": 35


Sorting is controlled by the sort_by query parameter.

Note that documents cannot be sorted by system properties (properties starting with _ that are managed automatically by RESTHeart).

sort_by simple format

The sort_by simplified format is :


multiple sort properties

Specify multiple sort options using multiple sort_by query parameters

GET /db/coll?sort_by=name&sort_by=-age

sort_by json expression format

sort_by can also be a MongoDB sort expression.

json expression format is available starting from version 2.0.1. See improvement RH-190
sort_by={"field": 1}


Sort by the date ascending

GET /test/coll?sort_by=date

GET /test/coll?sort_by={"date":1}

Sort by the date descending

GET /test/coll?sort_by=-date

GET /test/coll?sort_by={"date":-1}

Sort by the date descending and title ascending 

GET /test/coll?sort_by=-date&sort_by=title

GET /test/coll?sort_by={"date":-1, "title":1}

Sort by search score

This is only possible with json expression format

// create a text index
PUT /test/coll/_indexes/text {"keys": {"title": "text }}
// sort by {"$meta": "textScore"}
GET /test/coll?filter={"$text":{"$search":"a search string"}}&keys={"title":1,"score":{"$meta":"textScore"}}&sort_by={"score":{"$meta":"textScore"}}


Projection limits the fields to return for all matching documents, specifying the inclusion or the exclusion of fields.

This is done via the keys query parameter. 

projecting multiple keys

Specify multiple keys using multiple keys query parameters

Note that system properties (properties starting with _ that are managed automatically by RESTHeart) are not affected by this option.


Only return the property title

GET /test/coll?keys={'title':1}

Return all but the property title

GET /test/coll?keys={'title':0}

Only return the properties title and summary

GET /test/coll?keys={'title':1}&keys={'summary':1}

It's possible to use the "dot notation" to specify fields within an object, for example, let's say that both title and summary are part of an header object:

GET /test/coll?keys={'header.title':1}&keys={'header.summary':1}
  • No labels