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 step by step tutorial assumes that RESTHeart is running on localhost with the default configuration: the database restheart is bound to / and the user admin exists with default password secret.

To run RESTHeart please first read the setup section.

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.

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).

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).

> 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.

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.

> GET /inventory?keys={'header.item':1}&keys={'header.status':1}

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

> PUT /inventory/_indexes/item {"keys": {"item": 1}}

> PUT /inventory/_indexes/status {"keys": {"status": 1 }}

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