Read JSON Documents

Introduction

This page provides examples of query operations using the GET method.

You will learn how to get documents from a collection, optionally specifying a query, sort criteria, fields projections options and deal with pagination.

You will also learn hot to get a single document knowing its _id.

Before running the example requests

The following examples assume RESTHeart Platform running on the localhost with the default configuration: the database restheart is bound to / and the user admin exists with default password secret.

To create the restheart db, run the following:

PUT / HTTP/1.1

The examples on this page use the inventory collection. To create the inventory collection, run the following:

PUT /inventory HTTP/1.1

To populate the inventory collection, run the following:

POST /inventory HTTP/1.1

[
   { "item": "journal", "qty": 25, "size": { "h": 14, "w": 21, "uom": "cm" }, "status": "A" },
   { "item": "notebook", "qty": 50, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "A" },
   { "item": "paper", "qty": 100, "size": { "h": 8.5, "w": 11, "uom": "in" }, "status": "D" },
   { "item": "planner", "qty": 75, "size": { "h": 22.85, "w": 30, "uom": "cm" }, "status": "D" },
   { "item": "postcard", "qty": 45, "size": { "h": 10, "w": 15.25, "uom": "cm" }, "status": "A" }
]

GETting Documents from a Collection

To GET documents in the collection, run the following:

GET /inventory HTTP/1.1

Paging

The response is paginated, i..e. only a subset of the collection’s document is returned in the response array.

The number of documents to return is controlled via the pagesize query parameter. Its default value is 100, maximum allowable 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.

Paging Examples

Return documents on second page when pagesize is 3

GET /inventory?page=2&pagesize=3 HTTP/1.1

Filtering

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

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.

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

Filtering Examples

Return documents whose quantity is more than 50

GET /inventory?filter={"qty":{"$gt":50}} HTTP/1.1

Return documents whose quantity is more than 25 and with status set to “D” value

GET /inventory?filter={"$and":[{"qty":{"$gt":75}},{"status":"D"}]} HTTP/1.1

or equivalently:

GET /inventory?filter={"qty":{"$gt":75}}&filter={"status":"D"} HTTP/1.1

Counting

Use _size keyword after the collection path to retrieve the number of documents that meets the filter condition (if present).

Impact on performances


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

Counting Examples

Return the number of documents into “inventory” collection

GET /inventory/_size?filter={"status":"A"} HTTP/1.1

Sorting

Sorting is controlled by the sort query parameter.

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

Multiple sort properties


Specify multiple sort options using multiple `sort` query parameters

> GET /inventory?sort=qty&sort=-status

Sort simple format

The sort simplified format is :

sort=[ |-]<fieldname>

Sort JSON expression format

sort can also be a MongoDB sort expression.

JSON expression format is available starting from version 2.0.1. See improvement RH-190

sort={"field": 1}

Sorting Examples

Sort by status ascending

GET /inventory?sort=status HTTP/1.1

or equivalently:

GET /inventory?sort={"status":1} HTTP/1.1

Sort by status descending

GET /inventory?sort=-status HTTP/1.1

or equivalently:

GET /inventory?sort={"status":-1} HTTP/1.1

Sort by status ascending and qty descending

GET /inventory?sort=status&sort=-qty HTTP/1.1

or equivalently:

GET /inventory?sort={"status":1,"qty":-1} HTTP/1.1

Sort by search score

This is only possible with json expression format

create a text index

PUT /inventory/_indexes/text HTTP/1.1

{"keys": {"item": "text" }}

sort by score

GET /inventory?filter={"$text":{"$search":"paper"}}&keys={"item":1,"score":{"$meta":"textScore"}}&sort={"score":{"$meta":"textScore"}} HTTP/1.1

Projection

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. 

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

Projection Examples

Only return the property item

GET /inventory?keys={'item':1} HTTP/1.1

Return all but the property item

GET /inventory?keys={'item':0} HTTP/1.1

Only return the properties item and qty

GET /inventory?keys={'item':1}&keys={'qty':1} HTTP/1.1

Hint

Hint allows overriding MongoDB’s default index selection and query optimization process. See cursor hint on MongoDB documentation.

This is done via the hint query parameter.

Specify the index by the index specification document, either using a json document or the compact string representation; specifying the index by name is not supported.

Use $natural to force the query to perform a forwards collection scan.

Hint Examples

Use the index on item field

The following example returns all documents in the collection named coll using the index on the item field.

GET /inventory?hint={'item':1} HTTP/1.1

Use the compound index on age and timestamp fields using the compact string format

The following example returns the documents using the compound index on the item and reverse status fields.

GET /inventory?hint=item&hint=-status HTTP/1.1

Perform a forwards collection scan

The following example returns the documents using a forwards collection scan.

GET /inventory?hint={'$natural':1} HTTP/1.1

Perform a reverse collection scan

The following example returns the documents using a reverse collection scan.

GET /inventory?hint={'$natural':-1} HTTP/1.1